PocketBase as a standalone database server

The pocketbase driver no longer embeds PocketBase: Warp keeps its data as
PocketBase collections on a server of its own and reaches it only through
the REST API, the way the postgres driver reaches PostgreSQL.
database.connection_string is the server's URL, and Warp signs in as the
superuser in WARP_PB_SUPERUSER_EMAIL / WARP_PB_SUPERUSER_PASSWORD (or a
WARP_PB_SUPERUSER_FILE of the two).

Every SQL table is a superuser-only collection of the same name and
columns, created by warp migrate. Reads go through PocketBase's SQL
endpoint with the SQL drivers' queries, via a read-only database/sql
driver that inlines arguments, moves long ones into warp_params and pages
past 1000 rows. Writes are record operations in batch requests under one
write lock in the Warp process. Media is a protected file field in
warp_media, local or in the S3 bucket Warp writes into PocketBase's
settings. Search matches word prefixes with LIKE. The storage tests run
against an in-process PocketBase and pass as on SQLite.

Docker: the PocketBase stacks get a pocketbase service running
tajniak81/pocketbase-docker-root (WARP_PB_IMAGE), with a pb-data volume
and its admin UI on loopback; the AIO images run that PocketBase binary
as a process beside the homeserver, making up a superuser when none is
set. The .env examples, READMEs, docs and warp.yaml.example follow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Docker/.env.pocketbase.example

@@ -21,11 +21,31 @@ WARP_PORT=8008
 WARP_ADMIN_PORT=8009
 WARP_WEB_PORT=8080
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=admin@example.org
+WARP_PB_SUPERUSER_PASSWORD=change-me-now
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 
 # ------------------------------------------------------------ homeserver
 

Docker/.env.pocketbase.prod.example

@@ -5,6 +5,9 @@
 #   cp .env.pocketbase.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.prod.yml up -d
 #
+# Required, with no default: WARP_PB_SUPERUSER_EMAIL and
+# WARP_PB_SUPERUSER_PASSWORD.
+#
 # Compose reads .env for the values it puts into the compose file, and hands
 # all of it to the containers, so a change takes effect on the next `up -d`.
 # An empty value means the built-in default, given in the comment above it;
@@ -26,11 +29,31 @@ WARP_WEB_PORT=8080
 WARP_REGISTRY=10.2.1.10:5500/admin
 WARP_VERSION=latest
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=
+WARP_PB_SUPERUSER_PASSWORD=
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 
 # ------------------------------------------------------------ homeserver
 

Docker/.env.pocketbase.s3.example

@@ -24,15 +24,35 @@ WARP_PORT=8008
 WARP_ADMIN_PORT=8009
 WARP_WEB_PORT=8080
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=admin@example.org
+WARP_PB_SUPERUSER_PASSWORD=change-me-now
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 
 # ------------------------------------------------------------- media (S3)
 
-# Media goes to this bucket; the database stays in /data/pb_data. The bucket
+# Media goes to this bucket; the database stays in PocketBase. The bucket
 # must already exist: nothing here runs a gateway or creates it. For a
 # gateway on the Docker host, use http://host.docker.internal:8333. Media
 # stored before S3 was on is not moved into the bucket.

Docker/.env.pocketbase.s3.prod.example

@@ -5,8 +5,9 @@
 #   cp .env.pocketbase.s3.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.s3.prod.yml up -d
 #
-# Required, with no default: WARP_PB_S3_ENDPOINT, WARP_PB_S3_ACCESS_KEY
-# and WARP_PB_S3_SECRET.
+# Required, with no default: WARP_PB_SUPERUSER_EMAIL,
+# WARP_PB_SUPERUSER_PASSWORD, WARP_PB_S3_ENDPOINT, WARP_PB_S3_ACCESS_KEY and
+# WARP_PB_S3_SECRET.
 #
 # Compose reads .env for the values it puts into the compose file, and hands
 # all of it to the containers, so a change takes effect on the next `up -d`.
