claude-code-tracker/DOCKER.md

Claude Code Tracker - Docker Deployment

This guide covers deploying Claude Code Tracker using Docker with Caddy reverse proxy integration.

Quick Start

1. Clone and configure:

   git clone <repository>
   cd claude-tracker
   cp .env.example .env
   # Edit .env file to set your domain
   

2. Deploy with one command:

   ./docker-deploy.sh
   

3. Access your instance:

   • Dashboard: https://claude.l.supported.systems/dashboard
   • API Docs: https://claude.l.supported.systems/docs

Prerequisites

Required

• Docker Engine 20.10+
• Docker Compose 2.0+
• Caddy server with docker-proxy plugin running

Caddy Network Setup

The deployment expects an external Docker network named caddy:

# Create the network if it doesn't exist
docker network create caddy

Caddy Server

Ensure Caddy is running with the docker-proxy plugin:

# Example Caddy docker-compose.yml
version: '3.8'
services:
  caddy:
    image: lucaslorentz/caddy-docker-proxy:ci-alpine
    ports:
      - "80:80"
      - "443:443"
    environment:
      - CADDY_INGRESS_NETWORKS=caddy
    networks:
      - caddy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - caddy_data:/data
    restart: unless-stopped

Configuration

Environment Variables

The .env file configures the deployment:

# Domain for Caddy reverse proxy
DOMAIN=claude.l.supported.systems

# Database path (inside container)
DATABASE_URL=sqlite+aiosqlite:///app/data/tracker.db

# Application settings
DEBUG=false
API_HOST=0.0.0.0
API_PORT=8000

# Data directory path (host)
DATA_PATH=./data

Caddy Labels

The docker-compose.yml includes comprehensive Caddy configuration:

• Reverse Proxy: Automatic routing to the container
• SSL/TLS: Automatic certificate management
• Security Headers: XSS protection, content type sniffing prevention
• CORS Headers: API cross-origin support
• Compression: Gzip encoding for better performance
• Caching: Static asset caching

Deployment Options

Option 1: Automated Deployment (Recommended)

./docker-deploy.sh

Option 2: Manual Deployment

# Create network if needed
docker network create caddy

# Build and start
docker-compose up -d --build

# Check status
docker-compose ps

Option 3: Development Mode

# Start with logs
docker-compose up --build

# Rebuild after changes
docker-compose up --build --force-recreate

Data Persistence

Database Storage

• Host Path: ./data/ (configurable via DATA_PATH)
• Container Path: /app/data/
• Database File: tracker.db

Volume Management

# Backup database
cp ./data/tracker.db ./backups/tracker-$(date +%Y%m%d).db

# Restore database
cp ./backups/tracker-20240115.db ./data/tracker.db
docker-compose restart claude-tracker

Management Commands

Service Management

# View logs
docker-compose logs -f claude-tracker

# Restart service
docker-compose restart claude-tracker

# Stop service
docker-compose down

# Update and restart
docker-compose pull && docker-compose up -d

Container Access

# Shell access
docker-compose exec claude-tracker /bin/bash

# Run commands in container
docker-compose exec claude-tracker uv run python recalculate_project_stats.py

# View container stats
docker stats claude-tracker-api

Health Monitoring

# Check health
curl http://localhost:8000/health

# Container status
docker-compose ps

# Resource usage
docker-compose exec claude-tracker cat /proc/meminfo

Troubleshooting

Common Issues

1. Container Won't Start

# Check logs
docker-compose logs claude-tracker

# Common causes:
# - Port 8000 already in use
# - Database permission issues
# - Missing environment variables

2. Database Errors

# Check database permissions
ls -la ./data/

# Recreate database
rm ./data/tracker.db
docker-compose restart claude-tracker

3. Caddy Connection Issues

# Verify Caddy network
docker network ls | grep caddy

# Check Caddy logs
docker logs caddy

# Verify labels
docker inspect claude-tracker-api | grep -A 10 Labels

4. Performance Issues

# Monitor resources
docker stats claude-tracker-api

# Increase memory limits in docker-compose.yml

Health Checks

The container includes built-in health checks:

# Container health status
docker-compose ps

# Manual health check
curl -f http://localhost:8000/health

# Detailed health info
docker inspect --format='{{json .State.Health}}' claude-tracker-api

Security Considerations

Network Security

• Container only exposes port 8000 internally to Docker network
• External access only through Caddy reverse proxy
• Automatic HTTPS with Let's Encrypt

Data Security

• Database stored in dedicated Docker volume
• No sensitive data in container images
• Environment variables for configuration

Resource Limits

• Memory limit: 512MB (configurable)
• CPU limit: 1.0 core (configurable)
• Automatic restart on failure

Production Recommendations

Performance

1. Use bind mounts for data persistence
2. Configure resource limits appropriately
3. Monitor container health and logs
4. Regular database backups

Security

1. Use specific image tags (not latest)
2. Regular security updates
3. Network isolation
4. Secret management for sensitive data

Monitoring

1. Set up log aggregation
2. Configure health check alerts
3. Monitor resource usage
4. Database backup automation

Advanced Configuration

Custom Caddy Labels

Add additional Caddy configuration in docker-compose.yml:

labels:
  # Rate limiting
  caddy.rate_limit: "100r/m"
  
  # Basic auth for admin endpoints
  caddy.basicauth./admin/*: "admin $2a$14$..."
  
  # IP restrictions
  caddy.@internal: "remote_ip 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16"
  caddy.authorize.@internal: ""

Multi-Environment Setup

Create environment-specific compose files:

# Production
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Development
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Updating

Application Updates

# Pull latest changes
git pull

# Rebuild and restart
docker-compose up -d --build

# Check health
curl https://claude.l.supported.systems/health

Database Migrations

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

# Run migration (if needed)
docker-compose exec claude-tracker uv run python migrate.py

# Verify
docker-compose logs claude-tracker

Support

For issues related to:

• Docker deployment: Check this documentation
• Caddy configuration: Refer to Caddy documentation
• Application features: See main README.md
• API usage: Visit /docs endpoint

Links

• Dashboard: https://your-domain/dashboard
• API Documentation: https://your-domain/docs
• Hook Reference: https://your-domain/dashboard/docs/hook-reference
• Health Check: https://your-domain/health