job-forge/docs/infrastructure/docker_setup.md

Docker Setup Guide - Job Forge

Overview

Job Forge uses Docker for containerization to ensure consistent environments across development, testing, and production. This guide covers Docker configuration, best practices, and troubleshooting.

Docker Architecture

Container Structure

Job Forge Docker Setup
├── jobforge-app      # FastAPI + Dash application
├── postgres          # PostgreSQL 16 with pgvector
└── nginx            # Reverse proxy and SSL termination

Network Configuration

• Internal Network: Docker compose creates isolated network
• External Access: Only nginx container exposes ports 80/443
• Service Discovery: Containers communicate via service names

Development Setup

1. Prerequisites

# Install Docker and Docker Compose
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

2. Environment Configuration

# Copy environment template
cp .env.example .env

# Edit for development
nano .env

# Development Environment Variables
DATABASE_URL="postgresql://jobforge:jobforge123@postgres:5432/jobforge"
CLAUDE_API_KEY="your-claude-api-key"
OPENAI_API_KEY="your-openai-api-key"
JWT_SECRET="development-secret-key-change-in-production"
DEBUG=true
LOG_LEVEL="DEBUG"

3. Docker Compose Configuration

docker-compose.yml

version: '3.8'

services:
  # FastAPI + Dash Application
  jobforge-app:
    build: 
      context: .
      dockerfile: Dockerfile
    container_name: jobforge-app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://jobforge:jobforge123@postgres:5432/jobforge
      - CLAUDE_API_KEY=${CLAUDE_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - JWT_SECRET=${JWT_SECRET}
      - DEBUG=${DEBUG:-false}
      - LOG_LEVEL=${LOG_LEVEL:-INFO}
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      # Development: mount source for hot reload
      - ./app:/app/app:ro
      - ./uploads:/app/uploads
      - ./logs:/var/log/jobforge
    networks:
      - jobforge-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  # PostgreSQL with pgvector
  postgres:
    image: pgvector/pgvector:pg16
    container_name: jobforge-postgres
    environment:
      - POSTGRES_DB=jobforge
      - POSTGRES_USER=jobforge
      - POSTGRES_PASSWORD=jobforge123
      - POSTGRES_INITDB_ARGS="--encoding=UTF8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8"
    ports:
      - "5432:5432"  # Expose for development access
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init_db.sql:/docker-entrypoint-initdb.d/init_db.sql:ro
      - ./backups:/backups
    networks:
      - jobforge-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U jobforge -d jobforge"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  # Nginx Reverse Proxy
  nginx:
    image: nginx:alpine
    container_name: jobforge-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./ssl:/etc/nginx/ssl:ro
      - ./static:/var/www/static:ro
    depends_on:
      - jobforge-app
    networks:
      - jobforge-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "nginx", "-t"]
      interval: 30s
      timeout: 10s
      retries: 3

networks:
  jobforge-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

volumes:
  postgres_data:
    driver: local

docker-compose.override.yml (Development)

# Development overrides
version: '3.8'

services:
  jobforge-app:
    build:
      target: development  # Multi-stage build target
    environment:
      - DEBUG=true
      - LOG_LEVEL=DEBUG
      - RELOAD=true
    volumes:
      # Enable hot reload in development
      - ./app:/app/app
      - ./tests:/app/tests
    command: ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

  postgres:
    environment:
      - POSTGRES_PASSWORD=jobforge123  # Simpler password for dev
    ports:
      - "5432:5432"  # Expose port for development tools

4. Dockerfile Configuration

Multi-stage Dockerfile

# Multi-stage Dockerfile for Job Forge
FROM python:3.12-slim as base

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PYTHONPATH="/app" \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1

# Install system dependencies
RUN apt-get update && apt-get install -y \
    curl \
    postgresql-client \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Development target
FROM base as development

# Install development dependencies
COPY requirements-dev.txt .
RUN pip install --no-cache-dir -r requirements-dev.txt

# Copy source code
COPY . .

# Create non-root user
RUN adduser --disabled-password --gecos '' jobforge && \
    chown -R jobforge:jobforge /app
USER jobforge

# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

EXPOSE 8000

# Development command with hot reload
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

# Production target
FROM base as production

# Copy source code
COPY app/ ./app/
COPY alembic/ ./alembic/
COPY alembic.ini .

# Create non-root user
RUN adduser --disabled-password --gecos '' jobforge && \
    chown -R jobforge:jobforge /app && \
    mkdir -p /var/log/jobforge && \
    chown jobforge:jobforge /var/log/jobforge

USER jobforge

# Health check
HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

EXPOSE 8000

# Production command
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

.dockerignore

# .dockerignore for Job Forge
__pycache__/
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
.venv/
pip-log.txt
pip-delete-this-directory.txt
.git/
.gitignore
README.md
.env
.env.*
docker-compose*.yml
Dockerfile*
.pytest_cache/
htmlcov/
.coverage
*.log
logs/
backups/
uploads/
!uploads/.gitkeep
.vscode/
.idea/
*.swp
*.swo
*~

