49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
# 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, all)
|
|
- `tools/new-app.sh` -- Wrapper for `app.sh all` (backwards compat)
|
|
- `tools/new-service.sh` -- Scaffold a new Docker Compose service (compose + workflow)
|
|
- `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/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. No tests. Verify changes by:
|
|
1. Reading scripts and checking idempotency
|
|
2. Walking through each use case in USECASES.md
|
|
3. Cross-checking docs against scripts
|
|
|
|
## 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
|