driver-vault/DriverVault
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docker: stop telling operators to turn off the bootstrap that upgrades them

Browse Source 
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>
This commit is contained in:
tajniak81
2026-08-21 17:02:14 +02:00
co-authored by Claude Opus 5
parent 9bd5c523c4
commit 01a8fecf40
12 changed files with 63 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
API Server/README.md
+1 -1
View File
@@ -321,7 +321,7 @@ Copy `.env.example` to `.env` and fill in. Summary:
| `PLUGINS_FILE` | `plugins.json` | legacy plugin store, imported once then renamed |
| `OCPP_REQUIRE_TLS` | `true` | reject chargers that did not connect over TLS |
| `OCPP_PUBLIC_URL` | — | canonical `ws(s)://` base to point chargers at |
| `PB_BOOTSTRAP` | `true` | run the on-boot schema create/reconcile |
| `PB_BOOTSTRAP` | `true` | run the on-boot schema create/reconcile (leave on across upgrades) |
| `DRIVERVAULT_SUPERADMIN_EMAIL` / `_PASSWORD` / `_NAME` | — / — / `Administrator` | first `superadmin`, created on boot when absent |
`PB_URL`, `PB_ADMIN_EMAIL`, `PB_ADMIN_PASSWORD`, `PORT` and `CORS_ORIGINS` are
Docker-AIO/.env.example
+4 -1
View File
@@ -12,7 +12,10 @@ DRIVERVAULT_SUPERADMIN_EMAIL=owner@example.com
DRIVERVAULT_SUPERADMIN_PASSWORD=change-me-long-password
DRIVERVAULT_SUPERADMIN_NAME=Administrator
# Set to false to skip schema creation/reconcile once the database is set up.
# Schema creation/reconcile on boot. Leave this true: a release can add a
# collection the server needs (app_settings, which holds the plugin settings),
# and a stack that skipped the bootstrap never gets it — the plugin panel then
# answers 503 forever. Set false only for a database you know matches the release.
PB_BOOTSTRAP=true
# Allowed CORS origin(s) — match your web origin / WEB_PORT.
Docker-AIO/.env.prod.example
+4 -1
View File
@@ -18,7 +18,10 @@ DRIVERVAULT_SUPERADMIN_EMAIL=owner@example.com
DRIVERVAULT_SUPERADMIN_PASSWORD=change-me-long-password
DRIVERVAULT_SUPERADMIN_NAME=Administrator
# Set to false to skip schema creation/reconcile once the database is set up.
# Schema creation/reconcile on boot. Leave this true: a release can add a
# collection the server needs (app_settings, which holds the plugin settings),
# and a stack that skipped the bootstrap never gets it — the plugin panel then
# answers 503 forever. Set false only for a database you know matches the release.
PB_BOOTSTRAP=true
# Allowed CORS origin(s) — match your public web URL / WEB_PORT.
Docker-AIO/Dockerfile
+4 -1
View File
@@ -219,7 +219,10 @@ ENV API_ADDR=:8080 \
# Required at runtime (no safe defaults): PB_ADMIN_EMAIL, PB_ADMIN_PASSWORD.
# Optional: DRIVERVAULT_SUPERADMIN_EMAIL / DRIVERVAULT_SUPERADMIN_PASSWORD create
# the first app super-admin on boot; PB_BOOTSTRAP=false skips schema setup.
# the first app super-admin on boot. PB_BOOTSTRAP=false skips schema setup —
# leave it on: a release can add a collection the server needs (app_settings,
# which holds the plugin settings), and a stack that skipped the bootstrap never
# gets it, leaving the plugin panel answering 503 indefinitely.
# For Anker Solix charger control, OCPP_REQUIRE_TLS (default true) rejects
# chargers that did not arrive over TLS — this image serves plain HTTP, so put a
# TLS-terminating proxy in front and set OCPP_PUBLIC_URL to the public wss://
Docker-AIO/README.md
+8 -2
View File
@@ -62,8 +62,14 @@ Identical to the multi-container stack, and idempotent:
1. PocketBase upserts its superuser from `PB_ADMIN_EMAIL` / `PB_ADMIN_PASSWORD`.
2. The API Server waits for PocketBase to report healthy, then creates any
missing collections, reconciles existing ones, and creates the first app
`superadmin` from `DRIVERVAULT_SUPERADMIN_EMAIL` / `_PASSWORD`. Set
`PB_BOOTSTRAP=false` to skip once the database is established.
`superadmin` from `DRIVERVAULT_SUPERADMIN_EMAIL` / `_PASSWORD`.
> Leave `PB_BOOTSTRAP` at `true`, including across upgrades. A release can add a
> collection the server needs — `app_settings`, which holds the plugin settings,
> is one — and a stack that skipped the bootstrap never gets it. The plugin panel
> then answers `503` indefinitely, because a missing collection is read as "the
> database is not ready yet", never as "no plugins configured". Turn it off only
> for a database you know already matches the release you are running.
## Volumes
Docker-AIO/docker-compose.prod.yml
+6 -2
View File
@@ -26,8 +26,12 @@ services:
# Probed by the panel status page. nginx serves the Web App on port 80
# inside this container, so the default (localhost:8090) would never answer.
WEBAPP_URL: "http://127.0.0.1:80"
# Schema + super-admin bootstrap on boot (idempotent). Set PB_BOOTSTRAP=false
# to skip once the database is established.
# Schema + super-admin bootstrap (idempotent). Leave this ON. A release can
# add a collection the server needs — app_settings, holding the plugin
# settings, is one — and a stack that skipped the bootstrap never gets it:
# the plugin panel then answers 503 forever, because a missing collection
# is read as "database not ready", never as "no plugins configured".
# Turn it off only for a database you know already matches the release.
PB_BOOTSTRAP: "${PB_BOOTSTRAP:-true}"
DRIVERVAULT_SUPERADMIN_EMAIL: "${DRIVERVAULT_SUPERADMIN_EMAIL:-}"
DRIVERVAULT_SUPERADMIN_PASSWORD: "${DRIVERVAULT_SUPERADMIN_PASSWORD:-}"
Docker-AIO/docker-compose.yml
+6 -2
View File
@@ -29,8 +29,12 @@ services:
# Probed by the panel status page. nginx serves the Web App on port 80
# inside this container, so the default (localhost:8090) would never answer.
WEBAPP_URL: "http://127.0.0.1:80"
# Schema + super-admin bootstrap on boot (idempotent). Set PB_BOOTSTRAP=false
# to skip once the database is established.
# Schema + super-admin bootstrap (idempotent). Leave this ON. A release can
# add a collection the server needs — app_settings, holding the plugin
# settings, is one — and a stack that skipped the bootstrap never gets it:
# the plugin panel then answers 503 forever, because a missing collection
# is read as "database not ready", never as "no plugins configured".
# Turn it off only for a database you know already matches the release.
PB_BOOTSTRAP: "${PB_BOOTSTRAP:-true}"
DRIVERVAULT_SUPERADMIN_EMAIL: "${DRIVERVAULT_SUPERADMIN_EMAIL:-}"
DRIVERVAULT_SUPERADMIN_PASSWORD: "${DRIVERVAULT_SUPERADMIN_PASSWORD:-}"
Docker/.env.example
+4 -1
View File
@@ -12,7 +12,10 @@ DRIVERVAULT_SUPERADMIN_EMAIL=owner@example.com
DRIVERVAULT_SUPERADMIN_PASSWORD=change-me-long-password
DRIVERVAULT_SUPERADMIN_NAME=Administrator
# Set to false to skip schema creation/reconcile once the database is set up.
# Schema creation/reconcile on boot. Leave this true: a release can add a
# collection the server needs (app_settings, which holds the plugin settings),
# and a stack that skipped the bootstrap never gets it — the plugin panel then
# answers 503 forever. Set false only for a database you know matches the release.
PB_BOOTSTRAP=true
# --- API Server -------------------------------------------------------------
Docker/.env.prod.example
+4 -1
View File
@@ -24,7 +24,10 @@ DRIVERVAULT_SUPERADMIN_EMAIL=owner@example.com
DRIVERVAULT_SUPERADMIN_PASSWORD=change-me-long-password
DRIVERVAULT_SUPERADMIN_NAME=Administrator
# Set to false to skip schema creation/reconcile once the database is set up.
# Schema creation/reconcile on boot. Leave this true: a release can add a
# collection the server needs (app_settings, which holds the plugin settings),
# and a stack that skipped the bootstrap never gets it — the plugin panel then
# answers 503 forever. Set false only for a database you know matches the release.
PB_BOOTSTRAP=true
# --- API Server --------------------------------------------------------------
Docker/README.md
+8 -2
View File
@@ -47,8 +47,14 @@ Both steps are idempotent, so restarts and upgrades are safe:
bootstrap it. The API Server then authenticates with the same credentials.
2. **The API Server** creates any missing collections and reconciles existing
ones, then creates the first app `superadmin` from
`DRIVERVAULT_SUPERADMIN_EMAIL` / `_PASSWORD` if no such user exists. Set
`PB_BOOTSTRAP=false` to skip once the database is established.
`DRIVERVAULT_SUPERADMIN_EMAIL` / `_PASSWORD` if no such user exists.
> Leave `PB_BOOTSTRAP` at `true`, including across upgrades. A release can add a
> collection the server needs — `app_settings`, which holds the plugin settings,
> is one — and a stack that skipped the bootstrap never gets it. The plugin panel
> then answers `503` indefinitely, because a missing collection is read as "the
> database is not ready yet", never as "no plugins configured". Turn it off only
> for a database you know already matches the release you are running.
No manual `setup-pocketbase.mjs` step is needed here — the server runs the same
schema reconcile itself.
Docker/docker-compose.prod.yml
+6 -2
View File
@@ -59,8 +59,12 @@ services:
WEBAPP_URL: "http://web-app:8090"
CORS_ALLOW_ORIGINS: "${CORS_ALLOW_ORIGINS:-http://localhost:8090}"
AUTH_USERS_COLLECTION: "${AUTH_USERS_COLLECTION:-users}"
# Schema + super-admin bootstrap (idempotent). Set PB_BOOTSTRAP=false to
# skip it once the database is established.
# Schema + super-admin bootstrap (idempotent). Leave this ON. A release can
# add a collection the server needs — app_settings, holding the plugin
# settings, is one — and a stack that skipped the bootstrap never gets it:
# the plugin panel then answers 503 forever, because a missing collection
# is read as "database not ready", never as "no plugins configured".
# Turn it off only for a database you know already matches the release.
PB_BOOTSTRAP: "${PB_BOOTSTRAP:-true}"
DRIVERVAULT_SUPERADMIN_EMAIL: "${DRIVERVAULT_SUPERADMIN_EMAIL:-}"
DRIVERVAULT_SUPERADMIN_PASSWORD: "${DRIVERVAULT_SUPERADMIN_PASSWORD:-}"
Docker/docker-compose.yml
+8 -1
View File
@@ -52,7 +52,14 @@ services:
AUTH_USERS_COLLECTION: "${AUTH_USERS_COLLECTION:-users}"
# Schema + super-admin bootstrap (idempotent). Without the SUPERADMIN vars
# the collections are still created but no app user is, leaving a stack
# you cannot log into. Set PB_BOOTSTRAP=false to skip once established.
# you cannot log into.
#
# Leave the bootstrap ON. A release can add a collection the server needs —
# app_settings, holding the plugin settings, is one — and a stack that
# skipped it never gets that collection: the plugin panel then answers 503
# forever, because a missing collection is read as "database not ready",
# never as "no plugins configured". Turn it off only for a database you
# know already matches the release.
PB_BOOTSTRAP: "${PB_BOOTSTRAP:-true}"
DRIVERVAULT_SUPERADMIN_EMAIL: "${DRIVERVAULT_SUPERADMIN_EMAIL:-}"
DRIVERVAULT_SUPERADMIN_PASSWORD: "${DRIVERVAULT_SUPERADMIN_PASSWORD:-}"