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:

   bash

   make docker-test
   

2. •

   All tests pass:

   bash

   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:

   bash

   make build-emails
   git status  # Ensure compiled templates committed
   

6. •

   Image size reasonable:

   bash

   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.