Skip to content

docker-setup.md

Latest commit

 

History

History
331 lines (230 loc) · 7.86 KB

docker-setup.md

File metadata and controls

331 lines (230 loc) · 7.86 KB

Docker Setup Guide

Overview

This guide explains how to set up and run ImaForm using Docker and Docker Compose. Docker provides a consistent environment for development and production deployments.

Prerequisites

Required Software

Hardware Requirements

  • Minimum: 8GB RAM, 2 CPU cores
  • Recommended: 16GB RAM, 4 CPU cores
  • GPU: NVIDIA GPU with CUDA support (optional but recommended for geometry engine)

Operating System

  • Windows 10/11 (with WSL2)
  • macOS 10.15+ (with Docker Desktop)
  • Linux (Ubuntu 20.04+, Debian 11+, etc.)

Quick Start

1. Clone the Repository

git clone https://github.com/your-org/imaform.git
cd imaform

2. Configure Environment Variables

# Copy environment file template
cp docker/.env.example docker/.env

# Edit the .env file with your configuration
nano docker/.env

Important: Update the following values in .env:

  • SECRET_KEY: Generate a secure key with openssl rand -hex 32
  • DATABASE_URL: Update if using external database
  • REDIS_URL: Update if using external Redis
  • CORS_ORIGINS: Add your domain for production

3. Build Docker Images

# Build all images
./scripts/docker/build.sh

# Or build with options
./scripts/docker/build.sh --no-cache --pull

4. Start Containers

# Start all containers (detached)
./scripts/docker/up.sh

# Or start in foreground to see logs
./scripts/docker/up.sh --foreground

5. Verify Services

# Check health of all services
./scripts/docker/health-check.sh

6. Access the Application

Development Setup

For development with hot reload, use the development scripts:

# Start development containers with hot reload
./scripts/dev/docker/dev-up.sh

# Rebuild specific service
./scripts/dev/docker/rebuild.sh --service backend

# Stop development containers
./scripts/dev/docker/dev-down.sh

Hot Reload Features

  • Frontend: Next.js hot reload enabled
  • Backend: Uvicorn auto-reload enabled
  • Celery Worker: Auto-reload enabled

Development Workflow

  1. Make code changes in your local directory
  2. Changes are automatically reflected in containers (via volume mounts)
  3. View logs: ./scripts/docker/logs.sh --follow
  4. Restart service if needed: ./scripts/dev/docker/rebuild.sh --service <service>

Production Setup

For production deployment:

# 1. Configure production environment
nano docker/.env
# Set ENVIRONMENT=production
# Update SECRET_KEY with a secure value

# 2. Configure SSL certificates (optional but recommended)
mkdir -p docker/nginx/ssl
# Place cert.pem and key.pem in docker/nginx/ssl/

# 3. Start production containers
./scripts/deploy/docker/prod-up.sh

# 4. Wait for services to be ready
./scripts/docker/wait-for-services.sh --timeout 300

Production Considerations

  • SSL/TLS: Configure SSL certificates in docker/nginx/ssl/
  • Environment: Set ENVIRONMENT=production in .env
  • Secrets: Use strong, randomly generated secrets
  • Backups: Set up regular backups using ./scripts/deploy/docker/backup.sh
  • Monitoring: Configure monitoring and alerting

Service Management

View Logs

# View all logs
./scripts/docker/logs.sh

# Follow logs in real-time
./scripts/docker/logs.sh --follow

# View specific service logs
./scripts/docker/logs.sh --service backend --follow

Stop Services

# Stop all containers
./scripts/docker/down.sh

# Stop and remove volumes (WARNING: Data loss)
./scripts/docker/down.sh --volumes

Clean Up

# Remove all containers, volumes, and images
./scripts/docker/clean.sh --volumes --images --cache

# Clean without confirmation
./scripts/docker/clean.sh --force

Backup Data

# Backup database and storage
./scripts/deploy/docker/backup.sh --type all

# Backup only database
./scripts/deploy/docker/backup.sh --type database

# Backup only storage
./scripts/deploy/docker/backup.sh --type storage

Troubleshooting

Container Won't Start

Problem: Container fails to start immediately

Solutions:

  1. Check logs: ./scripts/docker/logs.sh --service <service>
  2. Verify environment variables in docker/.env
  3. Check port conflicts: netstat -tuln | grep LISTEN (Linux) or netstat -an (Mac/Windows)
  4. Verify Docker is running: docker ps

Out of Memory

Problem: Containers are killed due to OOM (Out of Memory)

Solutions:

  1. Increase Docker memory limit in Docker Desktop settings
  2. Reduce worker concurrency in .env: CELERY_WORKER_CONCURRENCY=1
  3. Stop unused containers: docker system prune -f

GPU Not Available

Problem: Geometry engine can't access GPU

Solutions:

  1. Verify NVIDIA driver is installed: nvidia-smi
  2. Check Docker GPU support: docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi
  3. Ensure CUDA_VISIBLE_DEVICES is set in .env
  4. Restart Docker Desktop with GPU support enabled

Database Connection Failed

Problem: Backend can't connect to PostgreSQL

Solutions:

  1. Check PostgreSQL is running: docker ps | grep postgres
  2. Verify database URL in .env
  3. Check PostgreSQL logs: ./scripts/docker/logs.sh --service postgres
  4. Wait for PostgreSQL to be ready: ./scripts/docker/wait-for-services.sh --service postgres

Permission Denied

Problem: Can't write to storage directory

Solutions:

  1. Check storage directory permissions: ls -la storage/
  2. Fix permissions: chmod -R 777 storage/ (development only)
  3. Ensure storage directory exists: mkdir -p storage/{uploads,exports,cache}

Advanced Configuration

Custom Ports

Edit docker/.env to change default ports:

NGINX_HTTP_PORT=8080
POSTGRES_PORT=5433
REDIS_PORT=6380

External Services

Configure ImaForm to use external PostgreSQL or Redis:

DATABASE_URL=postgresql+asyncpg://user:pass@external-host:5432/dbname
REDIS_URL=redis://external-host:6379/0

GPU Configuration

Configure GPU usage in .env:

CUDA_VISIBLE_DEVICES=0  # Use GPU 0
# or
CUDA_VISIBLE_DEVICES=0,1  # Use GPUs 0 and 1
# or
CUDA_VISIBLE_DEVICES=""  # Disable GPU (CPU only)

Performance Tuning

Backend Workers

Adjust worker count based on available CPU cores:

CELERY_WORKER_CONCURRENCY=4  # 4 workers

Uvicorn Workers

Backend runs with 4 workers by default. Adjust in docker/backend/Dockerfile:

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "8"]

PostgreSQL Performance

Tune PostgreSQL in docker/docker-compose.yml:

postgres:
  command:
    - "postgres"
    - "-c"
    - "max_connections=200"
    - "-c"
    - "shared_buffers=256MB"

Security Best Practices

  1. Never commit .env to version control
  2. Use strong, random secrets: openssl rand -hex 32
  3. Enable SSL/TLS in production
  4. Restrict CORS origins: Only allow your domain
  5. Regular updates: Keep Docker images updated
  6. Monitor logs: Check for suspicious activity
  7. Backup regularly: Schedule automated backups

Next Steps

Support

For issues or questions: