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_idGITHUB_CLIENT_SECRET=your_github_oauth_app_secretOAUTH_REDIRECT_URI=http://localhost:9002/auth/callback# for devOAUTH_STATE_SECRET=your-random-secret-key# Admin Authentication (required)ADMIN_INITIAL_USERNAME=your_github_username# Legacy team-based auth (optional, deprecated)ADMIN_GITHUB_ORG=pythonADMIN_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.