@@ -29,15 +30,35 @@ WARP_WEB_PORT=8080
 WARP_REGISTRY=10.2.1.10:5500/admin
 WARP_VERSION=latest
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=
+WARP_PB_SUPERUSER_PASSWORD=
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 
 # ------------------------------------------------------------- media (S3)
 
-# Media goes to this bucket; the database stays in /data/pb_data. The bucket
+# Media goes to this bucket; the database stays in PocketBase. The bucket
 # must already exist: nothing here runs a gateway or creates it. For a
 # gateway on the Docker host, use http://host.docker.internal:8333. Media
 # stored before S3 was on is not moved into the bucket.

Docker/.env.pocketbase.seaweedfs.example

@@ -23,18 +23,38 @@ WARP_PORT=8008
 WARP_ADMIN_PORT=8009
 WARP_WEB_PORT=8080
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=admin@example.org
+WARP_PB_SUPERUSER_PASSWORD=change-me-now
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 # SeaweedFS's data (seaweed-data).
 SEAWEED_DATA_VOLUME=
 
 # -------------------------------------------------------------- seaweedfs
 
 # Media goes to this bucket in SeaweedFS, created on start; the database
-# stays in /data/pb_data. The key pair is the homeserver's S3 identity:
+# stays in PocketBase. The key pair is the homeserver's S3 identity:
 # the gateway's only one, and what the homeserver signs with.
 # Media stored before S3 was on is not moved into the bucket.
 WARP_PB_S3_BUCKET=warp

Docker/.env.pocketbase.seaweedfs.prod.example

@@ -5,7 +5,8 @@
 #   cp .env.pocketbase.seaweedfs.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.seaweedfs.prod.yml up -d
 #
-# Required, with no default: WARP_PB_S3_ACCESS_KEY and WARP_PB_S3_SECRET.
+# Required, with no default: WARP_PB_SUPERUSER_EMAIL,
+# WARP_PB_SUPERUSER_PASSWORD, WARP_PB_S3_ACCESS_KEY and WARP_PB_S3_SECRET.
 #
 # Compose reads .env for the values it puts into the compose file, and hands
 # all of it to the containers, so a change takes effect on the next `up -d`.
@@ -28,18 +29,38 @@ WARP_WEB_PORT=8080
 WARP_REGISTRY=10.2.1.10:5500/admin
 WARP_VERSION=latest
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=
+WARP_PB_SUPERUSER_PASSWORD=
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 # SeaweedFS's data (seaweed-data).
 SEAWEED_DATA_VOLUME=
 
 # -------------------------------------------------------------- seaweedfs
 
 # Media goes to this bucket in SeaweedFS, created on start; the database
-# stays in /data/pb_data. The key pair is the homeserver's S3 identity:
+# stays in PocketBase. The key pair is the homeserver's S3 identity:
 # the gateway's only one, and what the homeserver signs with.
 # Media stored before S3 was on is not moved into the bucket.
 WARP_PB_S3_BUCKET=warp

Docker/.env.pocketbase.seaweedfs.split.example

@@ -24,11 +24,31 @@ WARP_PORT=8008
 WARP_ADMIN_PORT=8009
 WARP_WEB_PORT=8080
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=admin@example.org
+WARP_PB_SUPERUSER_PASSWORD=change-me-now
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 # SeaweedFS's data (seaweed-data).
 SEAWEED_DATA_VOLUME=
 # SeaweedFS's admin UI state (seaweed-admin).
@@ -37,7 +57,7 @@ SEAWEED_ADMIN_VOLUME=
 # -------------------------------------------------------------- seaweedfs
 
 # Media goes to this bucket in SeaweedFS, created on start; the database
-# stays in /data/pb_data. The key pair is the homeserver's S3 identity:
+# stays in PocketBase. The key pair is the homeserver's S3 identity:
 # written into the filer's IAM store on every start, beside any identity
 # added in the admin UI, so a new secret here lands on the next start.
 # Media stored before S3 was on is not moved into the bucket.

