Docker Health Check Workflow

This skill helps with Docker-related development, testing, and deployment.

When to use this skill

• Building Docker images for backend
• Running backend in containerized environment
• Debugging Docker deployment issues
• Validating Docker health before deployment
• Testing production-like environment locally

Quick Commands

make docker-build   # Build backend Docker image
make docker-test    # Run comprehensive Docker health checks
make db-start       # Start PostgreSQL Docker container
make db-stop        # Stop PostgreSQL (keeps data)

Development Database (Docker)

Start Database

make db-start

This starts PostgreSQL in Docker:

• Port: 5432 (main), 5433 (test)
• User: postgres
• Password: postgres
• Database: arive_dev, manageros_test
• Volume:

  pgdata

  (persisted)

CRITICAL: Database Persistence

The development database uses Docker volumes for data persistence:

• Volume name:

  pgdata

• NEVER delete this volume in development

• make db-stop

  stops container but PRESERVES data
• NEVER run

  docker compose down -v

  (destroys data)
• Database state persists across container restarts

Database Management

make db-start       # Start PostgreSQL container
make db-stop        # Stop container (keeps data)
make db-upgrade     # Apply migrations
make db-migrate     # Create new migration

# Check database status
docker ps | grep postgres
docker volume ls | grep pgdata

Backend Docker Image

Build Image

make docker-build

This builds the production backend image:

• Base: Python 3.13 slim
• Package manager: uv
• Entry point: Litestar app
• Includes: Database migrations, compiled email templates
• Tag:

  arive-backend:latest

What's Included

• Python application code
• uv-managed dependencies
• Alembic migrations
• Compiled email templates (HTML)
• Litestar ASGI server

What's NOT Included

• Frontend (deployed separately to Vercel)
• Development tools
• Test files
• Source email templates (only compiled HTML)

Docker Health Check

Run Health Checks

make docker-test

This performs comprehensive validation:

1. Build check: Verifies Docker image builds successfully
2. Container start: Starts backend + database containers
3. Health endpoint: Checks

   /health

   returns 200 OK
4. Database connectivity: Verifies PostgreSQL connection
5. Migration check: Ensures migrations can run
6. API smoke test: Validates basic API functionality
7. Worker check: Tests SAQ worker process

Health Check Output

Success:

✓ Docker image built successfully
✓ Containers started
✓ Health endpoint responding
✓ Database connected
✓ Migrations applied
✓ API responding to requests
✓ Worker process running

All health checks passed!

Failure Example:

✗ Health endpoint not responding
  Error: Connection refused on http://localhost:8000/health

Troubleshooting steps:
1. Check container logs: docker logs <container-id>
2. Verify port mapping: docker ps
3. Check health endpoint code

Troubleshooting Docker Issues

Container Won't Start

Check logs:

docker compose logs backend
docker logs <container-id>

Common issues:

• Port 8000 already in use: Stop other backend processes
• Database not ready: Ensure PostgreSQL container is running
• Migration failures: Check Alembic version compatibility
• Missing environment variables: Verify .env or docker-compose.yml

Build Failures

Check build output:

docker build --progress=plain -t arive-backend -f backend/Dockerfile backend/

Common issues:

• Python dependency conflicts: Check

  pyproject.toml

• File not found: Ensure files exist in build context
• uv errors: Verify uv version compatibility
• Permission issues: Check file permissions

Database Connection Issues

Check database container:

docker ps | grep postgres          # Is it running?
docker logs <postgres-container>   # Check logs

Test connection:

docker exec -it <postgres-container> psql -U postgres -d arive_dev

Common issues:

• Container not running:

  make db-start

• Wrong credentials: Check DATABASE_URL
• Port conflict: Ensure 5432/5433 are available
• Network issues: Verify Docker network configuration

Worker Not Processing Tasks

Check worker logs:

docker compose logs worker

Verify queue configuration:

# Access backend shell
docker exec -it <backend-container> python

from app.queue.config import get_queue
queue = await get_queue()
stats = await queue.stats()
print(stats)  # Check queued/processed counts

Common issues:

• Worker not started: Check docker-compose.yml includes worker service
• Queue table missing: Run migrations to create

  saq_*

  tables
• Task not registered: Verify task imported in

  app/queue/config.py

• Database connection: Check worker can connect to PostgreSQL

Local Docker Compose Setup

docker-compose.yml Example

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: arive_dev
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/arive_dev
      ENV: local
    depends_on:
      - db

  worker:
    build:
      context: ./backend
      dockerfile: Dockerfile
    command: litestar workers run
    environment:
      DATABASE_URL: postgresql://postgres:postgres@db:5432/arive_dev
      ENV: local
    depends_on:
      - db

volumes:
  pgdata:

Start Full Stack

docker compose up -d          # Start all services
docker compose logs -f        # Follow logs
docker compose down           # Stop all (keeps volumes)
docker compose down -v        # Stop and DELETE volumes (⚠️ DANGER)

Pre-Deployment Checklist

Before deploying to AWS:

1. Health checks pass locally:

   make docker-test
   

2. All tests pass:

   make test
   make check-all
   

3. Migrations reviewed:

   • Check

     backend/alembic/versions/

     for new migrations
   • Test both upgrade and downgrade paths
   • Verify no data loss operations

4. Environment variables configured:

   • Check

     .env.production

     or AWS Secrets Manager
   • Verify DATABASE_URL, API keys, etc.

5. Email templates compiled:

   make build-emails
   git status  # Ensure compiled templates committed
   

6. Image size reasonable:

   docker images arive-backend
   # Should be < 500MB ideally
   

Production Deployment (AWS ECS)

The backend deploys to AWS ECS Fargate:

• API Service: Litestar app behind ALB
• Worker Service: SAQ background task processor
• Database: Aurora Serverless v2 PostgreSQL
• Images: Stored in ECR (Elastic Container Registry)

Deployment handled by Terraform in

infra/

directory.

See

infra/CLAUDE.md

for detailed infrastructure guide.