# deploy/

Everything needed to run Velodrome as **one container**. See `docs/DECISIONS.md` D15 (why SQLite
and one container) and D16 (why migrations run from the entrypoint, and the Caddy/tini setup)
before changing anything here.

```
../Dockerfile          Multi-stage build: web SPA + API venv + Caddy, into one runtime image
Caddyfile               Serves the static SPA, proxies /api/* to uvicorn on loopback
entrypoint.sh           Runs migrations, then supervises uvicorn + Caddy as PID 1's children
unraid-template.xml     Unraid Community Applications template — turns the env vars below into
                        fillable web UI fields instead of a .env file
```

There is no docker-compose here, deliberately — the app is one container, not a set of services
that need orchestrating together. (Later phases may add genuinely separate containers — a
tileserver, a local LLM — see `docs/PLAN.md`'s "Service topology"; those would get their own
compose file or Unraid templates when a phase actually needs one, not speculatively now.)

## Build

From the repo root (the build context — the Dockerfile needs both `apps/api` and `apps/web`):

```sh
docker build -t velodrome .
```

## Run

```sh
docker run -d \
  --name velodrome \
  -p 8080:8080 \
  -v velodrome-data:/data \
  -e VELODROME_PUBLIC_URL=https://bikes.example.com \
  -e VELODROME_SECRET_KEY=$(openssl rand -hex 32) \
  -e VELODROME_ENVIRONMENT=production \
  velodrome
```

Put a TLS-terminating reverse proxy (whatever's already fronting other services on the host) in
front of port 8080 — this container only ever serves plain HTTP itself.

`GET http://<host>:8080/api/v1/healthz` should return `{"status": "ok"}` once it's up.

## Environment variables

All read by `apps/api/velodrome/config.py` (prefix `VELODROME_`) — the app and Alembic both read
the same values, there's no separate migration-time config anymore (docs/DECISIONS.md D15).

| Variable | Required | Default (baked into the image) | Notes |
|---|---|---|---|
| `VELODROME_DATABASE_URL` | No — don't override | `sqlite+aiosqlite:////data/velodrome.db` | Fixed to the `/data` volume mount. Change the volume mapping, not this. |
| `VELODROME_PUBLIC_URL` | **Yes** | none | The externally-visible URL. Checked against `Origin` on cookie-authenticated mutations — get this wrong and every logged-in write silently 403s. |
| `VELODROME_SECRET_KEY` | **Yes** | insecure dev placeholder | `openssl rand -hex 32`. Not yet used for anything reachable (arrives with Bryton credential encryption in a later phase) — set a real value now anyway. |
| `VELODROME_ENVIRONMENT` | **Yes** | `development` | `development` \| `test` \| `production`. Gates the session cookie's `Secure` flag — always `production` behind real HTTPS. |
| `VELODROME_SESSION_TTL_DAYS` | No | `90` | Login session lifetime. |
| `VELODROME_SESSION_COOKIE_NAME` | No | `vd_session` | Only matters if it collides with another app on the same domain. |

## Volumes

| Path | Contents |
|---|---|
| `/data` | The SQLite database file. Will also hold the content-addressed blob store once Phase 1 builds ingestion. This is the only thing that needs backing up. |

## Unraid

Import `unraid-template.xml` from the Docker tab's "Add Container" template picker — it exposes
the Port, Data path, and the env vars above as fillable web UI fields, matching the earlier
decision to keep configuration in Unraid's own UI rather than a `.env` file on disk. Every field
stays editable by hand afterward regardless of what the template pre-fills.

## Publishing the image

`.gitea/workflows/release.yml` builds this Dockerfile and pushes it to the Gitea container
registry (`192.168.0.3:3000/bbergle/bike-app`) on a `v*` tag push, or on manual
`workflow_dispatch`. It does **not** SSH into the host and recreate the running container —
rolling out a new image on Unraid (pulling it and clicking "Apply" on the container, or via
Unraid's own update-checking) is left as a manual/Unraid-side step, not something CI does
unattended.

## What's not here yet

Backups (`docs/PLAN.md` calls for a systemd timer running `restic` against `/data`, independent of
CI) and the `import_inbox` USB-watch bind mount are both Phase 1+ concerns — nothing in the schema
uses them yet.