Docker/.env.pocketbase.seaweedfs.split.prod.example

@@ -5,7 +5,8 @@
 #   cp .env.pocketbase.seaweedfs.split.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.seaweedfs.split.prod.yml up -d
 #
-# Required, with no default: WARP_PB_S3_ACCESS_KEY, WARP_PB_S3_SECRET and
+# Required, with no default: WARP_PB_SUPERUSER_EMAIL,
+# WARP_PB_SUPERUSER_PASSWORD, WARP_PB_S3_ACCESS_KEY, WARP_PB_S3_SECRET and
 # SEAWEED_ADMIN_PASSWORD.
 #
 # Compose reads .env for the values it puts into the compose file, and hands
@@ -29,11 +30,31 @@ WARP_WEB_PORT=8080
 WARP_REGISTRY=10.2.1.10:5500/admin
 WARP_VERSION=latest
 
+# The PocketBase image; any PocketBase 0.40 or later answers the same.
+WARP_PB_IMAGE=tajniak81/pocketbase-docker-root:latest
+
+# PocketBase's port, for its admin UI at http://localhost:8070/_/. It is
+# on loopback unless the bind address says otherwise; put the UI behind a
+# reverse proxy before binding it to 0.0.0.0.
+WARP_PB_BIND=127.0.0.1
+WARP_PB_PORT=8070
+
+# The PocketBase superuser the homeserver signs in as, and so can you, in
+# the admin UI. The pocketbase container creates it on its first start and
+# leaves it alone after that: to change the password, change it in the
+# admin UI first, then here. It needs 8 characters or more.
+WARP_PB_SUPERUSER_EMAIL=
+WARP_PB_SUPERUSER_PASSWORD=
+
 # Where the data lives. Empty keeps the named volume in brackets; a
 # host path (starting with . or /) bind-mounts that directory instead.
-# The homeserver runs as UID 10001, so its directory must be writable by it.
-# The homeserver's /data (warp-data).
+# The homeserver runs as UID 10001, so its directory must be writable by
+# it; PocketBase runs as root.
+# The homeserver's /data (warp-data): its signing key.
 WARP_DATA_VOLUME=
+# PocketBase's pb_data (pb-data): the database, and media unless it is
+# in S3.
+WARP_PB_DATA_VOLUME=
 # SeaweedFS's data (seaweed-data).
 SEAWEED_DATA_VOLUME=
 # SeaweedFS's admin UI state (seaweed-admin).
@@ -42,7 +63,7 @@ SEAWEED_ADMIN_VOLUME=
 # -------------------------------------------------------------- seaweedfs
 
 # Media goes to this bucket in SeaweedFS, created on start; the database
-# stays in /data/pb_data. The key pair is the homeserver's S3 identity:
+# stays in PocketBase. The key pair is the homeserver's S3 identity:
 # written into the filer's IAM store on every start, beside any identity
 # added in the admin UI, so a new secret here lands on the next start.
 # Media stored before S3 was on is not moved into the bucket.

Docker/README.md

@@ -7,7 +7,7 @@ The homeserver (`warp`), the admin panel (`warp-admin`) and the web client
 | File | Database | Images |
 | --- | --- | --- |
 | `docker-compose.sqlite.yml` | SQLite, in the `warp-data` volume | built here |
-| `docker-compose.pocketbase.yml` | PocketBase, embedded in the homeserver, in `warp-data` | built here |
+| `docker-compose.pocketbase.yml` | PocketBase, a container of its own, in `pb-data` | built here |
 | `docker-compose.postgresql.yml` | PostgreSQL 17, its own container | built here |
 | `docker-compose.pocketbase.s3.yml` | PocketBase, media in an existing S3 bucket elsewhere | built here |
 | `docker-compose.pocketbase.seaweedfs.yml` | PocketBase, media in SeaweedFS, one container | built here |
