tajniak81/pocketbase-docker-root repository overview

⁠PocketBase Docker

Minimal, production-minded Docker images for PocketBase⁠, shipped in two flavors:

• Root — runs as root, for environments where that's simpler or required.

Use a multi-stage Alpine build that downloads a pinned PocketBase release, verifies its SHA-256 checksum against the published checksums.txt, and ships only the binary in the runtime image. An entrypoint script optionally bootstraps the superuser and enables settings encryption on every start.

⁠Features

• 🪶 Small Alpine-based image, multi-stage build (only the pocketbase binary in the final layer).
• 🔒 Checksum verification of the downloaded release during build.
• 👤 Kept isolated via distinct Compose project names.
• 🌱 Idempotent superuser bootstrap — creates the admin only if it doesn't already exist.
• 🔑 Optional settings encryption via a 32-character key.
• 🏗️ Multi-arch (amd64 / arm64) via buildx TARGETARCH.
• ❤️ Built-in HEALTHCHECK hitting /api/health.
• 💾 Persistent pb_data volume for the SQLite database and uploads.

⁠Configuration

⁠Superuser bootstrap

On every start the entrypoint checks whether PB_ADMIN_EMAIL already exists in the database:

• exists → nothing happens (PB_ADMIN_PASSWORD is ignored).
• missing → the superuser is created using PB_ADMIN_PASSWORD (required in that case, otherwise the container exits with an error).
• PB_ADMIN_EMAIL blank → bootstrap is skipped entirely.

⁠Settings encryption

To encrypt application settings stored in the database, set a 32-character PB_ENCRYPTION_KEY. Generate one with:

openssl rand -hex 16

The entrypoint validates the length and passes --encryptionEnv=PB_ENCRYPTION_KEY to PocketBase. See the PocketBase production docs⁠.

⁠Data persistence

The SQLite database and uploaded files live in /pb/pb_data, backed by the named Docker volume pb_data. Data survives container recreation. To develop migrations/hooks against the running instance, uncomment the bind mounts in the Compose file:

# - ./pb_migrations:/pb/pb_migrations
# - ./pb_hooks:/pb/pb_hooks

You can also bake pb_migrations / pb_hooks into the image by uncommenting the corresponding COPY lines in the Dockerfile.

⁠Health check

Both images define a HEALTHCHECK that polls http://127.0.0.1:${PB_PORT}/api/health. Check status with:

docker ps
docker inspect --format '{{.State.Health.Status}}' pocketbase

⁠License

PocketBase is distributed under its own license⁠. This repository contains only the Docker packaging.