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:**
   ```bash
   git clone <repository>
   cd claude-tracker
   cp .env.example .env
   # Edit .env file to set your domain
   ```

2. **Deploy with one command:**
   ```bash
   ./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`:

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

### Caddy Server
Ensure Caddy is running with the docker-proxy plugin:

```bash
# 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:

```bash
# 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)
```bash
./docker-deploy.sh
```

### Option 2: Manual Deployment
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check logs
docker-compose logs claude-tracker

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

#### 2. Database Errors
```bash
# Check database permissions
ls -la ./data/

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

#### 3. Caddy Connection Issues
```bash
# 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
```bash
# Monitor resources
docker stats claude-tracker-api

# Increase memory limits in docker-compose.yml
```

### Health Checks

The container includes built-in health checks:

```bash
# 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`:

```yaml
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:

```bash
# 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
```bash
# Pull latest changes
git pull

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

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

### Database Migrations
```bash
# 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`