justinluu132/claude-code

Docker Overview

Claude Code — Amazon Q Developer to Claude API bridge with production-ready containerized deployment.

---

Architecture

┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                          Docker Compose Stack                                                    │
├──────────────────┬──────────────────────┬────────────────────────────┬─────────────────────────────────────────┤
│   POSTGRES       │      BACKEND         │        FRONTEND            │         OBSERVABILITY STACK             │
│  (PostgreSQL 16) │   (Python 3.11)      │      (Node.js 20)          │                                         │
│                  │                      │                            │  ┌─────────────────────────────────────┐ │
│  ┌────────────┐  │  ┌───────────────┐   │  ┌──────────────────┐      │  │ Grafana (3001) - Dashboards        │ │
│  │ PostgreSQL │◄─┼──│ FastAPI Server│◄──┼──│ Next.js 16 App   │      │  │ Prometheus (9090) - Metrics         │ │
│  │  Database  │  │  │ Amazon Q Bridge│  │  │ React 19 UI      │      │  │ Loki (3100) - Log Aggregation      │ │
│  └────────────┘  │  │ + Metrics     │   │  └──────────────────┘      │  │ Jaeger (16686) - Tracing           │ │
│       │          │  │ (Port 9464)   │   │         │                  │  │ Promtail - Log Shipping             │ │
│       ▼          │  └───────────────┘   │         ▼                  │  └─────────────────────────────────────┘ │
│   Port 5432      │    Port 8000         │    Port 3000               │                                         │
└──────────────────┴──────────────────────┴────────────────────────────┴─────────────────────────────────────────┘
         │                                                                                    │
         ▼                                                                                    ▼
  ┌──────────────┐                                                                    ┌─────────────────┐
  │ postgres_data│                                                                    │ Observability   │
  │   Volume     │                                                                    │ Data Volumes:   │
  └──────────────┘                                                                    │ - loki_data     │
                                                                                      │ - prometheus_data│
                                                                                      │ - grafana_data  │
                                                                                      └─────────────────┘

---

Quick Start

1. Prerequisites

• Docker Engine 20.10+
• Docker Compose V2

2. Pull from Docker Hub

bash
docker pull justinluu132/claude-code:latest

📦 Docker Hub: https://hub.docker.com/r/justinluu132/claude-code

3. Configuration

Create a .env file in the project root:

bash
# Required
ADMIN_PASSWORD="your-secure-password"

# Mode Configuration
MODE="development"             # "development" or "production"

# Optional - Database
# Note: docker-compose.yml sets DATABASE_URL to PostgreSQL by default
# You can override it here if needed:
# DATABASE_URL=""              # Empty = SQLite (./data/data.sqlite3)
# DATABASE_URL="postgresql://user:pass@host/db"  # Custom PostgreSQL
# DATABASE_URL="mysql://user:pass@host/db"       # MySQL

# Optional - Advanced
MAX_ERROR_COUNT=100
TOKEN_COUNT_MULTIPLIER=1.0
HTTP_PROXY=""
SSL_VERIFY="true"              # Set to "false" to disable SSL verification
ENABLE_CONSOLE="true"
FRONTEND_URL="http://localhost:3000"
PORT=8000

4. Launch

bash
# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

5. Access

---

Services

PostgreSQL Service

yaml
postgres:
  image: postgres:16-alpine
  environment:
    POSTGRES_DB: claude_code
    POSTGRES_USER: claude_user
    POSTGRES_PASSWORD: claude_password
  volumes:
    - postgres_data:/var/lib/postgresql/data
  ports:
    - "5432:5432"
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U claude_user -d claude_code"]
    interval: 10s
    timeout: 5s
    retries: 5
  restart: unless-stopped

Features:

• PostgreSQL 16 Alpine for minimal footprint
• Health checks for service readiness
• Persistent data storage via named volume
• Automatic restart on failure

Backend Service

yaml
backend:
  build: .
  ports:
    - "8000:8000"
    - "9464:9464"  # Prometheus metrics
  env_file:
    - .env
  environment:
    - DATABASE_URL=postgresql://claude_user:claude_password@postgres:5432/claude_code
    - JAEGER_HOST=jaeger
    - LOKI_URL=http://loki:3100
  depends_on:
    postgres:
      condition: service_healthy
    jaeger:
      condition: service_started
    loki:
      condition: service_started
  restart: unless-stopped
  logging:
    driver: "json-file"
    options:
      max-size: "10m"
      max-file: "3"
      labels: "service,environment"
      tag: "{{.Name}}/{{.ID}}"

