PocketBase

​

Overview

​

Architecture

• PocketBase — A single-replica stateful workload running one container that serves the REST API, the realtime stream, and the /_/ dashboard on port 8090. The superuser account is created from your credentials secret before the server ever binds the port, so there is no unclaimed-admin window.
• SQLite on a persistent volume — The database, uploaded files, and any locally-stored backup archives all live at /pb_data on the workload’s volume set. There is no external database dependency; PocketBase talks to nothing but its own disk.

​

What Gets Created

• Stateful PocketBase Workload — One replica ({release}-pocketbase) serving the API, realtime, and dashboard on port 8090.
• Volume Set — A 10 GiB persistent volume ({release}-pocketbase-data) mounted at /pb_data, holding the SQLite database, uploaded files, and local backup archives. Scheduled snapshots protect the data, and a final snapshot is taken on uninstall.
• Identity & Policy — An identity bound to the workload, with a policy granting reveal on exactly one secret: the credentials secret you create. Nothing else.

​

Prerequisites

cpln secret create-dictionary --name my-pocketbase-credentials \
  --entry email=admin@example.com \
  --entry password='choose-a-strong-password' \
  --entry encryptionKey="$(openssl rand -hex 16)"

The secret my-pocketbase-credentials no longer exists. Workload updates
are paused until the secret is added or the reference to the secret
removed.

​

First Steps After Install

​

Configuration

image: ghcr.io/muchobien/pocketbase:0.40.1 # must run as root with `pocketbase` on PATH

resources:
  maxCpu: 500m
  maxMemory: 1Gi
  minCpu: 125m # ratio to maxCpu may not exceed 4:1 on a stateful workload
  minMemory: 256Mi

volumeset:
  capacity: 10 # GiB (minimum 10) — SQLite database, uploaded files, and any local backups

# ─── Credentials (REQUIRED — create this secret BEFORE installing) ────────────
# A dictionary secret with exactly three keys:
#   email          superuser login for the dashboard at /_/
#   password       superuser password, at least 8 characters (re-applied on EVERY
#                  start — the secret is authoritative; changing it in the
#                  dashboard is reverted)
#   encryptionKey  EXACTLY 32 characters (openssl rand -hex 16) — encrypts SMTP,
#                  OAuth2 and S3 settings at rest. NEVER change it after install.
# Installing without this secret wedges the deployment silently: no logs at all.
# The missing name appears only in `cpln workload get-deployments` under
# status.versions[].message. See the README.
credentials:
  secretName: my-pocketbase-credentials

# ─── Backup ───────────────────────────────────────────────────────────────────
# Scheduled, crash-consistent snapshots of the data volume, managed by the
# platform (no cloud account or bucket required). SQLite recovers cleanly from a
# snapshot via its WAL. A final snapshot is always taken on uninstall.
backup:
  enabled: true # periodic snapshots of the data volume
  schedule: "0 3 * * *" # cron in UTC — default daily at 03:00 (hourly is the most frequent the platform allows)
  retention: 7d # how long each snapshot is kept (e.g. 7d, 720h, 30d)

# ─── API ──────────────────────────────────────────────────────────────────────
cors:
  allowedOrigins: # browser origins allowed to call the API; ["*"] allows any
    - "*"

# ─── Access ───────────────────────────────────────────────────────────────────
publicAccess:
  # Safe to leave on: the superuser is created from the secret above BEFORE the
  # server starts listening, so there is no unclaimed-admin window, and new
  # collections are superuser-only until you write an API rule.
  enabled: true # REST API, realtime and the /_/ dashboard on the canonical *.cpln.app HTTPS endpoint

internalAccess: # internal firewall scope (in-GVC callers of the API)
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

​

PocketBase Instance

• image — The PocketBase container image. See Image for why this is a community build and what an override must satisfy.
• resources — CPU and memory bounds for the container. The block exposes both a reservation and a limit, so the limit is named maxCpu / maxMemory; the bare cpu and memory keys are rejected at render with a message telling you to rename them. On a stateful workload the platform caps the maxCpu to minCpu ratio at 4:1, which the defaults sit exactly on.
• volumeset.capacity — Volume size in GiB (minimum 10) for /pb_data. Capacity is fixed when the volume set is created, so size it at install time.

​

Credentials

• credentials.secretName — Name of your pre-created dictionary secret holding email, password, and encryptionKey (see Prerequisites). It must exist before you install, and it is the only secret the workload’s identity can reveal.

​

Backup

• backup.enabled — Take periodic snapshots of the data volume (default true). Setting it to false removes the schedule; the final snapshot on uninstall is taken either way.
• backup.schedule — Cron expression in UTC (default 0 3 * * *, daily at 03:00). The platform does not accept schedules more frequent than hourly.
• backup.retention — How long each snapshot is kept, e.g. 7d, 720h, 30d.

​

API

• cors.allowedOrigins — Browser origins allowed to call the API, passed to PocketBase as its --origins flag. The default ["*"] allows any origin. With a restricted list, a request from an origin that is not on it still returns 200 but comes back without an access-control-allow-origin header — which is correct CORS behavior, since the browser is what blocks the response.

​

Access

• publicAccess.enabled — Serve the REST API, realtime, and the /_/ dashboard on the canonical *.cpln.app HTTPS endpoint (default true). This is safe to leave on: the superuser is created from your secret before the server starts listening, so no unclaimed admin account is ever exposed, and new collections are superuser-only until you write an API rule. Set it to false for an internal-only instance — external requests are then refused at the edge with a 403.
• internalAccess.type — Controls which workloads can reach PocketBase over the internal network:

cpln port-forward {release}-pocketbase 8090:8090 --gvc {gvc}

​

Image

​

Connecting

​

Realtime Subscriptions

• No events are lost while the stream is open — 10 of 10 record events were delivered, each carrying the mutation that triggered it.
• The cut is a clean end-of-stream, not an error or a reset. The connection simply ends.
• The cause is the platform timeout, proven causally. Lowering timeoutSeconds to 60 cut an otherwise identical stream at exactly 60 seconds.

​

Rotating Credentials

cpln workload force-redeployment {release}-pocketbase --gvc {gvc}

​

Restarts and Availability

​

Backing Up

• Default schedule — Daily at 03:00 UTC (backup.schedule: "0 3 * * *"), kept for 7 days (backup.retention: 7d).
• Minimum interval — The platform does not accept schedules more frequent than hourly.
• Coverage — Everything under /pb_data: the SQLite database, uploaded files, and any backup archives PocketBase itself wrote locally.

cpln volumeset snapshot get {release}-pocketbase-data --gvc {gvc} -o yaml

​

Restoring a Backup

cpln volumeset snapshot get {release}-pocketbase-data --gvc {gvc} -o yaml

cpln volumeset snapshot restore {release}-pocketbase-data \
  --snapshot-name <snapshot-name> \
  --location <location> \
  --volume-index 0 \
  --gvc {gvc}

​

Important Notes

• Create the credentials secret before installing. credentials.secretName must name an existing dictionary secret holding email, password, and encryptionKey. Without it the deployment wedges silently: cpln logs returns zero lines and the only diagnostic is status.versions[].message from cpln workload get-deployments. Recovery after creating the secret took 10 minutes 11 seconds unaided, or force a redeployment to skip the wait.
• Never change encryptionKey after install. It encrypts the SMTP password, OAuth2 client secrets, and S3 backup credentials stored inside the database. Changing it orphans all of them with no way back. Keep a copy outside Control Plane.
• The superuser password is re-applied from the secret on every start. Changing it in the dashboard is reverted at the next restart — change it in the secret instead, and note that doing so changes your login.
• Rotating the secret needs a forced redeployment. The workload does not pick up a changed secret on its own: eleven minutes after a rotation the old password still worked and the workload reported ready: true throughout. See Rotating Credentials.
• Realtime subscriptions are cut at ten minutes. timeoutSeconds is already at the platform maximum of 600, so this is a hard ceiling. No events are lost and the cut is a clean end-of-stream; the official SDKs reconnect automatically, but a hand-rolled client must handle it. See Realtime Subscriptions.
• Single instance, no HA — and that is upstream’s design. PocketBase does not cluster, so there is no replicas knob and every restart is an outage of about 85 seconds. Data is not at risk; the same volume reattaches. See Restarts and Availability.
• Set the Application URL at first login. Verification and password-reset emails build their links from Settings → Application → Application URL, which is a database setting the chart cannot write. Until you set it, those links point at the wrong host.
• Uploads and local backup archives share the volume with the database. A file-heavy app needs more than the 10 GiB default; raise volumeset.capacity at install time, since capacity is fixed when the volume set is created.
• Backups are platform volume snapshots, not off-site copies. They live in the platform storage layer next to the volume. For an off-platform copy, configure PocketBase’s own S3 backups in the dashboard.
• Access-knob changes take time to propagate. Flipping publicAccess.enabled took 126 seconds to be enforced. Re-poll rather than trusting the first response.
• This is not an official image. No official PocketBase image exists, so the template pins a community build and overrides its entrypoint. The PB_ADMIN_EMAIL and PB_ADMIN_PASSWORD variables from that image’s documentation do nothing here — PocketBase core reads no environment variables. An image override must run as root with pocketbase on PATH.
• Data survives restarts and upgrades; uninstalling deletes it. The volume set goes with the release, though a final snapshot is taken on uninstall. Your credentials secret is yours and survives an uninstall.

​

External References