Ein Backend für eine kleine App oder einen Prototyp bringt meist Datenbankserver, Auth-Dienst und viel Konfiguration mit. PocketBase liefert stattdessen ein einziges Go-Binary, das SQLite-Datenbank, REST-API mit automatischer Dokumentation, Authentifizierung (E-Mail/Passwort, OAuth2, Einmalcodes per E-Mail), Datei-Storage, Echtzeit-Subscriptions per Server-Sent Events und eine vollständige Admin-UI in sich vereint. Externe Dienste sind nicht nötig. Die Anleitung zeigt, wie Sie PocketBase mit Docker Compose auf einem Linux-Host (Ubuntu, Debian oder NAS mit Docker) betreiben und typische Fehler vermeiden.

Voraussetzungen

Docker Engine >= 20.10 und das Docker Compose Plugin >= 2.x auf einem Linux-Host, einer VM oder einem NAS, x86_64, ARM64 oder ARMv7. Die Einrichtung beschreibt Docker und Docker Compose auf Linux installieren.
1 CPU-Kern und 512 MB RAM genügen für kleine Projekte. Dazu 100 MB Speicherplatz für das Image plus Platz für Datenbank und Uploads.
Netzwerkzugang zur GitHub Container Registry (ghcr.io) für den ersten Image-Download.
Für den Produktivbetrieb: ein Reverse Proxy (Caddy, Nginx oder Traefik) für HTTPS, siehe Caddy als Reverse Proxy mit automatischem HTTPS.
curl und openssl für Prüfschritte und Schlüssel.

Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Legen Sie einen eigenen Ordner für das Projekt an. Dort liegen compose.yaml und .env.

sudo mkdir -p /opt/pocketbase
sudo chown "$USER": /opt/pocketbase
cd /opt/pocketbase

Verifizieren: ls -la /opt/pocketbase zeigt ein leeres Verzeichnis, das Ihrem Benutzer gehört.

Schritt 2: Umgebungsvariablen in der .env-Datei hinterlegen

Secrets und konfigurierbare Werte gehören nicht direkt in die compose.yaml, sondern in eine .env-Datei. Docker Compose liest sie automatisch ein. Erstellen Sie die Datei mit einem Editor:

# /opt/pocketbase/.env

# Superuser (legt das Image bei jedem Start per "superuser upsert" an bzw. aktualisiert ihn)
PB_ADMIN_EMAIL=admin@example.com
PB_ADMIN_PASSWORD=IHR_ADMIN_PASSWORT

# 32 Zeichen für die Verschlüsselung der Einstellungen (openssl rand -hex 16)
ENCRYPTION=IHR_SCHLUESSEL_32_ZEICHEN

Ersetzen Sie die Platzhalter durch eigene Werte; den Schlüssel erzeugen Sie mit openssl rand -hex 16. Die Variable ENCRYPTION allein bewirkt nichts: PocketBase verschlüsselt die Einstellungen erst, wenn es mit --encryptionEnv ENCRYPTION startet (Schritt 3). Setzen Sie Variable und Schalter von Anfang an.

Schränken Sie die Dateirechte ein:

chmod 600 /opt/pocketbase/.env

Verifizieren: ls -l /opt/pocketbase/.env zeigt -rw-------, und grep -c "=IHR_" /opt/pocketbase/.env gibt 0 aus.

Schritt 3: compose.yaml erstellen

Die Anleitung nutzt das Community-Image ghcr.io/muchobien/pocketbase, weil das PocketBase-Projekt kein eigenes Docker-Image veröffentlicht. Es gibt das Image für linux/amd64, linux/arm64 und linux/arm/v7, die Tags folgen den PocketBase-Versionen (Stand September 2026: 0.40.4; mit dieser Version wurde die Anleitung getestet).

Intern lauscht PocketBase auf Port 8090 (PB_PORT). Die compose.yaml veröffentlicht ihn als 8080 und nur auf 127.0.0.1; von außen erreichen Sie PocketBase über den Reverse Proxy.