@@ -26,16 +26,22 @@ Homeserver on `:8008`, admin panel on `:8009`, web client on `:8080`
 TLS-terminating reverse proxy in front before exposing them; see
 [docs/deployment.md](../docs/deployment.md).
 
-PocketBase is a database driver inside the homeserver, not a separate
-server, so the PocketBase files have no PocketBase container.
+The PocketBase files run PocketBase as a container of its own, from
+`tajniak81/pocketbase-docker-root` (`WARP_PB_IMAGE` picks another; any
+PocketBase 0.40 or later will do). Its data is in the `pb-data` volume, and
+the homeserver reaches it at `http://pocketbase:8070`, signed in as the
+superuser in `.env`. The image creates that superuser on its first start
+and leaves it alone after, so a new password is set in the admin UI first,
+at `http://localhost:8070/_/` on loopback, and in `.env` after.
 
 ## Media in S3
 
 The three `pocketbase.s3` and `pocketbase.seaweedfs` setups keep the
-PocketBase database in `/data/pb_data` and put media in an S3 bucket
+PocketBase database in `pb-data` and put media in an S3 bucket
 (`WARP_PB_S3_BUCKET`, default `warp`). Media already stored on the
 filesystem is not moved into the bucket when S3 is turned on, so start
-these on a fresh `warp-data` or copy the files across first.
+these on a fresh `pb-data` or copy the files across first. It is the
+PocketBase container that talks to the bucket.
 
 - **`docker-compose.pocketbase.s3.yml`**: a bucket that already exists
   elsewhere (AWS, MinIO, a SeaweedFS on another host). Set

Docker/docker-compose.pocketbase.prod.yml

@@ -5,10 +5,11 @@
 #   cp .env.pocketbase.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.prod.yml up -d
 #
-# PocketBase is embedded in the homeserver (the pocketbase database driver),
-# so it is not a container of its own: its data directory, with media in
-# its storage, is /data/pb_data in the warp-data volume. Set WARP_PB_S3_*
-# in .env to keep media in an S3 bucket instead (docs/configuration.md).
+# PocketBase is the homeserver's database, in a container of its own: Warp's
+# collections, and media in PocketBase's storage, are in the pb-data volume,
+# and the homeserver reaches it at http://pocketbase:8070 as the superuser
+# set in .env. Set WARP_PB_S3_* in .env to keep media in an S3 bucket
+# instead (docs/configuration.md).
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080.
@@ -26,10 +27,38 @@
 name: warp-pocketbase
 
 services:
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    pull_policy: always
+    restart: unless-stopped
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     image: ${WARP_REGISTRY:-10.2.1.10:5500/admin}/warp:${WARP_VERSION:-latest}
     pull_policy: always
     restart: unless-stopped
+    depends_on:
+      pocketbase:
+        condition: service_healthy
     # The signing key is created on first start and kept in the volume:
     # losing it means other servers no longer recognise this one.
     entrypoint: ["/bin/sh", "-c"]
@@ -38,7 +67,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
     volumes:
       - ${WARP_DATA_VOLUME:-warp-data}:/data
     ports:
@@ -69,4 +98,7 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:

Docker/docker-compose.pocketbase.s3.prod.yml

@@ -6,7 +6,7 @@
 #   cp .env.pocketbase.s3.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.s3.prod.yml up -d
 #
-# The database stays in /data/pb_data (warp-data); media goes to the bucket
+# The database is PocketBase's, in pb-data; media goes to the bucket
 # WARP_PB_S3_BUCKET (default warp) on WARP_PB_S3_ENDPOINT, which must already
 # exist: nothing here runs a gateway or creates the bucket. For a gateway on
 # this Docker host, use http://host.docker.internal:8333; the host entry below