Features:

• Claude API compatible endpoints (/v1/messages)
• Amazon Q Developer integration with streaming
• Multi-database support (SQLite, PostgreSQL, MySQL)
• Token management with rate limiting and scopes
• Account management & AWS OIDC authentication
• Health checks at /healthz
• Conversation persistence and management
• Usage analytics and monitoring
• Prometheus metrics endpoint at port 9464
• Distributed tracing with Jaeger integration
• Structured logging with JSON format and log rotation
• Runs as non-root user (app)
• Waits for PostgreSQL and observability services before starting

Frontend Service

yaml
frontend:
  build:
    context: ./frontend
    args:
      BACKEND_URL: http://backend:8000
  ports:
    - "3000:3000"
  environment:
    - BACKEND_URL=http://backend:8000
  depends_on:
    - backend
  restart: unless-stopped

Features:

• Next.js 16 with React 19 and Turbopack
• Full ***-style chat interface
• Real-time streaming responses with thinking mode
• Conversation management with AI-generated titles
• Admin dashboard with tabbed interface
• Token usage analytics and monitoring
• Server-side rendering with standalone build
• Runs as non-root user (nextjs)

Observability Services

Jaeger - Distributed Tracing

yaml
jaeger:
  image: jaegertracing/all-in-one:1.50
  ports:
    - "16686:16686"  # UI
    - "6831:6831/udp"  # Agent (thrift)
    - "14268:14268"  # Collector HTTP
  environment:
    - COLLECTOR_ZIPKIN_HOST_PORT=:9411
    - COLLECTOR_OTLP_ENABLED=true
  restart: unless-stopped

Grafana Loki - Log Aggregation

yaml
loki:
  image: grafana/loki:2.9.0
  ports:
    - "3100:3100"
  command: -config.file=/etc/loki/local-config.yaml
  volumes:
    - loki_data:/loki
    - ./observability/loki-config.yaml:/etc/loki/local-config.yaml:ro
  restart: unless-stopped

Promtail - Log Shipper

yaml
promtail:
  image: grafana/promtail:2.9.0
  volumes:
    - /var/lib/docker/containers:/var/lib/docker/containers:ro
    - /var/run/docker.sock:/var/run/docker.sock:ro
    - ./observability/promtail-config.yaml:/etc/promtail/config.yaml:ro
  command: -config.file=/etc/promtail/config.yaml
  depends_on:
    - loki
  restart: unless-stopped

Prometheus - Metrics Collection

yaml
prometheus:
  image: prom/prometheus:v2.47.0
  ports:
    - "9090:9090"
  command:
    - '--config.file=/etc/prometheus/prometheus.yml'
    - '--storage.tsdb.path=/prometheus'
    - '--web.console.libraries=/usr/share/prometheus/console_libraries'
    - '--web.console.templates=/usr/share/prometheus/consoles'
  volumes:
    - ./observability/prometheus.yml:/etc/prometheus/prometheus.yml:ro
    - prometheus_data:/prometheus
  restart: unless-stopped

Grafana - Visualization and Dashboards

yaml
grafana:
  image: grafana/grafana:10.1.0
  ports:
    - "3001:3000"
  environment:
    - GF_SECURITY_ADMIN_PASSWORD=admin
    - GF_USERS_ALLOW_SIGN_UP=false
    - GF_SERVER_ROOT_URL=http://localhost:3001
  volumes:
    - grafana_data:/var/lib/grafana
    - ./observability/grafana/provisioning:/etc/grafana/provisioning:ro
  depends_on:
    - prometheus
    - loki
    - jaeger
  restart: unless-stopped

---

Data Persistence

Volume Configuration

yaml
volumes:
  postgres_data:
  loki_data:
  prometheus_data:
  grafana_data:

The Docker Compose setup uses named volumes for data persistence:

• postgres_data - PostgreSQL database storage
• loki_data - Loki log storage
• prometheus_data - Prometheus metrics storage
• grafana_data - Grafana dashboards and configuration

Multi-Database Support

bash
# PostgreSQL (Docker Compose default)
DATABASE_URL="postgresql://claude_user:claude_password@postgres:5432/claude_code"

# SQLite (alternative - requires ./data directory mount)
DATABASE_URL=""

# MySQL (alternative)
DATABASE_URL="mysql://user:password@host:3306/dbname"

Backup

bash
# PostgreSQL backup (Docker Compose default)
docker-compose exec postgres pg_dump -U claude_user claude_code > backup_$(date +%Y%m%d).sql

