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

```bash
cd 
cp .env.development .env
```

### 2. Configure Database Connection

Edit `.env` file with your Oracle database credentials:

```env
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)

```bash
./ssh_tunnel.sh start
```

### 4. Build and Start Services

```bash
# 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

```bash
# 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

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

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

### 2. Create Production Secrets

```bash
# 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`:

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

### 4. Deploy to Production

```bash
# 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

```bash
# 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:

```bash
# 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

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

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

### Frontend Development

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# Restart all services
docker-compose restart

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

#### Full Recovery

```bash
# Stop everything
docker-compose down

# Clean up
docker system prune -f

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

### Performance Tuning

#### Development

```bash
# 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

```bash
# 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

```bash
# 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:

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

### Environment-Specific Overrides

Create custom compose files:

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

### Adding New Services

```yaml
# 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

```bash
# 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*