Docker/ gets the same deployment shapes as DriverVault: plain, SeaweedFS in the stack, SeaweedFS split into its roles, and an external S3 endpoint, each as a build-from-source and a registry compose file with an .env example of the same name, plus a README. The API Server now reads PB_S3_* on boot and points PocketBase's file storage at the bucket (only when the settings differ), then asks PocketBase to test it. It never turns S3 off. Plugin state gets an api_data volume, since the image could not write plugins.json. The PocketBase image pinned v0.22.21, which cannot run the v0.23+ migrations or `superuser upsert`; it now pins v0.39.11. Starting from an empty database also exposed two migration bugs: the seed tried to create a passwordless account, and the documents collection saved its self-relation with a blank target. Both are fixed; databases that already ran them are unaffected. Verified on Docker: the SeaweedFS and split stacks come up healthy from an empty database, uploads land in the bucket, and a restart is a no-op. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
195 lines
9.7 KiB
Markdown
195 lines
9.7 KiB
Markdown
# PilotVault — Docker (multi-container stack)
|
|
|
|
Three containers — **PocketBase**, **API Server**, **Web App** — on one compose
|
|
network. This is the deployment to use unless you specifically want everything
|
|
in a single image; for that see [`../Docker-AIO`](../Docker-AIO).
|
|
|
|
```
|
|
Browser ─► Web App BFF (:8090) ──/api/*──► API Server (:8080) ─► PocketBase (:8070)
|
|
```
|
|
|
|
Only the Web App port is meant to be public. The API Server and the PocketBase
|
|
admin UI are published for convenience and, in the prod files, bound to
|
|
`127.0.0.1` by default.
|
|
|
|
| File | Use |
|
|
|---|---|
|
|
| `docker-compose.yml` | **builds from source** in this repo — for development and local testing |
|
|
| `docker-compose.prod.yml` | **pulls prebuilt images** from the registry — for deployment |
|
|
| `.env.example` / `.env.prod.example` | copy to `.env` for the matching compose file |
|
|
| `docker-compose[.prod].{s3,seaweedfs,seaweedfs.split}.yml` | the same stack with file storage in S3 — see [File storage](#file-storage-seaweedfs--s3) |
|
|
| `pocketbase/` | the PocketBase image (official release binary on alpine, plus the bundled migrations) |
|
|
|
|
## Run it
|
|
|
|
```bash
|
|
cd Docker
|
|
cp .env.example .env # then edit — POCKETBASE_ADMIN_* have no safe defaults
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Production, from the registry:
|
|
|
|
```bash
|
|
cp .env.prod.example .env # then edit
|
|
docker compose -f docker-compose.prod.yml pull
|
|
docker compose -f docker-compose.prod.yml up -d
|
|
```
|
|
|
|
Then: web app on `http://host:8090/`, the API Server's superadmin panel on
|
|
`http://host:8080/`, PocketBase admin on `http://host:8070/_/`.
|
|
|
|
The PocketBase image builds with the **repo root** as its context (it copies the
|
|
migrations from `API Server/pocketbase/pb_migrations`), so the root
|
|
`.dockerignore` keeps the Fly/Phone apps and other siblings out of it.
|
|
|
|
## First boot
|
|
|
|
Everything happens inside PocketBase, and every step is idempotent, so restarts
|
|
and upgrades are safe:
|
|
|
|
1. **The entrypoint** upserts the PocketBase superuser from
|
|
`POCKETBASE_ADMIN_EMAIL` / `POCKETBASE_ADMIN_PASSWORD`. This is the only way to
|
|
create the first superuser — the REST API cannot bootstrap it. The API Server
|
|
then authenticates with the same credentials.
|
|
2. **PocketBase runs the bundled JS migrations**, which create/reconcile every
|
|
collection (users, organizations, drones, flights, documents, routes, plugin
|
|
settings…) and seed the baseline org and accounts, including the
|
|
`superadmin@pilotvault.local` app login.
|
|
|
|
Unlike DriverVault, the API Server does not create schema itself. A release that
|
|
adds a collection ships it as a new migration in the PocketBase image, so
|
|
upgrading means pulling/rebuilding **both** images.
|
|
|
|
> The image pins PocketBase **v0.39.11**. It must be v0.23 or newer — the
|
|
> migrations use the v0.23+ JSVM API and the entrypoint uses `superuser upsert`.
|
|
|
|
## Volumes
|
|
|
|
| Volume | Holds |
|
|
|---|---|
|
|
| `pb_data` (`PB_DATA`) | the PocketBase SQLite database, its backups and — unless S3 is on — the uploaded document blobs |
|
|
| `api_data` (`API_DATA`) | the API Server's `plugins.json`: plugin enable-state and config |
|
|
|
|
Both default to Docker-managed named volumes; set `PB_DATA` / `API_DATA` to an
|
|
absolute host path in `.env` for a bind mount instead. PocketBase runs as root,
|
|
so a root-owned host directory is fine for `pb_data`. The API Server runs as
|
|
uid 10001, so an `API_DATA` host directory must be writable by that uid (a named
|
|
volume inherits the right ownership from the image on its own).
|
|
|
|
> One thing does **not** persist: the API Server panel's *Settings → PocketBase*
|
|
> screen applies immediately but only for the life of the container. Set
|
|
> `POCKETBASE_URL`, `POCKETBASE_ADMIN_EMAIL` / `POCKETBASE_ADMIN_PASSWORD`,
|
|
> `WEBAPP_URL` and `CORS_ALLOW_ORIGINS` in `.env` to change them permanently —
|
|
> in this stack the compose environment wins over anything the panel writes.
|
|
|
|
## File storage (SeaweedFS / S3)
|
|
|
|
Uploaded files — the document store's scans of pilot certificates, aircraft
|
|
registrations, insurance and authorisations — live inside `pb_data` by default,
|
|
next to the database. The further compose files put them in an S3 bucket
|
|
instead, so the blobs and the database can be sized, backed up and moved
|
|
independently. Nothing else changes: a document has always been downloaded
|
|
through the API Server (`GET /api/documents/{id}/file`), never from a storage
|
|
URL, so the Web App and the Fly/Phone apps cannot tell the difference.
|
|
|
|
Each shape is one self-contained compose file — nothing to layer, nothing to
|
|
remember — with an `.env` example of the same name:
|
|
|
|
| Shape | From the registry | From source |
|
|
|---|---|---|
|
|
| **Local storage** — the default, unchanged | `docker-compose.prod.yml` | `docker-compose.yml` |
|
|
| **SeaweedFS in this stack** | `docker-compose.prod.seaweedfs.yml` | `docker-compose.seaweedfs.yml` |
|
|
| **SeaweedFS, split into its roles** | `docker-compose.prod.seaweedfs.split.yml` | `docker-compose.seaweedfs.split.yml` |
|
|
| **An S3 endpoint outside it** | `docker-compose.prod.s3.yml` | `docker-compose.s3.yml` |
|
|
|
|
So `docker-compose.prod.seaweedfs.yml` is configured from
|
|
`.env.prod.seaweedfs.example`, `docker-compose.s3.yml` from `.env.s3.example`,
|
|
and so on:
|
|
|
|
```sh
|
|
cp .env.prod.seaweedfs.example .env # then edit it — PB_S3_* have no defaults
|
|
docker compose -f docker-compose.prod.seaweedfs.yml pull
|
|
docker compose -f docker-compose.prod.seaweedfs.yml up -d
|
|
```
|
|
|
|
Set `PB_S3_ACCESS_KEY` and `PB_S3_SECRET` first — every storage file refuses to
|
|
start without them. The SeaweedFS ones add a `seaweedfs` container (master,
|
|
volume, filer and S3 gateway in one process, on its own `seaweed_data` volume)
|
|
plus a one-shot `seaweedfs-init` that creates the bucket, because PocketBase never
|
|
issues a `CreateBucket` of its own. The external-S3 ones add no containers at
|
|
all: set `PB_S3_ENDPOINT`, and create the bucket yourself.
|
|
|
|
### Split SeaweedFS
|
|
|
|
`weed server -s3` runs master, volume, filer and gateway as four goroutines in
|
|
one process. The `.split.` files run them as four containers, plus a fifth: the
|
|
SeaweedFS **admin UI** on port 23646, where the cluster can be inspected and —
|
|
under *Object Store → Users* — further S3 identities minted and revoked. Split
|
|
also gets you per-role restarts and upgrades, per-role Prometheus metrics, and
|
|
room to add a second volume server later.
|
|
|
|
Identities work differently there, and it matters. SeaweedFS reads credentials
|
|
from, in descending priority: an `-s3.config` file, the filer's IAM store, then
|
|
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — and a higher source *replaces*
|
|
a lower one rather than adding to it. The single-process files use the env vars,
|
|
which is why nothing else may write identities there: the first user added in a
|
|
panel would displace PocketBase's key. So in the split files `seaweedfs-init`
|
|
seeds PocketBase's identity (named `pilotvault`) into the filer's store instead —
|
|
the same store the admin UI writes — and the gateway runs with no config file at
|
|
all. One source of truth, PocketBase's key visible in the panel beside every
|
|
other, and new keys picked up without a restart. Rotating `PB_S3_SECRET` in
|
|
`.env` and restarting updates that identity in place.
|
|
|
|
Set `SEAWEED_ADMIN_PASSWORD`: `weed admin` serves the panel with no
|
|
authentication when it is empty, and a panel that can mint bucket credentials is
|
|
the bucket. In the prod file it is bound to loopback like `PB_BIND` and
|
|
`API_BIND`, so a remote host needs `SEAWEED_ADMIN_BIND=0.0.0.0` behind a reverse
|
|
proxy. That file publishes nothing for master, volume and filer — the volume
|
|
server serves file content by id with no authentication of any kind, and the
|
|
admin UI already shows what those ports would.
|
|
|
|
Switching between `docker-compose.seaweedfs.yml` and its `.split.` twin needs no
|
|
migration: master, volume and filer share one `/data` mount, which is exactly
|
|
the layout `weed server -dir=/data` writes.
|
|
|
|
### How the switch happens
|
|
|
|
On every boot the API Server reads `PB_S3_*` and writes PocketBase's *Files
|
|
storage* settings from them (only when they differ from what is already there),
|
|
then asks PocketBase to prove it can reach the bucket. It retries for about half
|
|
a minute while PocketBase is still starting, and never blocks the server from
|
|
coming up. Watch for it in the log:
|
|
|
|
```
|
|
[api] storage: ✓ file storage → S3 (pilotvault at http://seaweedfs:8333)
|
|
[api] storage: ✓ S3 storage reachable
|
|
```
|
|
|
|
A boot that finds the settings already correct logs
|
|
`• file storage already on S3` and writes nothing.
|
|
|
|
Two things to know before turning it on:
|
|
|
|
- **Existing files are not migrated.** PocketBase copies nothing when the setting
|
|
flips, so documents uploaded before the switch stop resolving. Copy
|
|
`pb_data/storage/<collectionId>/<recordId>/<file>` into the bucket root, keeping
|
|
that layout, *before* enabling it — or start from a stack with no documents.
|
|
- **Going back to the plain compose file is not an off switch.** It leaves
|
|
PocketBase pointed at the bucket, deliberately: files already written there are
|
|
reachable only while it is. Move them back and turn it off in PocketBase's own
|
|
admin UI. For the same reason a rotation of `PB_S3_SECRET` alone is invisible to
|
|
the API Server — PocketBase masks the stored secret on read — so change another
|
|
`PB_S3_*` value alongside it, or set it in the admin UI.
|
|
|
|
## Notes
|
|
|
|
- `docker-compose.yml` builds the API Server and Web App from `../API Server`
|
|
and `../Web App`, and PocketBase from the repo root, so run it from this
|
|
directory with the repo checked out.
|
|
- The Web App's Vue bundle uses same-origin `/bff` and `/api`, which the BFF
|
|
proxies — no CORS in play. `CORS_ALLOW_ORIGINS` therefore only matters if a
|
|
browser calls the API Server directly. Native apps are not subject to CORS.
|
|
- Nothing in this stack terminates TLS. Put your own reverse proxy in front of
|
|
the Web App port and set `CORS_ALLOW_ORIGINS` to its public origin.
|