docs: comprehensive documentation updates for v2.0.0

- Update README.md with Docker quickstart and new features (label management, hacker theme) - Add detailed Docker deployment section to DEPLOYMENT.md: - docker-compose usage - Environment configuration - Data persistence and backup - Container health checks - Troubleshooting steps - Production deployment guidance - Create comprehensive CLAUDE_DESCRIPTION.md: - Project overview and version info - Recent changes in v2.0.0 - Technical stack details - Core features and file structure - State management explanation - Data flow diagrams - API endpoints reference - Development workflow - Customization points - Performance and security notes
2026-02-12 15:13:59 +01:00 · 2026-02-12 15:13:59 +01:00 · 83be6bbdfb
commit 83be6bbdfb
parent a1fa86fe55
4 changed files with 526 additions and 5 deletions
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@ -157,9 +157,233 @@ The application doesn't require any environment variables for local development.
 └── public/               # Static assets
 ```

+## Docker Deployment
+
+### Prerequisites
+
+- Docker (20.10+)
+- docker-compose (2.0+)
+
+### Build and Run with Docker Compose
+
+The easiest way to deploy is with docker-compose:
+
+```bash
+docker-compose up --build
+```
+
+This will:
+1. Build the Docker image with multi-stage build optimization
+2. Create a named volume `candle-data` for persistent database storage
+3. Start the container on port 3000
+4. Enable automatic restart unless stopped
+
+### Running in Detached Mode
+
+```bash
+docker-compose up -d --build
+```
+
+View logs:
+```bash
+docker-compose logs -f candle-annotator
+```
+
+Stop the service:
+```bash
+docker-compose down
+```
+
+### Manual Docker Build and Run
+
+If you prefer to build and run manually:
+
+```bash
+# Build image
+docker build -t candle-annotator .
+
+# Run container
+docker run -d \
+  -p 3000:3000 \
+  -v candle-data:/app/data \
+  --restart unless-stopped \
+  candle-annotator
+```
+
+### Environment Configuration
+
+Create a `.env` file in the project root based on `.env.example`:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` to customize:
+```
+NODE_ENV=production
+PORT=3000
+DATABASE_PATH=/app/data/candles.db
+```
+
+Pass environment variables to docker-compose:
+
+```bash
+docker-compose --env-file .env up -d
+```
+
+### Data Persistence
+
+The application stores the SQLite database in a Docker named volume `candle-data`. This ensures data persists across container restarts:
+
+```bash
+# View volumes
+docker volume ls | grep candle
+
+# Backup database
+docker cp candle-annotator:/app/data/candles.db ./backup.db
+
+# Restore database
+docker cp ./backup.db candle-annotator:/app/data/candles.db
+```
+
+### Accessing the Application
+
+Once running, access the application at:
+```
+http://localhost:3000
+```
+
+Health check endpoint:
+```bash
+curl http://localhost:3000/api/health
+```
+
+With database check:
+```bash
+curl http://localhost:3000/api/health?check=db
+```
+
+### Port Mapping
+
+To run on a different port (e.g., 8080), modify docker-compose.yml:
+
+```yaml
+services:
+  candle-annotator:
+    ports:
+      - "8080:3000"
+```
+
+Or use environment variable in docker-compose:
+
+```yaml
+services:
+  candle-annotator:
+    ports:
+      - "${HOST_PORT:-3000}:3000"
+```
+
+Then run:
+```bash
+HOST_PORT=8080 docker-compose up -d
+```
+
+### Container Health Checks
+
+Docker automatically checks container health every 30 seconds using the `/api/health` endpoint. The container will restart if:
+- Health check fails 3 times consecutively
+- Takes longer than 3 seconds to respond
+
+View health status:
+```bash
+docker ps
+```
+
+Look for the `STATUS` column - it should show `healthy`.
+
+### Troubleshooting
+
+**Port already in use:**
+```bash
+docker-compose down  # Stop any existing containers
+docker-compose up -d -p 8080:3000/tcp
+```
+
+**Database permission errors:**
+```bash
+# Ensure volume has correct permissions
+docker-compose down
+docker volume rm candle-data
+docker-compose up --build
+```
+
+**Rebuild without cache:**
+```bash
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+**View container logs:**
+```bash
+docker-compose logs -f --tail=100
+```
+
+### Update Procedure
+
+To update the application:
+
+```bash
+git pull origin master
+docker-compose down
+docker-compose up --build -d
+```
+
+Or with no-cache rebuild:
+```bash
+git pull
+docker-compose down
+docker-compose build --no-cache
+docker-compose up -d
+```
+
+### Production Deployment
+
+For production deployments, consider:
+
+1. **Use a container registry** (Docker Hub, ECR, GCR):
+   ```bash
+   docker tag candle-annotator myregistry/candle-annotator:v1.0.0
+   docker push myregistry/candle-annotator:v1.0.0
+   ```
+
+2. **Run on a remote server** (AWS, DigitalOcean, etc.):
+   ```bash
+   # SSH into server, clone repo, then:
+   docker-compose up -d
+   ```
+
+3. **Add reverse proxy** (nginx, traefik) for HTTPS:
+   ```yaml
+   # docker-compose.yml
+   services:
+     nginx:
+       image: nginx:alpine
+       ports:
+         - "443:443"
+       volumes:
+         - ./nginx.conf:/etc/nginx/nginx.conf
+   ```
+
+4. **Enable Docker logging** for production monitoring:
+   ```bash
+   docker-compose logs -f --tail=1000 > app.log &
+   ```
+
 ## Notes

 - This application is designed for **single-user local use** only
 - There is no authentication or user management
 - The SQLite database is stored locally and not intended for concurrent access
 - For production multi-user deployments, consider migrating to PostgreSQL or similar
+- Docker deployment provides lightweight containerization ideal for standalone instances
+- The multi-stage Dockerfile keeps image size minimal (~100MB)