# Restore PostgreSQL backup
cat backup_20231201.sql | docker-compose exec -T postgres psql -U claude_user claude_code

# For SQLite (if using DATABASE_URL="")
docker-compose stop backend
cp ./data/data.sqlite3 ./backup/data.sqlite3.$(date +%Y%m%d)
docker-compose start backend

---

Health Monitoring

Backend Health Check

dockerfile
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')"

Check Container Health

bash
# View health status
docker-compose ps

# Check specific container
docker inspect --format='{{.State.Health.Status}}' claude-code-backend-1

# Monitor system health
curl http://localhost:8000/healthz

---

Environment Variables

---

API Endpoints

Claude API Compatibility

bash
# Chat completions (Claude API compatible)
POST /v1/messages

# Streaming support
POST /v1/messages (with stream: true)

Management APIs

bash
# Account management
GET/POST/PUT/DELETE /api/accounts

# Token management with scopes
GET/POST/PUT/DELETE /api/tokens

# Conversation management
GET/POST/PUT/DELETE /api/conversations

# Authentication
POST /api/auth/login
POST /api/auth/refresh

---

Production Deployment

With Reverse Proxy (Recommended)

yaml
# docker-compose.prod.yml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: claude_code
      POSTGRES_USER: claude_user
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    # No external port exposure - internal only
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U claude_user -d claude_code"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  backend:
    build: .
    expose:
      - "8000"
    environment:
      - MODE=production
      - DATABASE_URL=postgresql://claude_user:${POSTGRES_PASSWORD}@postgres:5432/claude_code
    depends_on:
      postgres:
        condition: service_healthy
    # Remove ports mapping - only internal access

  frontend:
    build:
      context: ./frontend
      args:
        BACKEND_URL: http://backend:8000
    expose:
      - "3000"
    depends_on:
      - backend
    # Remove ports mapping - only internal access

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - frontend
      - backend

volumes:
  postgres_data:

Resource Limits

yaml
services:
  postgres:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M

  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 256M

  frontend:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M

---

Commands Reference

bash
# Pull latest image
docker pull justinluu132/claude-code:latest

# Start services (detached)
docker-compose up -d

# View logs
docker-compose logs -f
docker-compose logs -f postgres
docker-compose logs -f backend
docker-compose logs -f frontend

# Stop services
docker-compose down

# Restart a service
docker-compose restart backend
docker-compose restart postgres

# Rebuild and restart
docker-compose up -d --build

# Remove all data (⚠️ destructive)
docker-compose down -v

# Shell into containers
docker-compose exec postgres /bin/bash
docker-compose exec backend /bin/bash
docker-compose exec frontend /bin/sh

# Check resource usage
docker stats

# Database operations (PostgreSQL)
docker-compose exec postgres psql -U claude_user -d claude_code

# Database operations (SQLite - if using DATABASE_URL="")
docker-compose exec backend sqlite3 /app/data/data.sqlite3

---

Troubleshooting

Container won't start

bash
# Check logs for all services
docker-compose logs postgres
docker-compose logs backend
docker-compose logs frontend

# Verify .env file exists and has correct MODE
cat .env

# Check port conflicts
lsof -i :5432
lsof -i :8000
lsof -i :3000

Database issues

bash
# Check PostgreSQL is running and healthy
docker-compose ps postgres

# Check PostgreSQL logs
docker-compose logs postgres

# Test PostgreSQL connection
docker-compose exec postgres pg_isready -U claude_user -d claude_code

# For SQLite (if using DATABASE_URL="")
mkdir -p ./data
chmod 755 ./data

Frontend can't connect to backend

bash
# Verify backend is healthy
curl http://localhost:8000/healthz

# Check internal network
docker-compose exec frontend wget -q -O - http://backend:8000/healthz

# Verify API endpoints
curl http://localhost:8000/v1/messages -X POST -H "Content-Type: application/json"

Authentication issues

bash
# Check MODE setting
docker-compose exec backend env | grep MODE

# Verify admin password
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}'

---

Image Size

---

Features

Chat Interface

• Full ***-style UI with conversation management
• Real-time streaming responses with thinking mode visualization
• AI-generated conversation titles
• Message persistence and history

Admin Dashboard

• Token management with scopes and rate limiting
• Account management with usage analytics
• System monitoring and health checks
• Audit logging and security features

API Compatibility

• Full Claude API compatibility (/v1/messages)
• Amazon Q Developer integration with streaming
• Multi-database support for scalability
• Production-ready authentication and authorization

---

Contact

For questions, issues, or support:

📧 Email: ***

---