Add comprehensive Docker deployment and file upload functionality
Features Added: • Docker containerization with multi-stage Python 3.12 build • Caddy reverse proxy integration with automatic SSL • File upload interface for .claude.json imports with preview • Comprehensive hook system with 39+ hook types across 9 categories • Complete documentation system with Docker and import guides Technical Improvements: • Enhanced database models with hook tracking capabilities • Robust file validation and error handling for uploads • Production-ready Docker compose configuration • Health checks and resource limits for containers • Database initialization scripts for containerized deployments Documentation: • Docker Deployment Guide with troubleshooting • Data Import Guide with step-by-step instructions • Updated Getting Started guide with new features • Enhanced documentation index with responsive grid layout 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
bec1606c86
commit
50c80596d0
36 changed files with 4334 additions and 172 deletions
345
DOCKER.md
Normal file
345
DOCKER.md
Normal file
|
|
@ -0,0 +1,345 @@
|
|||
# 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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue