docker-README.md

Docker Setup for Memory Tracker

This Docker Compose configuration brings up the entire Memory Tracker application with PostgreSQL database, FastAPI backend, and Next.js frontend.

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+

Quick Start

1. Set up environment variables:

   cp .env.example .env
   # Edit .env with your GitHub OAuth credentials and admin username

2. Build and start all services:

   docker compose up --build

3. Start in detached mode (background):

   docker compose up -d --build

4. Access the application:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs
   • PostgreSQL: localhost:5432

Services

Database (PostgreSQL)

• Image: postgres:15-alpine
• Port: 5432
• Database: memory_tracker
• User: memory_tracker_user
• Password: memory_tracker_password
• Data Volume: postgres_data

Backend (FastAPI)

• Port: 8000
• Health Check: http://localhost:8000/health
• Environment Variables:
  • DATABASE_URL: PostgreSQL connection string

Frontend (Next.js)

• Port: 3000
• Environment Variables:
  • NEXT_PUBLIC_API_BASE: Backend API URL

Database Initialization

• Service: db-init
• Purpose: Populates the database with default binary configurations
• Runs: Once after backend is healthy

Database Configuration

The application automatically:

1. Creates database tables on first startup
2. Populates default binary configurations (default, debug, etc.)

Useful Commands

View logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f db

Restart services

# All services
docker compose restart

# Specific service
docker compose restart backend

Stop and remove everything

docker compose down

Stop and remove with volumes (clears database)

docker compose down -v

Rebuild specific service

docker compose build backend
docker compose up -d backend

Development

Updating Backend Dependencies

Backend dependencies are managed with pip-tools. There are two lockfiles: requirements.txt (production) and requirements-dev.txt (adds test tooling). Edit backend/requirements.in for direct dependencies, then regenerate both lockfiles:

docker run --rm -v "$(pwd)/backend:/app" -w /app python:3.13-slim-bookworm \
  sh -c "pip install --quiet pip-tools && \
  pip-compile --strip-extras --generate-hashes \
    --output-file requirements.txt requirements.in && \
  pip-compile --strip-extras --generate-hashes \
    --output-file requirements-dev.txt requirements-dev.in"

Commit all changed files, then rebuild:

docker compose -f docker-compose.dev.yml up --build -d backend

Environment Variables

The application uses a .env file for configuration. Copy the example and customize:

cp .env.example .env

Required variables in .env:

# GitHub OAuth Configuration (required for admin authentication)
GITHUB_CLIENT_ID=your_github_oauth_app_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_app_secret
OAUTH_REDIRECT_URI=http://localhost:9002/auth/callback  # for dev
OAUTH_STATE_SECRET=your-random-secret-key

# Admin Authentication (required)
ADMIN_INITIAL_USERNAME=your_github_username

# Legacy team-based auth (optional, deprecated)
ADMIN_GITHUB_ORG=python
ADMIN_GITHUB_TEAMS=memory-python-org

Note: Development compose file uses port 9002 for frontend, production uses 3000.

Linting & Type Checking

# ESLint (must pass with zero errors)
docker compose -f docker-compose.dev.yml exec frontend npm run lint

# TypeScript type checking
docker compose -f docker-compose.dev.yml exec frontend npm run typecheck

Accessing the Database

# Connect to PostgreSQL container
docker compose exec db psql -U memory_tracker_user -d memory_tracker

# Or from host (if psql is installed)
psql -h localhost -p 5432 -U memory_tracker_user -d memory_tracker

Backend Shell Access

docker compose exec backend sh

Frontend Shell Access

docker compose exec frontend sh

Troubleshooting

Service won't start

1. Check logs: docker compose logs [service-name]
2. Verify health checks: docker compose ps
3. Restart specific service: docker compose restart [service-name]

Database connection issues

1. Ensure PostgreSQL is healthy: docker compose ps db
2. Check database logs: docker compose logs db
3. Verify connection string in backend logs

Frontend can't reach backend

1. Check backend health: curl http://localhost:8000/health
2. Verify NEXT_PUBLIC_API_BASE environment variable
3. Check CORS configuration in backend

Clean slate restart

# Stop everything and remove volumes
docker compose down -v

# Remove images (optional)
docker compose down --rmi all

# Rebuild and start
docker compose up --build

Production Considerations

For production deployment:

1. Change default passwords in environment variables
2. Use external PostgreSQL database for persistence
3. Configure proper CORS origins for your domain
4. Set up reverse proxy (nginx/traefik) for SSL termination
5. Configure logging aggregation and monitoring
6. Use secrets management for sensitive environment variables

Architecture

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Frontend  │───▶│   Backend   │───▶│ PostgreSQL  │
│   Next.js   │    │   FastAPI   │    │  Database   │
│   Port 3000 │    │   Port 8000 │    │   Port 5432 │
└─────────────┘    └─────────────┘    └─────────────┘

The services communicate through Docker's internal network, with health checks ensuring proper startup order.