An unset variable stays unset on the way into the container

[lml2468]

What

docker compose --profile app up -d — the command the README promises — exits on the first step with a clean clone:

Error: error with configuration: relative URL without a base

Three variables are declared as ${VAR:-}. When the variable is not set on the host, that does not mean "don't pass it"; it passes an empty string. UTOPIA_MIGRATION_URL="" reaches sqlx, and sqlx cannot parse "" as a URL.

blank_is_unset (#344) fixed the Rust side, and its comment already names this shape:

容器编排里 UTOPIA_X: ${UTOPIA_X:-} 这种写法，在变量没设时传进容器的是空串，不是「不传」。

This is the other half: the empty string should never be sent in the first place. Writing the key with no value is the documented Compose form for "pass it through, and leave it unset if the host has not set it".

Why not just bump the default image

That was the first instinct, and it is worse. 0.1.0-rc5 is the only published release tag, and it predates #344 — so bumping means pinning the README's headline command to dev-ed397e7, a dev build, against the compose file's own instruction to pin a released version. Fixing the compose side means the already-published rc5 boots, and no new release is needed.

Verified

Boots with the stock default unchanged (0.1.0-rc5), on an otherwise untouched clone:

image: ghcr.io/deeplethe/utopia:0.1.0-rc5
health: {"name":"utopia","status":"ok","version":"0.1.0"}
数据库迁移完成
Utopia 服务启动于 http://0.0.0.0:1516

Compose semantics checked directly, rather than assumed:

form	host unset	via .env	via host env
VAR: ${VAR:-}	set to ""	—	—
VAR:	not set at all	from_env_file	from_host

So configuring any of the three still works exactly as before; only the "nobody set it" case changes.

The regression guard

release.yml's smoke test runs docker run directly and never passes an empty UTOPIA_MIGRATION_URL, which is precisely how #343 shipped green in rc5 and broke the first command a new user types. The smoke test now passes -e UTOPIA_MIGRATION_URL= so an empty string has to behave like unset.

Confirmed the guard discriminates — it fails on the broken build and passes on the fixed one:

image	with -e UTOPIA_MIGRATION_URL=
0.1.0-rc5 (pre-#344)	exited:1 — relative URL without a base
dev-ed397e7 (post-#344)	running — Utopia 服务启动于 http://0.0.0.0:1516

Deliberately left alone

db's UTOPIA_APP_DB_PASSWORD: ${UTOPIA_APP_DB_PASSWORD:-} keeps its current form — init-app-role.sh already guards it with [ -z ], which is the check config.rs cites as the precedent for blank_is_unset.

Records

No ADR status line to update: this changes no decision, it closes the deployment gap #343 named.

Testing

YAML-only change; no Rust or web sources touched. docker compose config and a YAML parse both pass, and the boot above is the real check. The pre-push Rust suite was not run for that reason.