{% extends "docs/base.html" %} {% block title %}Docker Deployment - Claude Code Project Tracker{% endblock %} {% block doc_content %}

Docker Deployment Guide

Deploy Claude Code Project Tracker using Docker with Caddy reverse proxy for production environments.

Prerequisites

Required:

  • Docker and Docker Compose installed
  • Caddy with docker-proxy plugin
  • External Caddy network configured
  • Domain name (or local development domain)

Quick Start

Follow these steps to get Claude Code Tracker running with Docker:

1. Clone and Configure
# Clone the repository
git clone <repository-url> claude-tracker
cd claude-tracker

# Copy environment template
cp .env.example .env
2. Configure Environment

Edit the .env file with your settings:

# Domain configuration
DOMAIN=claude.l.supported.systems

# Database settings
DATABASE_URL=sqlite+aiosqlite:////app/data/tracker.db

# Application settings
DEBUG=false
PYTHONPATH=/app
3. Deploy with Docker Compose
# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Check status
docker-compose ps

Docker Configuration

Dockerfile

The application uses a multi-stage Docker build with Python 3.12 and uv package manager:

# Multi-stage build with Python 3.12
FROM python:3.12-slim

# Install uv package manager
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# Application setup
WORKDIR /app
COPY . .

# Install dependencies and create virtual environment
RUN uv venv && uv pip install -r requirements.txt

# Database initialization script
COPY init_db.py ./

# Startup script with database initialization
CMD ["./start.sh"]

docker-compose.yml

The Docker Compose configuration includes Caddy integration:

services:
  claude-tracker:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: claude-tracker-api
    restart: unless-stopped
    environment:
      - DATABASE_URL=sqlite+aiosqlite:////app/data/tracker.db
      - DEBUG=true
      - PYTHONPATH=/app
    volumes:
      - ./data:/app/data
      - ./app/dashboard/static:/app/app/dashboard/static:ro
    networks:
      - caddy
    labels:
      # Caddy reverse proxy configuration
      caddy: ${DOMAIN:-claude.l.supported.systems}
      caddy.reverse_proxy: "{{upstreams 8000}}"
    expose:
      - 8000
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s

networks:
  caddy:
    external: true
    name: caddy

Caddy Integration

The application integrates with Caddy using docker-proxy labels for automatic SSL and reverse proxy configuration.

Caddy Labels Explained
  • caddy: ${DOMAIN} - Sets the domain for the service
  • caddy.reverse_proxy: "{{upstreams 8000}}" - Proxies to port 8000
  • Automatic SSL certificate generation
  • Health check integration
  • Load balancing support

Database & Persistence

The application uses SQLite with proper volume mounting for data persistence:

Volume Configuration
  • ./data:/app/data - Database and file storage
  • ./app/dashboard/static:/app/app/dashboard/static:ro - Static assets (read-only)
Important: Ensure the ./data directory exists and has proper permissions before starting the container.

Management Commands

Container Management
# Start services
docker-compose up -d

# Stop services  
docker-compose down

# Restart services
docker-compose restart

# View logs
docker-compose logs -f

# Check status
docker-compose ps
Database Management
# Execute shell in container
docker-compose exec claude-tracker sh

# Initialize database manually
docker-compose exec claude-tracker python init_db.py

# Backup database
cp ./data/tracker.db ./data/tracker.db.backup

# View database size
du -h ./data/tracker.db

Monitoring & Health

Health Checks

The container includes built-in health checks:

  • Endpoint: http://localhost:8000/health
  • Interval: 30 seconds
  • Timeout: 10 seconds
  • Retries: 3 attempts
  • Start Period: 30 seconds
# Check health status
docker-compose ps
curl https://your-domain.com/health
Resource Limits

Configured resource limits:

  • CPU Limit: 1.0 core
  • Memory Limit: 512MB
  • CPU Reservation: 0.25 core
  • Memory Reservation: 128MB

Troubleshooting

# Check logs for errors
docker-compose logs claude-tracker

# Check database permissions
ls -la ./data/

# Verify database initialization
docker-compose exec claude-tracker python init_db.py

# Check if container is running
docker-compose ps

# Verify health check
docker-compose exec claude-tracker curl localhost:8000/health

# Check Caddy network connectivity
docker network ls | grep caddy

# Create data directory if missing
mkdir -p ./data
chmod 755 ./data

# Remove corrupted database
rm ./data/tracker.db

# Restart container to reinitialize
docker-compose restart

Security Considerations

Production Security
  • Set DEBUG=false in production
  • Use strong domain names and SSL certificates
  • Regularly backup the database
  • Monitor container logs for suspicious activity
  • Keep Docker images updated
  • Limit container resource usage
Quick Reference
Essential Commands
# Deploy
docker-compose up -d

# Logs
docker-compose logs -f

# Stop
docker-compose down
Key Files
  • .env
  • docker-compose.yml
  • Dockerfile
  • ./data/
Default Ports
  • 8000 (Internal)
  • 80/443 (Caddy)
{% endblock %}