Phase 0 deployment: three-service docker-compose.yml (caddy, api, db), a
Caddyfile that proxies /api/* to the api service and serves the SPA with
index.html fallback, and two Gitea Actions workflows (release.yml builds and
pushes both images on a v* tag or manual dispatch; deploy.yml is manual-only
and rolls them out to the Unraid host).
The non-obvious part is the Docker-outside-of-Docker constraint on this
act_runner setup: job containers share the host's Docker daemon over the
socket but do NOT share its filesystem, so any command whose correctness
depends on a client-side local path (docker cp to a host path, mv/rm -rf on
a host path, a bind-mount source path on a `docker run` command line issued
from inside a job) silently operates on the ephemeral job container's own
throwaway filesystem instead. Two things are safe: a bind mount declared in
a compose file's `volumes:` block (resolved by the daemon when `docker
compose up` creates the service — this is why db's pgdata bind mount is
fine), and a named volume populated by a one-shot `docker run` whose
*command* does the copying (this is why the web image's static build output
goes into a `web_build` named volume via `docker run -v ... sh -c 'cp -a
...'` in deploy.yml, rather than any `docker cp`).
Local verification (see PR description for full detail) caught a real bug:
`docker compose run api alembic upgrade head` needs
VELODROME_DB_APP_PASSWORD/VELODROME_DB_AUTH_PASSWORD as container env vars
to create the two runtime roles, but --env-file alone doesn't inject them
since the api service's permanent environment block deliberately omits them
(least-privilege — the long-running app should never need role-creation
passwords). Fixed by passing them as explicit -e overrides on the migration
step, same as VELODROME_DATABASE_URL_MIGRATE.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Prepares the repo for parallel agent work. No application code.
- CLAUDE.md: conventions, branch naming, and the six non-negotiable
invariants from the design (immutable raw bytes, no stored odometers,
SI integers, dual-layer user isolation, secret containment, single
ingestion path). Also records a model-allocation policy: the
orchestrator runs Opus 5, workers default to Sonnet, and Opus is
reserved for review plus the areas where a mistake is silent and
expensive (ingest, wear SQL, auth/RLS, the Bryton protocol client).
And the Gitea Actions gotchas, so nobody rediscovers them:
GITEA_TOKEN cannot push to the container registry, jobs.*.environment
is ignored, and cron needs a workflow_dispatch pair.
- CONTRIBUTING.md: day-to-day flow, worktrees for parallel branches,
review expectations.
- .gitea/workflows/ci.yml: repo hygiene (branch naming, secret scan,
no ride data in git), plus API/web/migration jobs that guard on whether
the code exists yet, so CI is meaningful now and grows into the real
thing rather than being rewritten.
- .gitea/PULL_REQUEST_TEMPLATE.md: forces an honest "how this was
verified" and an invariant checklist.
- scripts/pr.sh, scripts/review.sh: open and inspect PRs via the Gitea API.
- Directory scaffold with placeholder READMEs.
Agents open PRs; humans merge them.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
BBergleandClaude Sonnet 5