ee4ac44 removed the api_data volume, which left the panel's Settings ->
PocketBase and Settings -> Web App screens with nowhere to persist to: they
apply at runtime and the container environment wins again on restart. That
is only acceptable if the environment is actually reachable by an operator,
and for two of those keys it was not - WEBAPP_URL was hardcoded in all four
compose files, and POCKETBASE_URL in the two multi-container ones, so
there was no supported way to change them at all.
Both are now ${VAR:-default} with the previous hardcoded value as the
default, so nothing moves for an existing .env while the keys become
settable. CORS_ALLOW_ORIGINS and the admin credentials already were.
The env examples grow a section naming every setting the panel can also
change, saying plainly that the panel's version lasts only for the life of
the container, and giving the commented-out line to make it stick. It also
records the trap in WEBAPP_URL: it is a container-to-container call, so it
has to be reachable from the API Server rather than from a browser, which
is why the default is a service name and not localhost. POCKETBASE_URL is
described as repointable in the multi-container stack and left alone in the
AIO image, where it addresses that container's own PocketBase.
Also dropped two leftovers from when there were two volumes: the storage
sections still said "either".
Checked by parsing all five compose files and asserting each interpolation
default matches the value it replaced, so this cannot have moved a default
by accident. go build and go test ./... still pass (untouched here). Not
verified: no Docker CLI, so no `docker compose config` render and no build.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
01a8fec fixed the advice that led operators into this, but advice is not a
guard: a stack still running PB_BOOTSTRAP=false gets no app_settings
collection on upgrade, and the plugin panel sits at 503 while the retry
loop reads a collection that does not exist.
The fix is not to soften the reading. A missing collection stays "not
ready" rather than "no plugins configured", because the alternative lets
the first save write a fresh document over settings the server merely
failed to find - the failure this whole line of work exists to prevent.
Instead the server now fixes the cause: on a missing collection it creates
that collection and reads again.
Three pieces:
bootstrap.EnsureCollection creates one named collection from the desired
schema if absent, and nothing else. Deliberately narrower than Run - no
field reconcile elsewhere, no super-admin - so it is safe to call on a
deployment that turned the full bootstrap off. It creates the collection
the server cannot start without, not the schema the operator declined.
The store tells a missing collection apart from an outage. A 404 from a
list means the collection itself is gone: an existing but empty one answers
200 with no items. That is tagged errNoCollection, which wraps errNotReady
so every write is still refused, and IsMissingCollection narrows it. The
distinction matters because the remedies are opposites - creating
collections against a flaky database is exactly the wrong reflex, and a
test pins that an outage does not trigger it.
loadPlugins acts on the tag once, then re-reads. Failing to create is
reported as the original read error rather than the repair's, so the log
names the real problem.
Six tests: the tag and its negative in internal/plugins, and three in
internal/api against a fake PocketBase covering the collection being
created exactly once, an existing collection not being recreated, and an
outage creating nothing.
Docs from 01a8fec are corrected in the same pass - they said the panel
would answer 503 forever, which is no longer true. They now say what still
depends on the bootstrap (every other collection and field) and what does
not (app_settings alone).
go build, go vet and go test ./... pass; compose files still parse. Not
verified: no Docker CLI here, so the repair has not been exercised against
a real PocketBase, only the fake.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every deployment file advised setting PB_BOOTSTRAP=false "once the database
is established". That was harmless while the schema was static. It stopped
being harmless in 9bd5c52, which moved the plugin settings into a new
app_settings collection: a stack upgraded with the bootstrap off never gets
that collection, and a missing collection is deliberately read as "the
database is not ready" rather than "no plugins configured" - so the plugin
panel answers 503 indefinitely and the background retry spins forever.
Fixing the advice rather than the reading: treating a missing collection as
empty would let the first save write a fresh document over settings the
server had simply failed to find, which is the failure this whole line of
work exists to prevent.
So all four compose files, all four .env examples, both stack READMEs and
the AIO Dockerfile now say to leave the bootstrap on, including across
upgrades, and name the symptom an operator would otherwise have to guess
at. Turning it off is still supported, but framed as something to do only
for a database known to match the running release.
Compose files still parse as YAML; go build, go vet and go test ./... pass
(untouched by this commit - it is comments and docs only). Note that this
is guidance, not a guard: an operator who sets PB_BOOTSTRAP=false anyway
still ends up in the same place, and the server would have to re-run the
bootstrap when it finds the collection missing to make that impossible.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The all-in-one image builds from the project root, and Docker only reads
.dockerignore from the context root — so the ones under "API Server" and
"Web App" never applied to it and every AIO build shipped the whole tree,
"Phone App/build" included. A root .dockerignore allow-lists the paths that
build actually copies.
The dev split stack passed neither PB_BOOTSTRAP nor the SUPERADMIN vars, so
it created the schema and then no user to log in with. It passes them now,
and .env.example says so.
WEBAPP_URL was never set anywhere, leaving the panel status page probing
localhost:8090 — itself — and always reporting the Web App as down. Each
compose file now points it at wherever the Web App really is, and the BFF
grew a real /healthz instead of letting the SPA fallback answer probes with
index.html and look healthy no matter what.
In the AIO, PocketBase and the API Server drop to an unprivileged user;
only nginx stays root to bind :80. The entrypoint takes ownership of the
two volumes first, so data written by the old root-only image stays
writable. All three images carry a HEALTHCHECK, every compose file declares
one too (so depends_on still gates against an older pulled image), and
web-app waits for the API Server to be serving rather than merely started.
Also: pinned alpine/golang/node and PocketBase 0.39.11, so a rebuild months
from now produces the same image; nginx forwards WebSocket upgrades instead
of stripping them, with the map in http.d where Alpine actually reads it;
and a .gitattributes keeps entrypoint.sh on LF, because a CRLF shebang from
a Windows clone fails at container start with "no such file or directory".
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The all-in-one folder is now Docker-AIO, so -f Docker-AIO/Dockerfile
resolves without quoting. Every path that pointed at the old name
follows it: the compose build stanza, the documented build commands,
and the links from the two READMEs.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
