Charger control needs TLS, and the stack speaks plain HTTP, so the README
said "terminate TLS in a reverse proxy" and left the operator to work out
which four settings have to agree. This adds the proxy: a Caddy overlay
that fronts the Web App BFF — which already carries /api/ and /ocpp/ — so
browsers and chargers arrive at the same name and the certificate is issued
on first boot.
The four settings are derived from DV_DOMAIN, since one value getting typed
right is better odds than four: OCPP_PUBLIC_URL, OCPP_REQUIRE_TLS back on,
CORS, and TRUST_FORWARDED_PROTO on the Web App. That last one is the
non-obvious one — without it the BFF overwrites Caddy's X-Forwarded-Proto
with its own plaintext hop and the API Server rejects the charger it just
told to connect over wss.
The README's OCPP section was stale besides: it still sent chargers to the
API Server port alone, from before the BFF carried that path.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The project has no public installs, so there is nothing to migrate from.
MigrateLegacyFile, the file-backed Store it read through, PLUGINS_FILE and
the legacy path threaded through the Server all go. What is left is one
store, PocketBase, and a plugins package that touches no filesystem at all.
That was the last thing keeping api_data alive, so the volume goes too. All
four compose files now declare exactly one volume, pb_data, and the
standalone API Server compose declares none - it talks to an external
PocketBase and has nothing of its own to keep. Backing up the stack is
backing up one path again.
Both images get simpler for it. The API Server image loses VOLUME /data and
the su-exec entrypoint that existed only to fix a mounted volume's
ownership, so it goes back to a plain USER app; its working directory is
now /app and holds nothing. The AIO image loses its second volume and
chowns only /pb/pb_data.
One consequence worth stating plainly, because it is a small regression
rather than a no-op. The panel's Settings -> PocketBase and Settings -> Web
App screens write .env in the working directory, which is now ephemeral. In
the multi-container stack that changes nothing: compose sets all five of
those keys as container environment, and loadDotEnv only applies a key that
is not already set, so the file could never win a restart there anyway. In
the AIO image it did win for POCKETBASE_ADMIN_EMAIL/_PASSWORD, which are
not in that container's environment - so a service account fixed from the
panel now lasts only until the container is recreated. Both READMEs say so.
Moving those two screens into the app_settings singleton would close it
properly; the PocketBase URL and credentials cannot follow, since they are
how the database is reached in the first place.
go build, go vet and go test ./... pass; the compose files parse and each
resolves to a single pb_data volume. Not verified: no Docker CLI here, so
neither image was built.
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 integration cascade stored its top layer differently from the two below
it: org (L2) and user (L3) plugin config lived in PocketBase, in a
pluginSettings field, while the global (L1) layer sat in a plugins.json
next to the binary. That split was accretion rather than design - the file
was the whole store in the v1 MVP, and the per-tenant layers were later
built on PocketBase and layered on top of it instead of replacing it.
It also cost something real. plugins.json was a second state store with
different durability from pb_data: its own volume, its own ownership, its
own backup. Losing pb_data is unmissable; losing api_data was silent, which
is how "every plugin comes back disabled after a redeploy" happened.
L1 now lives in the app_settings collection - one record keyed "global",
holding its settings in a pluginSettings field, the same mechanism and the
same field name the layers below use. The documents still differ in shape,
because only L1 carries enable state and the registration of external
plugins, but the storage is no longer a special case.
The Manager grows a Store seam (PocketBase in production, file for the
import, memory for tests) and, more importantly, a loaded gate. Settings in
a database mean the store can be unreachable at boot - a cold stack, or a
service account still to be set from the panel. That must not read as "no
plugins configured", or the first save would write emptiness over real
settings. So until a read succeeds the Manager stays unloaded, every
mutation is refused, /api/admin/plugins* answers 503, and a background
retry backs off to two minutes. The same gate covers a document that will
not parse: it is never replaced by one built from an empty map, which is a
stronger guarantee than the .corrupt backup it replaces.
Writing to a store also revealed a hole in the previous fix. Classifying a
save failure as errPersist was left to each Store, and a store that
returned a plain error would fall through to the "saved, but the plugin
failed to start" branch and be reported as a 200 - the same silent-success
bug through a different door. The Manager now classifies, whatever the
Store returns; a test pins it.
Upgrades are automatic: on the first boot that finds no settings in the
database, an existing plugins.json is imported and renamed to
plugins.json.migrated. The import is refused if the store is merely
unreachable, or if the file does not parse, so a stale or broken file can
never overwrite live settings. /data is still needed - the panel rewrites
.env there when it retargets PocketBase - but plugin settings no longer
depend on it.
21 tests in internal/plugins cover both stores, including the production
path against a fake PocketBase: create-then-update of the singleton,
round-trip across a restart, an outage that leaves settings intact, a
missing collection reading as not-ready rather than empty, and the import
running exactly once. go build, go vet and go test ./... pass. Schema
changes are mirrored into scripts/setup-pocketbase.mjs as that file
requires. Not verified: no Docker CLI here, so no image was built and the
bootstrap of app_settings against a real PocketBase is untested outside the
fake.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
c173ca3 gave the API Server image a root entrypoint that takes ownership of
/data and then drops to app via su-exec, which left the Volumes note in
Docker/README.md telling operators to do by hand something the image now
does for them.
The replacement says what actually happens, and keeps the two cases the
entrypoint cannot cover: a container forced to another user (`user:` in
compose, `docker run --user`) has no privileges to chown with, so its host
directory still needs preparing. It also points at the new boot warning as
the thing to look for, since the alternative symptom - plugins that enable
normally in the panel and come back disabled after a redeploy - gives no
hint about permissions.
Also states that PocketBase runs as root, so PB_DATA never had this
problem; the old note read as though it applied to both volumes.
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>
Verified each documented command, path, port and env var against what the
code actually does, and corrected the drift.
Phone App. Was still titled Car Control. The navigation description was
also stale: the app moved to a RootShell bottom nav (Garage, Charging,
Settings, and Users for admins), so the Settings gear and admin action
the dashboard bullet described no longer exist. Adds the Charging screen,
noting its public tab is placeholder data and only the Home tab's OCPP
control is real, and rebuilds the lib/ tree, which had lost i18n.dart,
theme.dart, widgets/ and three screens.
Web App. Node 18+ was wrong. The installed Vite is 8.1.2, whose engines
field is ^20.19.0 || >=22.12.0 - Node 18 is EOL and cannot build this.
API Server. The config table gained OCPP_REQUIRE_TLS, OCPP_PUBLIC_URL,
PB_BOOTSTRAP and DRIVERVAULT_SUPERADMIN_*, plus a note that PLUGINS_FILE
and the panel-written .env resolve against the working directory (a
volume, in Docker).
Plugins. Per-tenant credentials sat under "not yet implemented", but
/api/integrations/* has done exactly that for both built-ins for a while.
Narrowed the roadmap item to the genuinely missing generic version.
New Docker/README.md and Docker AIO/README.md: the root README's
component table linked those directories as documentation but neither had
any. The root README now points at them.
All 8 markdown files pass a relative-link check.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
