chore(deploy): single-container Dockerfile, Caddy, and Unraid template
Builds the container the "1 container" decision (D15) actually needs, which D15 itself deferred as follow-up work: Caddy + the FastAPI app + the static SvelteKit build in one image, SQLite on a mounted volume. See docs/DECISIONS.md D16 for the specific choices and why (entrypoint-run migrations instead of a separate deploy-pipeline step, tini + a small supervisor script instead of s6-overlay/supervisord, copying the Caddy binary out of its official image). Removes apps/api/Dockerfile and apps/web/Dockerfile from the old 4-container compose plan (PR #4, closed as superseded) — the root Dockerfile replaces both with one multi-stage build. deploy/unraid-template.xml turns VELODROME_PUBLIC_URL, VELODROME_SECRET_KEY, etc. into fillable Unraid Community Applications web UI fields, per the earlier decision to keep config there instead of a .env file. .gitea/workflows/release.yml builds and pushes the image to the Gitea registry on a version tag or manual dispatch; it does not touch the running container. Verified by actually running the built image, not just building it: the health endpoint responds through Caddy's proxy, the SPA serves with working client-route fallback, alembic ran and produced a real (non-empty) SQLite file under /data, the process runs as the non-root velodrome user, and killing the uvicorn process brings the whole container down (exit 143) rather than leaving Caddy serving alone — confirming the entrypoint's coupled-lifetime behavior actually holds, not just that it reads correctly. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01R2ZKeWkZV7ehf7fivrAkkG
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,15 @@
|
||||
.git
|
||||
.gitea
|
||||
docs
|
||||
scripts
|
||||
**/node_modules
|
||||
**/.venv
|
||||
**/__pycache__
|
||||
**/*.pyc
|
||||
apps/web/build
|
||||
apps/web/.svelte-kit
|
||||
apps/api/.pytest_cache
|
||||
apps/api/.mypy_cache
|
||||
apps/api/.ruff_cache
|
||||
**/*.db
|
||||
**/*.db-journal
|
||||
@@ -0,0 +1,42 @@
|
||||
name: Release image
|
||||
|
||||
on:
|
||||
push:
|
||||
tags: ['v*']
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
build-and-push:
|
||||
name: Build and push single-container image
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
|
||||
# secrets.GITEA_TOKEN cannot push to the Gitea container registry — a documented Gitea
|
||||
# limitation, not a misconfiguration (see CLAUDE.md). REGISTRY_TOKEN is a separate PAT with
|
||||
# package:write, expected to already exist as a repo secret.
|
||||
- uses: docker/login-action@v3
|
||||
with:
|
||||
registry: 192.168.0.3:3000
|
||||
username: BBergle
|
||||
password: ${{ secrets.REGISTRY_TOKEN }}
|
||||
|
||||
- name: Resolve image tag
|
||||
id: tag
|
||||
run: |
|
||||
if [ "${{ gitea.ref_type }}" = "tag" ]; then
|
||||
echo "value=${{ gitea.ref_name }}" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "value=manual-$(date -u +%Y%m%d%H%M%S)" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- uses: docker/build-push-action@v6
|
||||
with:
|
||||
context: .
|
||||
file: Dockerfile
|
||||
push: true
|
||||
tags: |
|
||||
192.168.0.3:3000/bbergle/bike-app:latest
|
||||
192.168.0.3:3000/bbergle/bike-app:${{ steps.tag.outputs.value }}
|
||||
@@ -17,8 +17,9 @@ say so and argue it — but don't silently contradict it.
|
||||
apps/api/ Python 3.12 / FastAPI / SQLAlchemy async / Alembic
|
||||
apps/web/ SvelteKit static SPA (installable PWA)
|
||||
packages/openapi/ openapi.json — COMMITTED contract artefact, CI enforces it matches the code
|
||||
deploy/ single-container Dockerfile, Caddyfile, systemd units, backup scripts —
|
||||
see docs/DECISIONS.md D15 for why this isn't docker-compose
|
||||
Dockerfile single-container build (root, not deploy/ — needs both apps/api and apps/web
|
||||
as build context). See docs/DECISIONS.md D15/D16 for why one container.
|
||||
deploy/ Caddyfile, entrypoint.sh, unraid-template.xml, systemd backup units
|
||||
docs/ plan, decisions, research
|
||||
scripts/ repo tooling (PR helpers, etc.)
|
||||
.gitea/workflows/ CI
|
||||
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
# syntax=docker/dockerfile:1
|
||||
#
|
||||
# Single-container image for Velodrome (docs/DECISIONS.md D15/D16): Caddy serves the SvelteKit
|
||||
# static SPA and reverse-proxies /api/* to the FastAPI app, both running in the same container
|
||||
# behind whatever TLS-terminating reverse proxy already exists on the host. Build context is the
|
||||
# repo root, since this needs both apps/api and apps/web:
|
||||
#
|
||||
# docker build -t velodrome .
|
||||
#
|
||||
# Replaces apps/api/Dockerfile and apps/web/Dockerfile from the old 4-container compose plan
|
||||
# (PR #4, closed as superseded) — those built two images meant to run as separate services;
|
||||
# this builds one.
|
||||
|
||||
# ---- web: produces /app/build, nothing from this stage ends up running ----
|
||||
FROM node:22-slim AS web-builder
|
||||
WORKDIR /app
|
||||
COPY apps/web/package.json apps/web/pnpm-lock.yaml ./
|
||||
RUN corepack enable && corepack prepare pnpm@9 --activate \
|
||||
&& pnpm install --frozen-lockfile
|
||||
COPY apps/web .
|
||||
RUN pnpm run build
|
||||
|
||||
# ---- api: produces the venv at /app/.venv ----
|
||||
FROM python:3.12-slim AS api-builder
|
||||
RUN pip install --no-cache-dir uv
|
||||
WORKDIR /app
|
||||
COPY apps/api/pyproject.toml apps/api/uv.lock ./
|
||||
# Dependencies first, isolated from source changes, so touching velodrome/ doesn't invalidate
|
||||
# this layer.
|
||||
RUN uv sync --frozen --no-install-project --no-dev
|
||||
COPY apps/api/velodrome ./velodrome
|
||||
COPY apps/api/alembic ./alembic
|
||||
COPY apps/api/alembic.ini ./
|
||||
RUN uv sync --frozen --no-dev
|
||||
|
||||
# ---- runtime ----
|
||||
FROM python:3.12-slim AS runtime
|
||||
|
||||
# Caddy's official images ship a single statically-linked Go binary (no CGO) — copying it out of
|
||||
# the upstream image is the standard way to get Caddy into a non-Caddy base image without a
|
||||
# second package manager or a source build.
|
||||
COPY --from=caddy:2 /usr/bin/caddy /usr/bin/caddy
|
||||
|
||||
# tini is PID 1: reaps zombies and forwards signals correctly to entrypoint.sh's two background
|
||||
# processes, which a bare `CMD` running a shell script as PID 1 would not do on its own.
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends tini \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
RUN groupadd --system velodrome && useradd --system --gid velodrome --create-home velodrome
|
||||
|
||||
WORKDIR /app
|
||||
COPY --from=api-builder --chown=velodrome:velodrome /app /app
|
||||
COPY --from=web-builder --chown=velodrome:velodrome /app/build /srv/web
|
||||
COPY --chown=velodrome:velodrome deploy/Caddyfile /etc/caddy/Caddyfile
|
||||
COPY --chown=velodrome:velodrome deploy/entrypoint.sh /app/entrypoint.sh
|
||||
RUN chmod +x /app/entrypoint.sh
|
||||
|
||||
ENV PATH="/app/.venv/bin:$PATH"
|
||||
# Absolute path into the mounted volume below. See deploy/README.md for the full env var table —
|
||||
# this is the one variable NOT meant to be overridden per-deployment, since /data is the contract
|
||||
# with the volume mount, not a per-instance setting.
|
||||
ENV VELODROME_DATABASE_URL="sqlite+aiosqlite:////data/velodrome.db"
|
||||
|
||||
RUN mkdir -p /data && chown velodrome:velodrome /data
|
||||
|
||||
USER velodrome
|
||||
VOLUME ["/data"]
|
||||
# Non-privileged port: Caddy needs no root/setcap here, and TLS termination is the host reverse
|
||||
# proxy's job (docs/PLAN.md "Service topology"), not this container's.
|
||||
EXPOSE 8080
|
||||
|
||||
ENTRYPOINT ["tini", "--"]
|
||||
CMD ["/app/entrypoint.sh"]
|
||||
@@ -1,31 +0,0 @@
|
||||
# syntax=docker/dockerfile:1
|
||||
FROM python:3.12-slim AS builder
|
||||
|
||||
RUN pip install --no-cache-dir uv
|
||||
|
||||
WORKDIR /app
|
||||
COPY pyproject.toml uv.lock ./
|
||||
# Split into two syncs so dependency installation caches independently of source changes: this
|
||||
# first one installs only dependencies (--no-install-project), so touching velodrome/ doesn't
|
||||
# invalidate this layer.
|
||||
RUN uv sync --frozen --no-install-project --no-dev
|
||||
|
||||
COPY velodrome ./velodrome
|
||||
COPY alembic ./alembic
|
||||
COPY alembic.ini ./
|
||||
# Now install the project itself into the same venv.
|
||||
RUN uv sync --frozen --no-dev
|
||||
|
||||
FROM python:3.12-slim AS runtime
|
||||
|
||||
RUN groupadd --system velodrome && useradd --system --gid velodrome --create-home velodrome
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app /app
|
||||
ENV PATH="/app/.venv/bin:$PATH"
|
||||
USER velodrome
|
||||
|
||||
EXPOSE 8000
|
||||
|
||||
# Migrations run as an explicit step before this in deploy.yml (see docs/PLAN.md) — never from
|
||||
# the entrypoint, so a failed migration fails the deploy visibly instead of crash-looping here.
|
||||
CMD ["uvicorn", "velodrome.app:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
@@ -1,36 +0,0 @@
|
||||
# This image's ONLY purpose is to produce /app/build — the static SPA output
|
||||
# (HTML/CSS/JS/manifest/service worker). There is no Node runtime in
|
||||
# production: per docs/PLAN.md's "Stack" and "The PWA decision", Caddy serves
|
||||
# these files directly and proxies /api/* to the FastAPI backend. This image
|
||||
# is never run as a long-lived container in production.
|
||||
#
|
||||
# Build context: this directory (apps/web), e.g. `docker build -f
|
||||
# apps/web/Dockerfile apps/web`.
|
||||
#
|
||||
# How deploy/ is expected to consume this: build this image, then copy its
|
||||
# /app/build contents out into a location the `caddy` service in
|
||||
# deploy/docker-compose.yml bind-mounts — either via a multi-stage
|
||||
# `COPY --from=bennybergle/velodrome-web:<tag> /app/build /srv/web` in the
|
||||
# Caddy image build, or with a one-shot `docker create` + `docker cp` /
|
||||
# `docker run --rm -v ...` step in the deploy pipeline that dumps /app/build
|
||||
# into a named volume or bind-mounted host directory before `caddy` starts.
|
||||
# Picked this over a scratch/busybox "artifact-holder" final stage because a
|
||||
# single builder stage is simpler to reason about and there's nothing here
|
||||
# that needs to run — the consumer only ever needs the files, not a container.
|
||||
# The deploy/ agent may adjust this to whatever's simplest for the compose
|
||||
# setup; this is just the contract (build → /app/build).
|
||||
|
||||
FROM node:22-slim AS builder
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# Install dependencies first, isolated from source changes, for layer caching.
|
||||
COPY package.json pnpm-lock.yaml ./
|
||||
RUN corepack enable && corepack prepare pnpm@9 --activate \
|
||||
&& pnpm install --frozen-lockfile
|
||||
|
||||
COPY . .
|
||||
RUN pnpm run build
|
||||
|
||||
# Nothing further: /app/build is the artifact. No CMD/ENTRYPOINT — this image
|
||||
# is not meant to be run.
|
||||
+7
-19
@@ -77,23 +77,11 @@ false`, and `vite.config.ts` configures `@sveltejs/adapter-static` with `fallbac
|
||||
- **Styling.** Plain CSS (`src/app.css`), CSS custom properties for theming, `prefers-color-scheme`
|
||||
for dark mode. No Tailwind — kept the dependency surface small for this scaffolding phase.
|
||||
|
||||
## Dockerfile
|
||||
## Docker build
|
||||
|
||||
This image's **only** purpose is to produce `/app/build` (the static SPA output) as a buildable
|
||||
artifact — see the comment block at the top of `Dockerfile` for the full rationale. There is no
|
||||
Node runtime in production; Caddy serves the built files directly and proxies `/api/*` to the API
|
||||
container (`docs/PLAN.md`, "Service topology"). This image is never run as a long-lived container.
|
||||
|
||||
Build it with the `apps/web` directory as context:
|
||||
|
||||
```sh
|
||||
docker build -f apps/web/Dockerfile -t velodrome-web-build apps/web
|
||||
```
|
||||
|
||||
How `deploy/` is expected to consume it (my assumption — the `deploy/` work is happening in a
|
||||
parallel worktree, so this may get adjusted there): a multi-stage `COPY --from=velodrome-web-build
|
||||
/app/build /srv/web` in whatever image serves Caddy, or a one-shot `docker create` +
|
||||
`docker cp` / bind-mount step in the deploy pipeline that populates the volume Caddy reads from
|
||||
before it starts. Went with a single plain builder stage (no `scratch`/`busybox` artifact-holder
|
||||
final stage) because nothing here needs to _run_ — the only thing anyone needs from this image is
|
||||
the files in `/app/build`, and a second stage would add complexity without adding anything.
|
||||
There is no `apps/web/Dockerfile` anymore. Per D15/D16 (`docs/DECISIONS.md`), the whole app ships
|
||||
as one container, so building this SPA is a stage in the root `Dockerfile`
|
||||
(`web-builder`, `apps/web` as its `COPY` source), not a standalone image — the built output
|
||||
(`/app/build`) is copied straight into the runtime stage at `/srv/web`, which is what the root
|
||||
`Dockerfile`'s Caddy config (`deploy/Caddyfile`) serves. There is no Node runtime in production.
|
||||
See `deploy/README.md` for the actual single-container build/run instructions.
|
||||
|
||||
@@ -0,0 +1,31 @@
|
||||
# Single-container Caddy config (docs/DECISIONS.md D15). Serves the static SvelteKit build and
|
||||
# reverse-proxies /api/* to uvicorn on loopback — the same split apps/web/vite.config.ts's dev
|
||||
# proxy describes, just as Caddy directives instead of Vite's dev-server proxy.
|
||||
{
|
||||
admin off
|
||||
# Explicit, not just implied by using a bare port below: this container is never the TLS
|
||||
# terminator (docs/PLAN.md "Service topology" — the host's existing reverse proxy is), so
|
||||
# Caddy must never attempt to provision a certificate for whatever it's fronted by.
|
||||
auto_https off
|
||||
}
|
||||
|
||||
:8080 {
|
||||
encode gzip
|
||||
|
||||
log {
|
||||
output stdout
|
||||
}
|
||||
|
||||
handle /api/* {
|
||||
reverse_proxy 127.0.0.1:8000
|
||||
}
|
||||
|
||||
# SPA fallback matching apps/web/vite.config.ts's `adapter({ fallback: 'index.html' })`:
|
||||
# any path that isn't a real built file resolves to index.html so client-side routing works
|
||||
# on a hard refresh / direct link.
|
||||
handle {
|
||||
root * /srv/web
|
||||
try_files {path} /index.html
|
||||
file_server
|
||||
}
|
||||
}
|
||||
+86
-1
@@ -1 +1,86 @@
|
||||
docker-compose, Caddyfile, systemd backup units. Not yet written — Phase 0.
|
||||
# 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.
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
#!/bin/bash
|
||||
# Single-container entrypoint (docs/DECISIONS.md D16). Two responsibilities:
|
||||
#
|
||||
# 1. Run migrations before serving anything. There's no separate "run migrations, then start the
|
||||
# app" step in front of this container the way docs/PLAN.md's original deploy.yml had one for
|
||||
# the 3-container Postgres stack (see apps/api/Dockerfile's history) — a single container has
|
||||
# nowhere else to put that step. `set -e` means a failed migration exits non-zero here, which
|
||||
# still fails startup visibly (Docker/Unraid shows the container as exited/restarting) instead
|
||||
# of silently serving a broken app; that's the property the separate step existed to protect,
|
||||
# preserved by a different mechanism now that there's only one container to do it in.
|
||||
# 2. Run uvicorn and Caddy as two background processes and tie their lifetimes together: if either
|
||||
# one dies, kill the other and exit with its status, so Docker/Unraid restarts the whole
|
||||
# container. Two half-alive processes (API up, web serving stale/nothing, or vice versa) is a
|
||||
# worse failure mode than a clean restart.
|
||||
set -euo pipefail
|
||||
|
||||
alembic -c /app/alembic.ini upgrade head
|
||||
|
||||
# uvicorn binds loopback only — Caddy is the sole process with an exposed port, and the sole
|
||||
# thing that talks to uvicorn (see deploy/Caddyfile's reverse_proxy target).
|
||||
uvicorn velodrome.app:app --host 127.0.0.1 --port 8000 &
|
||||
API_PID=$!
|
||||
|
||||
caddy run --config /etc/caddy/Caddyfile --adapter caddyfile &
|
||||
CADDY_PID=$!
|
||||
|
||||
trap 'kill -TERM "$API_PID" "$CADDY_PID" 2>/dev/null || true' TERM INT
|
||||
|
||||
wait -n "$API_PID" "$CADDY_PID"
|
||||
EXIT_CODE=$?
|
||||
kill -TERM "$API_PID" "$CADDY_PID" 2>/dev/null || true
|
||||
exit "$EXIT_CODE"
|
||||
@@ -0,0 +1,37 @@
|
||||
<?xml version="1.0"?>
|
||||
<!--
|
||||
Unraid Docker "Template" for Community Applications' Add-Container form. This is what turns the
|
||||
env vars in the table below into fillable fields in the Unraid web UI instead of a .env file —
|
||||
see docs/DECISIONS.md D16 for why this exists.
|
||||
|
||||
Import: Docker tab -> Add Container -> Template drop-down -> pick this file (or paste the
|
||||
"Template" URL if this repo is served over http from the Gitea instance). Every field is also
|
||||
editable by hand afterward; nothing here is load-bearing beyond being a starting point.
|
||||
-->
|
||||
<Container version="2">
|
||||
<Name>velodrome</Name>
|
||||
<Repository>192.168.0.3:3000/bbergle/bike-app:latest</Repository>
|
||||
<Registry>http://192.168.0.3:3000/BBergle/-/packages/container/bike-app</Registry>
|
||||
<Network>bridge</Network>
|
||||
<Privileged>false</Privileged>
|
||||
<Support>https://192.168.0.3:3000/BBergle/bike-app/issues</Support>
|
||||
<Project>http://192.168.0.3:3000/BBergle/bike-app</Project>
|
||||
<Overview>Self-hosted cycling app: Bryton Rider 650 ride sync, mileage tracking, spare-parts inventory, and maintenance reminders. One container: Caddy + the FastAPI app + a SQLite database file on the Data path below. See docs/PLAN.md and docs/DECISIONS.md (D15/D16) in the repo for the design.</Overview>
|
||||
<Category>Productivity:</Category>
|
||||
<WebUI>http://[IP]:[PORT:8080]/</WebUI>
|
||||
<Icon/>
|
||||
<ExtraParams/>
|
||||
<PostArgs/>
|
||||
<CPUset/>
|
||||
<DateInstalled/>
|
||||
<DonateText/>
|
||||
<DonateLink/>
|
||||
<Description>Self-hosted cycling app: Bryton ride sync, mileage tracking, spare-parts inventory, maintenance reminders.</Description>
|
||||
<Config Name="Web UI Port" Target="8080" Default="8080" Mode="tcp" Description="Container's HTTP port. Put a reverse proxy with TLS in front of this — the container itself only ever serves plain HTTP (docs/PLAN.md 'Service topology')." Type="Port" Display="always" Required="true" Mask="false">8080</Config>
|
||||
<Config Name="Data" Target="/data" Default="/mnt/user/appdata/velodrome" Mode="rw" Description="The SQLite database file (and, in a later phase, the raw-file blob store) live here. This is the only thing worth backing up." Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/velodrome</Config>
|
||||
<Config Name="VELODROME_PUBLIC_URL" Target="VELODROME_PUBLIC_URL" Default="" Mode="" Description="The externally-visible URL this instance is reachable at, e.g. https://bikes.example.com. Must match exactly what's in the browser's address bar — it's checked against the Origin header on cookie-authenticated requests to stop cross-site request forgery." Type="Variable" Display="always" Required="true" Mask="false"></Config>
|
||||
<Config Name="VELODROME_SECRET_KEY" Target="VELODROME_SECRET_KEY" Default="" Mode="" Description="A random secret, 32+ bytes. Generate one with: openssl rand -hex 32. The image ships an insecure development placeholder — always override this before exposing the container to anything." Type="Variable" Display="always" Required="true" Mask="true"></Config>
|
||||
<Config Name="VELODROME_ENVIRONMENT" Target="VELODROME_ENVIRONMENT" Default="production" Mode="" Description="development | test | production. Gates the session cookie's Secure flag — leave this as production for any deployment reachable over HTTPS." Type="Variable" Display="always" Required="true" Mask="false">production</Config>
|
||||
<Config Name="VELODROME_SESSION_TTL_DAYS" Target="VELODROME_SESSION_TTL_DAYS" Default="90" Mode="" Description="Days before a login session expires and re-authentication is required." Type="Variable" Display="advanced" Required="false" Mask="false">90</Config>
|
||||
<Config Name="VELODROME_SESSION_COOKIE_NAME" Target="VELODROME_SESSION_COOKIE_NAME" Default="vd_session" Mode="" Description="Name of the session cookie. No reason to change this unless it collides with another app on the same domain." Type="Variable" Display="advanced" Required="false" Mask="false">vd_session</Config>
|
||||
</Container>
|
||||
@@ -181,6 +181,58 @@ containment), #6 (single ingestion path) — none of those were ever Postgres-sp
|
||||
(D6, opaque bearer tokens) is unaffected. FastAPI/SQLAlchemy/Alembic stay exactly as chosen in D4;
|
||||
only the database engine underneath them changed.
|
||||
|
||||
### D16 — Single-container packaging: entrypoint migrations, tini + a two-line supervisor, Caddy binary copy, Unraid template
|
||||
|
||||
**Chosen:** one Docker image (root `Dockerfile`), built by copying the SvelteKit static build and
|
||||
the API's venv into a runtime stage alongside a copied-out `caddy` binary. `deploy/entrypoint.sh`
|
||||
runs `alembic upgrade head`, then starts uvicorn (loopback-only) and Caddy as two background
|
||||
processes under `tini` as PID 1, and kills+exits if either one dies. Config surfaces as env vars
|
||||
read by the existing `VELODROME_`-prefixed Pydantic settings; `deploy/unraid-template.xml` exposes
|
||||
the required ones as Unraid Community Applications web UI fields instead of a `.env` file.
|
||||
|
||||
**Why not a real process manager (s6-overlay, supervisord):** two long-running processes with no
|
||||
dependency graph between them (Caddy doesn't need to wait on uvicorn — it just proxies) doesn't
|
||||
need a supervisor with restart policies, readiness ordering, or log multiplexing. A ~20-line bash
|
||||
script under `tini` (for correct signal forwarding and zombie reaping, which a bare shell script as
|
||||
PID 1 doesn't do) gets the one property that matters — if either process dies, the whole container
|
||||
exits non-zero so Docker/Unraid restarts it — without a new dependency or a config format to learn.
|
||||
Revisit if a third long-running process gets added later; two is the reasonable ceiling for "just
|
||||
write the script."
|
||||
|
||||
**Why migrations run from the entrypoint, contradicting what apps/api/Dockerfile's own comment
|
||||
used to say** ("Migrations run as an explicit step before this in deploy.yml... never from the
|
||||
entrypoint, so a failed migration fails the deploy visibly instead of crash-looping here"): that
|
||||
comment described the 3-container Postgres plan, where a separate `run --rm api alembic upgrade
|
||||
head` step existed *before* `compose up -d`. A single container has nowhere else to put that step.
|
||||
The property it was protecting — a failed migration must be visible, not silently served — still
|
||||
holds: `set -e` means the script exits non-zero on migration failure, so the container never starts
|
||||
serving traffic and shows as exited/restarting in `docker ps`/Unraid, which is the same visibility
|
||||
by a different mechanism. What's genuinely lost is the *old* mechanism's failure mode of "the
|
||||
previous version keeps running while the bad migration is investigated" — a single container that
|
||||
fails to start migrations has no previous version still up. Acceptable for a single-instance
|
||||
home-lab deployment; would need reconsidering (e.g. a blue/green swap) if this ever needed
|
||||
zero-downtime deploys.
|
||||
|
||||
**Why the Caddy binary is copied from `caddy:2` rather than using a Caddy base image:** the runtime
|
||||
needs both Python (for uvicorn) and Caddy; picking either official base image as the starting
|
||||
point means installing the other stack into it by hand. Caddy's official images are a single
|
||||
statically-linked Go binary with no CGO, so `COPY --from=caddy:2 /usr/bin/caddy /usr/bin/caddy`
|
||||
into a `python:3.12-slim` base is the documented, standard way to get both without a second
|
||||
package manager or a source build.
|
||||
|
||||
**Why an Unraid template file, not just documentation:** the earlier decision (in-session) was to
|
||||
move configuration out of a `.env` file and into fields the Unraid web UI can fill in — a plain env
|
||||
var table in a README doesn't do that by itself, since Unraid still needs a `Config`-tagged XML
|
||||
entry per field to render one. `deploy/unraid-template.xml` is that; every field stays hand-editable
|
||||
in the UI afterward regardless of what the template pre-fills, so getting a default slightly wrong
|
||||
here isn't load-bearing.
|
||||
|
||||
**What this doesn't do:** `.gitea/workflows/release.yml` builds and pushes the image to the Gitea
|
||||
registry; it does not SSH into the Unraid host and recreate the running container. Rolling a new
|
||||
image out is a manual/Unraid-side action (pull + Apply, or Unraid's own update check), not
|
||||
something CI does unattended — consistent with treating "affects a shared, already-running system"
|
||||
as something a human triggers, not automation.
|
||||
|
||||
---
|
||||
|
||||
## Deliberately deferred
|
||||
|
||||
Reference in New Issue
Block a user