From 42b4fce30a93c355987866308d98a6c8c629266c Mon Sep 17 00:00:00 2001
From: Joerg <joerg@dj7nt.de>
Date: Mon, 19 Jan 2026 16:10:22 +0100
Subject: [PATCH] docs: update CLAUDE.md with Docker deployment section

Add comprehensive Docker documentation to CLAUDE.md:
- Quick start guide
- Architecture overview (single port, host-mounted database)
- Key Docker files reference
- Environment variables
- Database management commands
- Important deployment notes

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index f897133..2db7b69 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,6 +47,58 @@ test("hello world", () => {
 });
 ```
 
+## Docker Deployment
+
+The application supports Docker deployment with single-port architecture and host-mounted database persistence.
+
+**Quick Start**:
+```bash
+# Create environment file
+cp .env.docker.example .env
+
+# Generate JWT secret
+openssl rand -base64 32  # Add to .env as JWT_SECRET
+
+# Start application
+docker-compose up -d --build
+
+# Access at http://localhost:3001
+```
+
+**Architecture**:
+- **Single Port**: Port 3001 serves both API (`/api/*`) and frontend (all other routes)
+- **Database Persistence**: SQLite database stored at `./data/award.db` on host
+- **Auto-initialization**: Database created from template on first startup
+- **Health Checks**: Built-in health monitoring at `/api/health`
+
+**Key Docker Files**:
+- `Dockerfile`: Multi-stage build using official Bun runtime
+- `docker-compose.yml`: Stack orchestration with volume mounts
+- `docker-entrypoint.sh`: Database initialization logic
+- `.env.docker.example`: Environment variable template
+- `DOCKER.md`: Complete deployment documentation
+
+**Environment Variables**:
+- `NODE_ENV`: Environment mode (default: production)
+- `PORT`: Application port (default: 3001)
+- `LOG_LEVEL`: Logging level (debug/info/warn/error)
+- `JWT_SECRET`: JWT signing secret (required, change in production!)
+- `VITE_APP_URL`: Your application's public URL
+- `ALLOWED_ORIGINS`: CORS allowed origins (comma-separated)
+
+**Database Management**:
+- Database location: `./data/award.db` (host-mounted volume)
+- Backups: `cp data/award.db data/award.db.backup.$(date +%Y%m%d)`
+- Reset: `docker-compose down -v && docker-compose up -d`
+
+**Important Notes**:
+- Database persists across container restarts/recreations
+- Frontend dependencies are reinstalled in container to ensure correct platform binaries
+- Uses custom init script (`src/backend/scripts/init-db.js`) with `bun:sqlite`
+- Architecture-agnostic (works on x86, ARM64, etc.)
+
+For detailed documentation, see `DOCKER.md`.
+
 ## Frontend
 
 Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.