@@ -31,10 +31,42 @@
 name: warp-pocketbase-s3
 
 services:
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    pull_policy: always
+    restart: unless-stopped
+    extra_hosts:
+      # Lets WARP_PB_S3_ENDPOINT name the Docker host as host.docker.internal:
+      # PocketBase is what talks to the bucket.
+      - "host.docker.internal:host-gateway"
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     image: ${WARP_REGISTRY:-10.2.1.10:5500/admin}/warp:${WARP_VERSION:-latest}
     pull_policy: always
     restart: unless-stopped
+    depends_on:
+      pocketbase:
+        condition: service_healthy
     extra_hosts:
       # Lets WARP_PB_S3_ENDPOINT name the Docker host as host.docker.internal.
       - "host.docker.internal:host-gateway"
@@ -53,7 +85,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
       WARP_PB_S3_ENABLED: "true"
       WARP_PB_S3_ENDPOINT: ${WARP_PB_S3_ENDPOINT:?set WARP_PB_S3_ENDPOINT in .env}
       WARP_PB_S3_BUCKET: ${WARP_PB_S3_BUCKET:-warp}
@@ -93,4 +125,7 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:

Docker/docker-compose.pocketbase.s3.yml

@@ -6,7 +6,7 @@
 #   cp .env.pocketbase.s3.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.s3.yml up -d --build
 #
-# The database stays in /data/pb_data (warp-data); media goes to the bucket
+# The database is PocketBase's, in pb-data; media goes to the bucket
 # WARP_PB_S3_BUCKET (default warp) on WARP_PB_S3_ENDPOINT, which must already
 # exist: nothing here runs a gateway or creates the bucket. For a gateway on
 # this Docker host, use http://host.docker.internal:8333; the host entry below
@@ -24,12 +24,43 @@
 name: warp-pocketbase-s3
 
 services:
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    restart: unless-stopped
+    extra_hosts:
+      # Lets WARP_PB_S3_ENDPOINT name the Docker host as host.docker.internal:
+      # PocketBase is what talks to the bucket.
+      - "host.docker.internal:host-gateway"
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     build:
       context: ..
       dockerfile: Dockerfile
     image: warp:latest
     restart: unless-stopped
+    depends_on:
+      pocketbase:
+        condition: service_healthy
     extra_hosts:
       # Lets WARP_PB_S3_ENDPOINT name the Docker host as host.docker.internal.
       - "host.docker.internal:host-gateway"
@@ -48,7 +79,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
       WARP_PB_S3_ENABLED: "true"
       WARP_PB_S3_ENDPOINT: ${WARP_PB_S3_ENDPOINT:?set WARP_PB_S3_ENDPOINT in .env}
       WARP_PB_S3_BUCKET: ${WARP_PB_S3_BUCKET:-warp}
@@ -92,4 +123,7 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:

Docker/docker-compose.pocketbase.seaweedfs.prod.yml

@@ -7,7 +7,7 @@
 #   cp .env.pocketbase.seaweedfs.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.seaweedfs.prod.yml up -d
 #
-# The database stays in /data/pb_data (warp-data); media goes to the bucket
+# The database is PocketBase's, in pb-data; media goes to the bucket
 # WARP_PB_S3_BUCKET (default warp) in SeaweedFS (seaweed-data), whose gateway
 # has exactly one identity: the homeserver's. For SeaweedFS's admin UI and
 # per-role containers, see docker-compose.pocketbase.seaweedfs.split.yml.
@@ -72,11 +72,38 @@ services:
     command:
       - echo "s3.bucket.create -name $$WARP_PB_S3_BUCKET" | weed shell -master=seaweedfs:9333 >/dev/null
 
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    pull_policy: always
+    restart: unless-stopped
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     image: ${WARP_REGISTRY:-10.2.1.10:5500/admin}/warp:${WARP_VERSION:-latest}
     pull_policy: always
     restart: unless-stopped
     depends_on:
+      pocketbase:
+        condition: service_healthy
       seaweedfs:
         condition: service_healthy
       seaweedfs-init:
@@ -89,7 +116,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
       # The gateway on the compose network; these override whatever .env
       # says about S3.
       WARP_PB_S3_ENABLED: "true"
@@ -129,5 +156,8 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:
   seaweed-data:

Docker/docker-compose.pocketbase.seaweedfs.split.prod.yml

@@ -7,7 +7,7 @@
 #   cp .env.pocketbase.seaweedfs.split.prod.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.seaweedfs.split.prod.yml up -d
 #
-# The database stays in /data/pb_data (warp-data); media goes to the bucket
+# The database is PocketBase's, in pb-data; media goes to the bucket
 # WARP_PB_S3_BUCKET (default warp) in SeaweedFS (seaweed-data). Over
 # docker-compose.pocketbase.seaweedfs.yml this buys SeaweedFS's admin UI,
 # where S3 identities are created and revoked under Object Store → Users,
@@ -177,11 +177,38 @@ services:
       retries: 12
       start_period: 15s
 
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    pull_policy: always
+    restart: unless-stopped
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     image: ${WARP_REGISTRY:-10.2.1.10:5500/admin}/warp:${WARP_VERSION:-latest}
     pull_policy: always
     restart: unless-stopped
     depends_on:
+      pocketbase:
+        condition: service_healthy
       seaweedfs-s3:
         condition: service_healthy
     # The signing key is created on first start and kept in the volume:
@@ -192,7 +219,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
       # The gateway on the compose network; these override whatever .env
       # says about S3.
       WARP_PB_S3_ENABLED: "true"
@@ -232,7 +259,10 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:
   # Master, volume and filer share it, as `weed server -dir` lays it out.
   seaweed-data:
   # The admin UI's session key and maintenance state; no object data.

Docker/docker-compose.pocketbase.seaweedfs.split.yml

@@ -7,7 +7,7 @@
 #   cp .env.pocketbase.seaweedfs.split.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.seaweedfs.split.yml up -d --build
 #
-# The database stays in /data/pb_data (warp-data); media goes to the bucket
+# The database is PocketBase's, in pb-data; media goes to the bucket
 # WARP_PB_S3_BUCKET (default warp) in SeaweedFS (seaweed-data). Over
 # docker-compose.pocketbase.seaweedfs.yml this buys SeaweedFS's admin UI,
 # where S3 identities are created and revoked under Object Store → Users,
@@ -170,6 +170,30 @@ services:
       retries: 12
       start_period: 15s
 
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    restart: unless-stopped
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     build:
       context: ..
@@ -177,6 +201,8 @@ services:
     image: warp:latest
     restart: unless-stopped
     depends_on:
+      pocketbase:
+        condition: service_healthy
       seaweedfs-s3:
         condition: service_healthy
     # The signing key is created on first start and kept in the volume:
@@ -187,7 +213,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
       # The gateway on the compose network; these override whatever .env
       # says about S3.
       WARP_PB_S3_ENABLED: "true"
@@ -231,7 +257,10 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:
   # Master, volume and filer share it, as `weed server -dir` lays it out.
   seaweed-data:
   # The admin UI's session key and maintenance state; no object data.

Docker/docker-compose.pocketbase.seaweedfs.yml

@@ -7,7 +7,7 @@
 #   cp .env.pocketbase.seaweedfs.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.seaweedfs.yml up -d --build
 #
-# The database stays in /data/pb_data (warp-data); media goes to the bucket
+# The database is PocketBase's, in pb-data; media goes to the bucket
 # WARP_PB_S3_BUCKET (default warp) in SeaweedFS (seaweed-data), whose gateway
 # has exactly one identity: the homeserver's. For SeaweedFS's admin UI and
 # per-role containers, see docker-compose.pocketbase.seaweedfs.split.yml.
@@ -65,6 +65,30 @@ services:
     command:
       - echo "s3.bucket.create -name $$WARP_PB_S3_BUCKET" | weed shell -master=seaweedfs:9333 >/dev/null
 
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    restart: unless-stopped
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     build:
       context: ..
