CLAUDE.md

Quick context for Claude Code. See README.md for full details, ARCHITECTURE.md for technical deep-dives, USECASES.md for expected behaviors.

Key files

scripts/bootstrap.sh -- First-time server setup (manual, uses Bitwarden)
scripts/configure.sh -- Idempotent server config (firewall, certbot, start services; CI-safe)
scripts/deploy.sh -- SSH-triggered deploy + cert issuance + provision (deploy-, cert-, provision commands)
tools/app.sh -- App provisioning by subcommand (dns, repo, files, cert, garage, build, verify, monitor, all)
tools/service.sh -- Manage Docker services by subcommand (dns, files, nginx, cert, all)
tools/remove-app.sh -- Remove a static site (local files + Gitea repo)
docker/nginx/conf.d/ -- Per-app nginx server blocks
docker/<domain>/compose.yml -- Per-app compose files
docker/goatcounter/ -- GoatCounter analytics (compose.yaml, .env.keys)
docker/garage/ -- Garage S3 object storage (Dockerfile, garage.toml, .env.keys)
.gitea/workflows/ -- Per-app deploy workflows + provision.yml

Conventions

App name = domain (e.g., example.com)
Container name = dots → underscores (e.g., example_com)
One domain per conf file -- deploy.sh derives cert name from filename
All HTTP → HTTPS; bare domain → www.<domain>
All shell scripts use set -euo pipefail and must be idempotent
The shared Docker network is created by nginx compose and used by all apps
Secrets are in Bitwarden Secrets Manager (see README.md for full list)
Service secrets use .env.keys files (see README.md)

Deploy flow

App repo push → build.yml → build/push image → SSH deploy-<domain> → deploy.sh
This repo push → deploy-<app>.yml (path match) → SSH deploy-<app> → deploy.sh
Setup change → provision.yml → SSH provision → configure.sh

Build and test

No build step. Run e2e tests with:

uvx pytest tests/test_app_e2e.py -v -x

Prerequisites

uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
CLI tools: bws, jq, dig, ssh, curl, git
bws token: set BWS_ACCESS_TOKEN env var or save to ~/.config/hantim/bws-token
Vultr API key must allow requests from the machine's IP (check https://my.vultr.com/settings/#settingsapi)

Test structure

tests/conftest.py -- Fixtures: preflight checks, bws secrets, API helper, cleanup
tests/test_app_e2e.py -- E2E tests for tools/app.sh against real services
tests/test_security_headers.py -- Verify security headers on live sites
tests/test_default_server.py -- Verify unknown Host headers are dropped
tests/test_tls.py -- Verify TLS hardening

E2E tests (`test_app_e2e.py`)

Tests use kgfamily.com as a throwaway test domain. Two phases:

TestAppSubcommands -- Runs each app.sh subcommand individually (dns, repo, files, cert, garage, build, monitor), verifies side effects via API, then cleans up. Does not test verify (needs full deploy flow).
TestAppAll -- Runs app.sh all kgfamily.com, verifies everything including site liveness and git commit, then cleans up (including reverting the commit+push).

Cleanup is done directly via APIs (Vultr, Gitea, Garage, UptimeRobot) + local file deletion. Does NOT use remove-app.sh to avoid coupling. Runs before and after each phase to handle leftovers from crashed runs.

Known issue

Vultr API keys can be IP-restricted. If test_dns fails with HTTP 401, add the machine's IP to the Vultr API access control list.

Other tests

The security/TLS/default-server tests run against live sites and are triggered automatically after nginx deploy. They can also be run locally:

uvx pytest tests/ -v --ignore=tests/test_app_e2e.py

Commit style

Short, lowercase commit messages (e.g., "add example.com", "fix deploy command")
Do NOT include "Co-Authored-By" lines
Commit only when explicitly asked

3.9 KiB Raw Permalink Blame History