Skip to main content

Docker Deployment

Deploy ChemAudit using Docker Compose for a complete development environment with all services configured and ready to use.

Architecture​

ChemAudit's Docker deployment includes:

  • Frontend: React SPA (port 3002 in development)
  • Backend: FastAPI application (port 8001 in development)
  • PostgreSQL: Database (port 5432, internal only)
  • Redis: Cache and message broker (port 6379, internal only)
  • Celery Workers: Background job processing
  • Nginx: Reverse proxy (port 80 in production)
  • Prometheus (optional): Metrics collection
  • Grafana (optional): Monitoring dashboards

Development Setup​

Prerequisites​

  • Docker Engine 24.0+
  • Docker Compose 2.20+
  • 4 GB RAM minimum (8 GB recommended)
  • 20 GB disk space

Quick Start​

# Clone repository
git clone https://github.com/Kohulan/ChemAudit.git
cd chemaudit

# Create environment file
cp .env.example .env
# Edit .env to set required secrets

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

Access points:

Environment Configuration​

Edit .env to configure required secrets:

# Database
POSTGRES_PASSWORD=your_secure_password

# Redis (authentication required)
REDIS_PASSWORD=your_redis_password
REDIS_URL=redis://:${REDIS_PASSWORD}@redis:6379/0

# Application
SECRET_KEY=your_secret_key
API_KEY_ADMIN_SECRET=your_admin_secret
CSRF_SECRET_KEY=your_csrf_secret

# Monitoring (optional)
GRAFANA_PASSWORD=your_grafana_password

Generate secure secrets:

openssl rand -hex 32
Local Redis Conflict

If you have a local Redis server running (e.g., via Homebrew), stop it before starting Docker Compose to avoid port conflicts:

brew services stop redis  # macOS
sudo systemctl stop redis  # Linux

Service Overview​

ServiceDescriptionPorts
frontendReact development server3002
backendFastAPI application8001
postgresPostgreSQL database5432 (internal)
redisCache and broker6379 (internal)
celery-workerBackground processingNone

Common Commands​

Start Services​

# Start all services
docker-compose up -d

# Start with monitoring
docker-compose --profile monitoring up -d

# Start specific service
docker-compose up -d backend

View Logs​

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

# Last 100 lines
docker-compose logs --tail=100 backend

Stop Services​

# Stop all services
docker-compose down

# Stop and remove volumes (deletes data)
docker-compose down -v

Restart Services​

# Restart all services
docker-compose restart

# Restart specific service
docker-compose restart backend

Execute Commands​

# Access backend shell
docker-compose exec backend bash

# Run database migrations
docker-compose exec backend alembic upgrade head

# Access PostgreSQL
docker-compose exec postgres psql -U chemaudit

Troubleshooting​

Port already in use:

Change ports in docker-compose.yml:

ports:
  - "3003:3002"  # Map to different host port

Services won't start:

# Check service status
docker-compose ps

# View detailed logs
docker-compose logs backend

# Rebuild images
docker-compose build --no-cache
docker-compose up -d

Redis authentication errors:

If you see Authentication required in backend logs:

# Ensure REDIS_PASSWORD is set in .env
grep REDIS .env

# REDIS_URL must include the password:
# REDIS_URL=redis://:your_password@redis:6379/0

# Restart after fixing
docker-compose restart

Database connection errors:

# Verify PostgreSQL is running
docker-compose exec postgres pg_isready

# Check connection from backend
docker-compose exec backend python -c "from app.database import engine; print('Connected!')"

Next Steps​