# /opt/pocketbase/compose.yaml
services:
  pocketbase:
    image: ghcr.io/muchobien/pocketbase:0.40.4
    container_name: pocketbase
    restart: unless-stopped
    command: ["--encryptionEnv", "ENCRYPTION"]
    ports:
      - "127.0.0.1:8080:8090"
    environment:
      PB_HOST: "0.0.0.0"
      PB_PORT: "8090"
      PB_ADMIN_EMAIL: "${PB_ADMIN_EMAIL}"
      PB_ADMIN_PASSWORD: "${PB_ADMIN_PASSWORD}"
      ENCRYPTION: "${ENCRYPTION}"
    volumes:
      - pb_data:/pb_data
      - pb_hooks:/pb_hooks
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1:8090/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s

volumes:
  pb_data:
  pb_hooks:

Die wichtigsten Punkte im Überblick:

Parameter	Wert	Erklärung
Image	`ghcr.io/muchobien/pocketbase:0.40.4`	Community-Image, amd64/arm64/armv7
Port (extern)	`8080`	Host-Port, nur 127.0.0.1
Port (intern)	`8090`	Standard des Community-Images; via PB_PORT konfigurierbar
Volume pb_data	`/pb_data`	Pflicht: SQLite-DB, Uploads, Konfiguration
Volume pb_hooks	`/pb_hooks`	Optional: JavaScript-Hook-Skripte
command	`--encryptionEnv ENCRYPTION`	aktiviert die Verschlüsselung der Einstellungen
Health-Endpoint	`/api/health`	HTTP 200 wenn bereit

Verifizieren: docker compose config --quiet && echo OK gibt OK aus.

Schritt 4: Container starten

Starten Sie PocketBase im Projektordner:

cd /opt/pocketbase
docker compose up -d

Docker lädt das Image von ghcr.io, startet den Container, legt das Datenverzeichnis an und erstellt den Superuser aus der .env.

Verifizieren: Der Container meldet healthy:

docker compose ps

Erwartetes Ergebnis nach etwa 15 Sekunden:

NAME          IMAGE                                    STATUS
pocketbase    ghcr.io/muchobien/pocketbase:0.40.4      Up (healthy)

Zeigt der Status noch Up (health: starting), warten Sie kurz und wiederholen den Befehl. Bei Problemen helfen die Logs:

docker compose logs pocketbase

Der Health-Endpunkt antwortet:

curl -s http://localhost:8080/api/health

Erwartetes Ergebnis: {"message":"API is healthy.","code":200,"data":{}}

Schritt 5: Admin-UI öffnen und Superuser einrichten

Rufen Sie im Browser die Admin-Oberfläche auf:

http://localhost:8080/_/

Da PB_ADMIN_EMAIL und PB_ADMIN_PASSWORD gesetzt sind, hat das Image den Superuser beim Start angelegt; Sie melden sich direkt an. Ohne diese Variablen gibt PocketBase beim ersten Start im Log einen einmaligen Link zur Einrichtung aus (docker compose logs pocketbase).

Nach der Anmeldung sehen Sie:

Collections – Datenstrukturen (ähnlich Tabellen), die PocketBase automatisch als REST-Endpunkte bereitstellt.
API-Vorschau – je Collection über die Schaltfläche „API Preview“ in der Admin-Oberfläche, erzeugt aus der Collection-Definition.
Echtzeit-Subscriptions – Clients können sich per SSE auf /api/realtime auf Collection-Änderungen abonnieren; kein Redis, kein separater WebSocket-Server nötig.
Auth-Einstellungen – E-Mail/Passwort, OAuth2-Anbieter (Google, GitHub u. a.) und Einmalcodes (OTP) aktivieren Sie je Auth-Collection.

Verifizieren: Die Anmeldung mit den Werten aus der .env gelingt. Legen Sie testweise eine Collection an und setzen Sie die „List/Search rule“ auf leer (öffentlich); dann antwortet curl -s http://localhost:8080/api/collections/<name>/records mit JSON ("items":[]). Ohne Regel antwortet der Endpunkt nur Superusern.

