roa2web-service-auto/docs/DOCKER_SETUP.md

ROA2WEB Docker Setup Guide

This guide covers how to set up and run ROA2WEB using Docker and Docker Compose for both development and production environments.

📋 Prerequisites

• Docker (20.10+)
• Docker Compose (2.0+)
• Git
• 4GB+ available RAM
• 10GB+ available disk space

Windows/WSL2 Users

• WSL2 with Ubuntu/Debian
• Docker Desktop for Windows with WSL2 backend

🚀 Quick Start (Development)

1. Clone and Setup Environment

cd 
cp .env.development .env

2. Configure Database Connection

Edit .env file with your Oracle database credentials:

ORACLE_USER=CONTAFIN_ORACLE
ORACLE_PASSWORD=your_password_here
ORACLE_HOST=localhost  # via SSH tunnel
ORACLE_PORT=1521
ORACLE_SID=ROA

3. Start SSH Tunnel (if needed)

./ssh_tunnel.sh start

4. Build and Start Services

# Build images and start services
docker-compose up --build

# Or run in background
docker-compose up -d --build

5. Access the Application

• Frontend: http://localhost:8080 (via Nginx Gateway)
• Backend API: http://localhost:8000 (direct access)
• Frontend Direct: http://localhost:3000 (direct access)
• Redis: http://localhost:6379 (direct access)

6. View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f roa-backend
docker-compose logs -f roa-frontend
docker-compose logs -f roa-gateway

🏭 Production Deployment

1. Prepare Production Environment

# Copy production template
cp .env.production .env.production.local

# Edit with your production values
nano .env.production.local

2. Create Production Secrets

# Create secrets directory
mkdir -p secrets/

# Add your production secrets
echo "your_oracle_password" > secrets/oracle_password.txt
echo "your_jwt_secret_key" > secrets/jwt_secret_key.txt
echo "your_redis_password" > secrets/redis_password.txt

# Secure the secrets
chmod 600 secrets/*.txt

3. Configure SSL Domain

Update .env.production.local:

DOMAIN=your-domain.com
SSL_EMAIL=admin@your-domain.com

4. Deploy to Production

# Using deployment script (recommended)
./scripts/deploy.sh

# Or manually
docker-compose -f docker-compose.yml -f docker-compose.production.yml up -d --build

5. Verify Deployment

# Check services health
./scripts/health-check.sh

# Check individual services
curl http://localhost/health
curl http://localhost/api/health

🛠️ Development Workflow

Hot Reload Development

The development setup includes hot reload for both frontend and backend:

# Start with override (development config)
docker-compose up

# Backend code changes in reports-app/backend/app/ are reflected immediately
# Frontend code changes in reports-app/frontend/src/ trigger rebuild

Database Changes

# Restart backend after database schema changes
docker-compose restart roa-backend

# View backend logs
docker-compose logs -f roa-backend

Frontend Development

# Rebuild frontend after package changes
docker-compose build roa-frontend
docker-compose up -d roa-frontend

# Access frontend directly for debugging
# http://localhost:3000

📊 Monitoring and Maintenance

Health Checks

# Comprehensive health check
./scripts/health-check.sh full

# Quick service check
./scripts/health-check.sh quick  

# Continuous monitoring
./scripts/health-check.sh watch

Backup and Restore

# Full backup
./scripts/backup.sh full

# Database only
./scripts/backup.sh database

# List backups
./scripts/backup.sh list

# Restore from backup
./scripts/backup.sh restore backup_20240131_143022

Log Management

# View real-time logs
docker-compose logs -f

# View logs with timestamps
docker-compose logs -t

# Export logs
docker-compose logs > roa2web_logs_$(date +%Y%m%d).log

🔧 Troubleshooting

Common Issues

1. Port Already in Use

# Check what's using the port
sudo netstat -tlnp | grep :8080

# Stop the conflicting service or change ports in docker-compose.override.yml

2. Database Connection Failed

# Check SSH tunnel status
./ssh_tunnel.sh status

# Restart SSH tunnel
./ssh_tunnel.sh restart

# Test database connection
docker-compose exec roa-backend python -c "from shared.database.oracle_pool import test_connection; test_connection()"

3. Frontend Build Errors

# Clear node_modules and rebuild
docker-compose build --no-cache roa-frontend

# Check frontend logs
docker-compose logs roa-frontend

4. SSL Certificate Issues (Production)

# Generate test certificates
docker-compose exec roa-gateway /usr/local/bin/ssl-renew.sh

# Check certificate status
docker-compose exec roa-gateway openssl x509 -in /etc/letsencrypt/live/your-domain.com/cert.pem -text -noout

Service Recovery

Quick Recovery

# Restart all services
docker-compose restart

# Rollback to previous version
./scripts/rollback.sh quick

Full Recovery

# Stop everything
docker-compose down

# Clean up
docker system prune -f

# Restart fresh
docker-compose up -d --build

Performance Tuning

Development

# Allocate more memory to Docker
# Docker Desktop: Settings > Resources > Memory (recommend 4GB+)

# Disable unnecessary services in development
# Comment out services in docker-compose.override.yml

Production

# Monitor resource usage
docker stats

# Scale services
docker-compose -f docker-compose.yml -f docker-compose.production.yml up -d --scale roa-backend=2

# Optimize images
docker image prune -f
docker volume prune -f

🔒 Security

Development Security

• Never commit actual credentials to version control
• Use .env files that are gitignored
• SSH tunnel provides secure database access

Production Security

• Use Docker secrets for sensitive data
• Enable SSL/TLS with valid certificates
• Regular security updates
• Monitor logs for suspicious activity

# Update base images
docker-compose pull
docker-compose up -d --build

# Security scan
docker scout cves backend:latest

📚 Advanced Configuration

Custom Nginx Configuration

Edit nginx/conf/sites-enabled/roa2web.conf for custom routing:

# Add custom location
location /custom-api/ {
    proxy_pass http://custom-service:3000/;
    proxy_set_header Host $host;
}

Environment-Specific Overrides

Create custom compose files:

# docker-compose.staging.yml
version: '3.8'
services:
  roa-backend:
    environment:
      - DEBUG=false
      - LOG_LEVEL=INFO

Adding New Services

# Add to docker-compose.yml
services:
  new-service:
    build: ./new-service
    networks:
      - roa-network
    depends_on:
      - roa-backend

📞 Support

Getting Help

1. Check logs: docker-compose logs
2. Run health check: ./scripts/health-check.sh
3. Review this documentation
4. Check GitHub issues
5. Contact the development team

Useful Commands Reference

# Quick commands
docker-compose up -d        # Start services in background
docker-compose down         # Stop and remove containers
docker-compose ps           # Show running services
docker-compose exec roa-backend sh  # Access backend container

# Maintenance
docker system df            # Show Docker disk usage
docker system prune -f      # Clean up unused resources
docker-compose pull         # Update base images
docker-compose build --no-cache  # Rebuild without cache

---

Last updated: $(date +%Y-%m-%d) ROA2WEB Docker Setup Guide v1.0