server-stack/CLAUDE.md

Agent Instructions

Project Context

This is the server-stack repository for deploying tessavb.com, jamesvanboxtel.com, and git.jamesvanboxtel.com. It runs on a GCP e2-micro VM (Debian 12) at 35.230.59.34.

Stack

• Caddy (lucaslorentz/caddy-docker-proxy) - reverse proxy with auto-SSL via Docker labels
• Gitea - self-hosted git at git.jamesvanboxtel.com
• Node/Express apps - each site runs on port 8080 internally
• Docker Compose - orchestrates everything (use docker-compose not docker compose on the server, the v2 plugin isn't installed)
• SQLite - database files go in apps/<name>/data/

Key Conventions

• Caddy routing is configured via Docker labels on each service (e.g., caddy: tessavb.com, caddy.reverse_proxy: "{{upstreams 8080}}")
• The Docker network is named server-stack_server-network (docker-compose prefixes the project name)
• The CADDY_INGRESS_NETWORKS env var must match this exact network name
• Data directories (caddy_data/, gitea_data/, apps/*/data/) are gitignored and must never be deleted on the server
• Each app has its own Dockerfile, package.json, and server.js in apps/<name>/

Adding a New Site

1. Create apps/<name>/ with Dockerfile, package.json, server.js
2. Add a service block to docker-compose.yml with appropriate caddy labels
3. Add DNS A record pointing the domain to 35.230.59.34
4. Push and rebuild: docker-compose up -d --build

Deployment

Currently manual: push to Gitea, SSH in, git pull && docker-compose up -d --build. Auto-deploy via webhook is planned but not yet configured.

Testing

No test suite yet. Verify changes by:

1. Building locally: docker-compose build <service-name>
2. Checking the site loads after deploying
3. Checking logs: docker logs <container-name>