Schritt 6: Datenpersistenz und Backup

Alle Daten (SQLite-Dateien, Uploads, Einstellungen) liegen im Volume pb_data. Docker Compose stellt den Projektnamen voran, das Volume heißt deshalb pocketbase_pb_data:

docker volume inspect pocketbase_pb_data

Die Ausgabe zeigt den Mountpoint, typischerweise /var/lib/docker/volumes/pocketbase_pb_data/_data.

PocketBase betreibt SQLite im WAL-Modus (Write-Ahead Logging). Ein Kopieren des Verzeichnisses im laufenden Betrieb kann deshalb einen inkonsistenten Stand erfassen; stoppen Sie dafür den Container. Im laufenden Betrieb nutzen Sie die eingebaute Sicherung (Settings → Backups) oder die API. Das Archiv landet in pb_data/backups:

# Superuser-Token holen und Sicherung anlegen
TOKEN=$(curl -s -X POST http://localhost:8080/api/collections/_superusers/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity":"admin@example.com","password":"IHR_ADMIN_PASSWORT"}' | sed -E 's/.*"token":"([^"]+)".*/\1/')
curl -s -X POST http://localhost:8080/api/backups \
  -H "Authorization: $TOKEN" -H "Content-Type: application/json" -d '{"name":"pb-backup.zip"}'

Eine Strategie für regelmäßige Sicherungen beschreibt die Anleitung 3-2-1-Backup-Strategie praktisch umsetzen.

Verifizieren: docker compose exec pocketbase ls /pb_data /pb_data/backups zeigt data.db und die Datei pb-backup.zip.

Schritt 7: Updates durchführen

Tragen Sie für ein Update den neuen Tag in der compose.yaml ein, nachdem Sie eine Sicherung angelegt und die Release Notes gelesen haben. PocketBase ist noch vor Version 1.0; Minor-Versionen können Änderungen mitbringen, die Anpassungen an Hooks oder Clients erfordern.

cd /opt/pocketbase
sed -i 's|pocketbase:0.40.4|pocketbase:NEUE_VERSION|' compose.yaml
docker compose pull
docker compose up -d

PocketBase führt Datenbankmigrationen beim Start aus. Prüfen Sie danach die Logs:

docker compose logs pocketbase | head -50

Zur Update-Benachrichtigung für Container siehe Docker-Container automatisch aktualisieren nach dem Watchtower-Aus.

Verifizieren: docker compose ps zeigt pocketbase mit dem neuen Tag und Up (healthy); docker compose exec pocketbase pocketbase --version nennt die neue Version.

Troubleshooting / Typische Fehler

Container nicht erreichbar (curl: (7) Failed to connect): Prüfen Sie mit docker compose logs pocketbase, ob die Startzeile Server started at http://0.0.0.0:8090 erscheint. Steht dort 127.0.0.1, ist PB_HOST falsch gesetzt. Aus dem Netz ist der Port absichtlich nicht erreichbar, weil er an 127.0.0.1 gebunden ist.
Port-Konflikt (Bind: address already in use): Port 8080 ist belegt. Ändern Sie den Host-Port in der compose.yaml (z. B. "127.0.0.1:8081:8090").
Datenverlust nach docker compose down: Wurde das Volume aus der compose.yaml entfernt, umbenannt oder der Projektordner umbenannt, legt Docker ein neues, leeres Volume an. docker volume ls zeigt, ob pocketbase_pb_data noch existiert; referenzieren Sie es wieder.
Anmeldung mit den Werten aus der .env scheitert: Das Image führt bei jedem Start pocketbase superuser upsert aus, allerdings nur ohne eigenes command oder wenn command mit einer Option wie --encryptionEnv beginnt. Nach einer Änderung der .env übernimmt docker compose up -d das neue Passwort (im Test mit 0.40.4 bestätigt).
ENCRYPTION nachträglich gesetzt: Ein geänderter oder verlorener Schlüssel macht die verschlüsselten Einstellungen (z. B. SMTP- und S3-Zugangsdaten) unlesbar. Sichern Sie den Wert zusammen mit dem Backup.
Image-Architektur-Mismatch (eigenes Dockerfile): Beim eigenen Image nach dem Alpine-Beispiel der Doku passen Sie die Download-URL an den Prozessor an: linux_amd64 für x86-Hosts, linux_arm64 für Apple Silicon / moderne ARM-Server, linux_arm für Raspberry Pi 3/4 (32-bit).
Reverse Proxy: falsche Client-IPs in den Logs: Hinter Nginx oder Traefik ohne korrekte Header protokolliert PocketBase die Proxy-IP. Leiten Sie X-Real-IP, X-Forwarded-For und X-Forwarded-Proto per proxy_set_header (Nginx) bzw. X-Forwarded-*-Middleware (Traefik) weiter und tragen Sie die Proxy-Adresse unter Settings → Application → User IP proxy headers ein.

Häufige Fragen

Brauche ich eine externe Datenbank wie PostgreSQL oder MySQL?

Nein. PocketBase nutzt eingebettetes SQLite; eine externe Datenbank ist nicht vorgesehen. Für kleine bis mittlere Lasten reicht das. Hohe parallele Schreiblast und horizontales Skalieren deckt PocketBase nicht ab.

Wie greife ich auf die Admin-UI zu?

Über http://localhost:8080/_/ bzw. die Domain des Reverse Proxys mit /_/. Ohne gesetzte Superuser-Variablen gibt PocketBase beim ersten Start einen Einrichtungslink im Log aus; legen Sie den Superuser sofort an.

Kann PocketBase hinter einem Reverse Proxy betrieben werden?

Ja, für den Produktivbetrieb empfohlen, damit der Proxy HTTPS übernimmt. Caddy, Nginx und Traefik eignen sich. Geben Sie die Proxy-Header (X-Real-IP, X-Forwarded-For, X-Forwarded-Proto) weiter. Für Caddy siehe Caddy als Reverse Proxy einrichten.

Unterstützt PocketBase Echtzeit-Updates?

Ja, per Server-Sent Events (SSE) unter /api/realtime. Clients abonnieren Änderungen an Collections und erhalten sie sofort, ohne zusätzliche Infrastruktur.

Welche Authentifizierungsverfahren sind verfügbar?

PocketBase unterstützt E-Mail/Passwort, OAuth2 (Google, GitHub, GitLab und weitere Anbieter), Einmalcodes per E-Mail (OTP) und Zwei-Faktor-Anmeldung (MFA), konfigurierbar in der Admin-Oberfläche.

Wie aktualisiere ich PocketBase auf eine neue Version?

Neuen Tag in der compose.yaml eintragen, dann docker compose pull && docker compose up -d. PocketBase migriert die Datenbank beim Start. Legen Sie vorher eine Sicherung an (Schritt 6).

Gibt es ein offizielles Docker-Image?

Nein. Die Dokumentation enthält nur ein Dockerfile-Beispiel. Das hier genutzte Image ghcr.io/muchobien/pocketbase stammt aus der Community und wird vom PocketBase-Projekt nicht offiziell unterstützt. Wer volle Kontrolle braucht, baut ein eigenes Image nach dem Alpine-Beispiel.

Fazit

PocketBase bündelt Datenbank, API, Authentifizierung und Admin-Oberfläche in einem Binary. Mit Docker Compose ist es in wenigen Minuten betriebsbereit. Für den Produktivbetrieb zählen drei Punkte: regelmäßige Sicherungen über die Backup-Funktion, ein festgeschriebenes Image-Tag und ein Reverse Proxy mit HTTPS. Innerhalb der Grenzen von SQLite eignet sich PocketBase für Prototypen, interne Werkzeuge und kleine Anwendungen.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: PocketBase Dokumentation – Going to Production | PocketBase GitHub Repository | ghcr.io/muchobien/pocketbase – Community Docker-Image