Jake/bike_admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: production deployment recipe + Arch gotchas

Browse Source 
- README: expand the production section with a full systemd recipe
  (useradd, chown, uv sync --project, install -d for ReadWritePaths,
  .env perms 640), a Caddy block, and backup note.
- AGENTS.md: add the Arch python-uv package-name note and the root-rooted
  venv caveat, plus a new "Deploy / production" section documenting the
  volundr unit, data location, .env perms, and forward-proxy expectations.
This commit is contained in:
Jake
2026-09-10 13:25:19 +01:00
parent ff7212ab9e
commit 4576e6fae3
2 changed files with 79 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -10
View File
@@ -42,6 +42,55 @@ uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
Or copy `.env.example` to `.env` and fill in the values (env vars and the local
`.env` file are both read automatically).
## Running behind a reverse proxy (production)
TLS terminated at the proxy (Caddy/nginx), app on a private host behind it.
`deploy/bike_admin.service` is the systemd unit used in production;
`deploy/env.production.example` is the production `.env` template.
- Set `BIKE_ADMIN_IS_PRODUCTION=true` so the session cookie is `Secure`.
- Bind as needed for the proxy to reach you:
- proxy on the **same** host → `--host 127.0.0.1`
- proxy on **another** host (e.g. a single fronting Caddy) → `--host 0.0.0.0`
or bind to a specific LAN interface; never the public interface directly, since
there is no app-level TLS.
- Proxy forwards to the app and sets `X-Forwarded-For` / `X-Forwarded-Proto`;
the app trusts these by default (`BIKE_ADMIN_TRUST_PROXY`). uvicorn's
`--forwarded-allow-ips 192.168.0.0/16 --proxy-headers` accepts them
(adjust to your LAN range).
### systemd (production recipe)
```bash
# one-time: deps + service account [on Arch: uv ships as python-uv]
sudo pacman -S --needed git python-uv
sudo useradd --system bike
# one-time: app
sudo chown -R bike:bike /opt/bike_admin
sudo -u bike uv sync --all-extras --project /opt/bike_admin
sudo install -d -o bike -g bike /opt/bike_admin/data # systemd needs it to exist
# one-time: .env (see deploy/env.production.example)
sudo chown bike:bike /opt/bike_admin/.env
sudo chmod 640 /opt/bike_admin/.env # owner rw, group r, others none
sudo cp deploy/bike_admin.service /etc/systemd/system/bike-admin.service
sudo systemctl daemon-reload
sudo systemctl enable --now bike-admin
```
Caddy block for the fronting proxy:
```
volundr.local.jakes-asgard.uk {
reverse_proxy 192.168.0.52:8000
}
```
Back up your data by copying the single file in the data dir —
`<data_dir>/bike_admin.db` (SQLite, WAL; `data/bike_admin.db` by default).
## Tests / lint
```bash
@@ -49,13 +98,3 @@ uv run pytest -q
uv run ruff check app tests
uv run ruff format --check app tests
```
## Running behind a reverse proxy (production)
- Terminate TLS at the proxy (nginx/apache/caddy) and forward to the app.
- Set `BIKE_ADMIN_IS_PRODUCTION=true` so the session cookie is `Secure`.
- Bind to the private address: `uvicorn app.main:app --host 127.0.0.1 --port 8000`
- Pass `X-Forwarded-For` / `X-Forwarded-Proto` so throttling + secure-cookie logic
see the real client IP/protocol (the app trusts these by default).
Back up your data by copying the single file `data/bike_admin.db` (SQLite, WAL).