@@ -72,6 +96,8 @@ services:
     image: warp:latest
     restart: unless-stopped
     depends_on:
+      pocketbase:
+        condition: service_healthy
       seaweedfs:
         condition: service_healthy
       seaweedfs-init:
@@ -84,7 +110,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
       # The gateway on the compose network; these override whatever .env
       # says about S3.
       WARP_PB_S3_ENABLED: "true"
@@ -128,5 +154,8 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data:
   seaweed-data:

Docker/docker-compose.pocketbase.yml

@@ -5,10 +5,11 @@
 #   cp .env.pocketbase.example .env      # then edit it
 #   docker compose -f docker-compose.pocketbase.yml up -d --build
 #
-# PocketBase is embedded in the homeserver (the pocketbase database driver),
-# so it is not a container of its own: its data directory, with media in
-# its storage, is /data/pb_data in the warp-data volume. Set WARP_PB_S3_*
-# in .env to keep media in an S3 bucket instead (docs/configuration.md).
+# PocketBase is the homeserver's database, in a container of its own: Warp's
+# collections, and media in PocketBase's storage, are in the pb-data volume,
+# and the homeserver reaches it at http://pocketbase:8070 as the superuser
+# set in .env. Set WARP_PB_S3_* in .env to keep media in an S3 bucket
+# instead (docs/configuration.md).
 #
 # Homeserver http://localhost:8008, admin panel http://localhost:8009, web
 # client http://localhost:8080.
@@ -20,12 +21,39 @@
 name: warp-pocketbase
 
 services:
+  # PocketBase, the homeserver's database: Warp's collections, and media in
+  # PocketBase's storage, are in the pb-data volume. The image creates the
+  # superuser from .env on its first start, and never changes it after: a
+  # new password goes in through the admin UI, then into .env. The admin UI
+  # is http://localhost:8070/_/ on loopback; WARP_PB_BIND=0.0.0.0 exposes
+  # it, behind a reverse proxy only.
+  pocketbase:
+    image: ${WARP_PB_IMAGE:-tajniak81/pocketbase-docker-root:latest}
+    restart: unless-stopped
+    environment:
+      PB_PORT: "8070"
+      PB_ADMIN_EMAIL: ${WARP_PB_SUPERUSER_EMAIL:?set WARP_PB_SUPERUSER_EMAIL in .env}
+      PB_ADMIN_PASSWORD: ${WARP_PB_SUPERUSER_PASSWORD:?set WARP_PB_SUPERUSER_PASSWORD in .env}
+    volumes:
+      - ${WARP_PB_DATA_VOLUME:-pb-data}:/pb/pb_data
+    ports:
+      - "${WARP_PB_BIND:-127.0.0.1}:${WARP_PB_PORT:-8070}:8070"
+    healthcheck:
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8070/api/health >/dev/null || exit 1"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+      start_period: 10s
+
   warp:
     build:
       context: ..
       dockerfile: Dockerfile
     image: warp:latest
     restart: unless-stopped
+    depends_on:
+      pocketbase:
+        condition: service_healthy
     # The signing key is created on first start and kept in the volume:
     # losing it means other servers no longer recognise this one.
     entrypoint: ["/bin/sh", "-c"]
@@ -34,7 +62,7 @@ services:
     env_file: .env
     environment:
       WARP_DB_DRIVER: pocketbase
-      WARP_DB_CONNECTION_STRING: /data/pb_data
+      WARP_DB_CONNECTION_STRING: http://pocketbase:8070
     volumes:
       - ${WARP_DATA_VOLUME:-warp-data}:/data
     ports:
@@ -69,4 +97,7 @@ services:
       - "${WARP_WEB_PORT:-8080}:8080"
 
 volumes:
+  # The homeserver's signing key.
   warp-data:
+  # PocketBase's pb_data: the database, and media unless it is in S3.
+  pb-data: