Fix: a docker source build reported "dev", not its version

[tbcsec]

What & why

A fresh git clone + docker compose up --build reported its version as dev, not 1.2.0-src — the README's headline install path, so most deployments.

backend/Dockerfile had:

ARG APP_VERSION=dev
ENV APP_VERSION=${APP_VERSION}

A Dockerfile has no conditional ENV, so that line always runs — and pydantic-settings ranks an environment variable above the Python default. ENV APP_VERSION=dev therefore shadowed config.py's "1.2.0-src" on every source build.

Two consequences, the second worse than the first:

1. Adoption data collapsed into one opaque dev bucket with no version granularity.
2. Source deployments could never be told a new release existed — "dev" doesn't parse, so is_newer() always returned False.

#124 changed the Python default from "dev" to "1.2.0-src" but never touched the env var overriding it, so it fixed nothing for the path that matters.

The fix

ARG APP_VERSION= — empty, meaning "not a release image" — with a validator in config.py resolving blank to SOURCE_BUILD_VERSION. Blank includes whitespace: a quoted compose value or a heredoc newline would otherwise reach the update endpoint and be bucketed as invalid.

Verified across every path:

APP_VERSION	reports
unset (bare uvicorn)	1.2.0-src
"" (source docker build)	1.2.0-src
" " (whitespace)	1.2.0-src
" v1.2.0 \n" (stray newline)	v1.2.0
v1.2.0 (release image)	v1.2.0

The default also moves out of the settings field into a module constant, so there's one name to grep, bump and assert on rather than a literal buried in a class.

Guards on the mechanism, not the value

The value read 1.2.0-src correctly the whole time — only the interaction was wrong. So both new guards check the mechanism:

• a test asserting ARG APP_VERSION carries no literal default;
• a second tag-push CI step doing the same, so a regression blocks the release rather than shipping.

Confirmed both fire: restoring ARG APP_VERSION=dev blocks.

How this got through

Worth recording, because the gap was in the testing approach rather than the code. The config default was tested by importing Settings in isolation, where no env var exists, and the existing CI guard only read config.py. Both agreed on 1.2.0-src. Neither exercised a container. A single docker compose up --build would have caught it in seconds — and that's the check that was missing when the version-resolution mechanism changed.

Checklist

• Backend tests pass — cd backend && .venv/bin/pytest (569 passed, 2 new)
• Frontend checks pass — no frontend files touched; backend-only change
• If UI-observable, I ran it in the browser and confirmed it works — the version string renders through existing code; verified at the settings layer
• Follows the architectural rules in CONTRIBUTING.md
• One migration for this PR if the schema changed — no migration, config and CI only
• This is not a security fix (those follow SECURITY.md)

Like #124, this wants merging before v1.2.0 is tagged — otherwise the first release ships images whose source-build counterpart reports the wrong version.

After merging, the useful check is a real one: pull, docker compose up --build, and confirm Admin → Site settings → General reads "Running version 1.2.0-src". A running container keeps reporting dev until rebuilt, since the value is baked at image build time.

🤖 Generated with Claude Code