Production Setup

1. Production Docker Compose

# docker-compose.prod.yml
version: '3.8'

services:
  jobforge-app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - CLAUDE_API_KEY=${CLAUDE_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - JWT_SECRET=${JWT_SECRET}
      - DEBUG=false
      - LOG_LEVEL=INFO
      - WORKERS=4
    volumes:
      - ./uploads:/app/uploads
      - ./logs:/var/log/jobforge
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

  postgres:
    image: pgvector/pgvector:pg16
    environment:
      - POSTGRES_DB=${DB_NAME}
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backups:/backups:ro
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.25'
          memory: 256M
    # Don't expose port in production
    # ports:
    #   - "5432:5432"

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/prod.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 128M

2. Production Commands

# Build production images
docker-compose -f docker-compose.prod.yml build

# Start production services
docker-compose -f docker-compose.prod.yml up -d

# Scale application containers
docker-compose -f docker-compose.prod.yml up -d --scale jobforge-app=3

Container Management

1. Basic Operations

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# Restart specific service
docker-compose restart jobforge-app

# View logs
docker-compose logs -f jobforge-app
docker-compose logs --tail=100 postgres

# Execute commands in container
docker-compose exec jobforge-app bash
docker-compose exec postgres psql -U jobforge -d jobforge

2. Database Operations

# Run database migrations
docker-compose exec jobforge-app alembic upgrade head

# Create new migration
docker-compose exec jobforge-app alembic revision --autogenerate -m "description"

# Database backup
docker-compose exec postgres pg_dump -U jobforge jobforge > backup.sql

# Database restore
docker-compose exec -T postgres psql -U jobforge -d jobforge < backup.sql

3. Application Management

# Update application code (development)
docker-compose restart jobforge-app

# Rebuild containers
docker-compose build
docker-compose up -d

# View container resource usage
docker stats

# Clean up unused resources
docker system prune -a -f

Monitoring and Debugging

1. Health Checks

# Check container health
docker-compose ps

# Manual health check
curl http://localhost:8000/health

# Check individual services
docker-compose exec jobforge-app python -c "import requests; print(requests.get('http://localhost:8000/health').json())"

2. Log Management

# View application logs
docker-compose logs -f jobforge-app

# View specific timeframe
docker-compose logs --since="2024-01-01T00:00:00" jobforge-app

# Export logs
docker-compose logs jobforge-app > app.log

# Follow logs with timestamps
docker-compose logs -f -t jobforge-app

3. Performance Monitoring

# Container resource usage
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}"

# Container processes
docker-compose exec jobforge-app ps aux

# Database performance
docker-compose exec postgres psql -U jobforge -d jobforge -c "SELECT * FROM pg_stat_activity;"

Troubleshooting

1. Common Issues

Container Won't Start

# Check logs for errors
docker-compose logs jobforge-app

# Check if ports are in use
sudo netstat -tulpn | grep :8000

# Check Docker daemon
sudo systemctl status docker

Database Connection Issues

# Test database connectivity
docker-compose exec jobforge-app python -c "
import asyncio
import asyncpg
asyncio.run(asyncpg.connect('postgresql://jobforge:jobforge123@postgres:5432/jobforge'))
print('Database connection successful')
"

# Check database is ready
docker-compose exec postgres pg_isready -U jobforge

Volume Mount Issues

# Check volume permissions
ls -la uploads/ logs/

# Fix permissions
sudo chown -R $USER:$USER uploads logs
chmod 755 uploads logs

2. Debug Mode

# Run container in debug mode
docker-compose run --rm jobforge-app bash

# Run with environment override
docker-compose run -e DEBUG=true jobforge-app

# Attach to running container
docker-compose exec jobforge-app bash

3. Network Issues

# Check network connectivity
docker network ls
docker network inspect jobforge_jobforge-network

# Test inter-container communication
docker-compose exec jobforge-app ping postgres
docker-compose exec nginx ping jobforge-app

Optimization

1. Image Optimization

# Use multi-stage builds to reduce image size
# Use .dockerignore to exclude unnecessary files
# Use specific base image versions
# Combine RUN commands to reduce layers
# Clean up package caches

2. Resource Limits

# Set appropriate resource limits
deploy:
  resources:
    limits:
      cpus: '1.0'
      memory: 1G
    reservations:
      cpus: '0.5'
      memory: 512M

3. Volume Optimization

# Use bind mounts for development
# Use named volumes for persistent data
# Regular cleanup of unused volumes
docker volume prune

Security Best Practices

1. Container Security

# Run as non-root user
USER jobforge

# Use specific image versions
FROM python:3.12-slim

# Don't expose unnecessary ports
# Use secrets for sensitive data

2. Network Security

# Use custom networks
networks:
  jobforge-network:
    driver: bridge
    internal: true  # For internal services

3. Environment Security

# Use .env files for secrets
# Don't commit secrets to version control
# Use Docker secrets in production
# Regular security updates

This Docker setup provides a robust, scalable, and maintainable containerization solution for Job Forge, suitable for both development and production environments.