---
title: "PocketBase mit Docker installieren: Einzelnes Go-Binary als komplettes Backend"
date: 2026-08-20T14:33:54+02:00
modified: 2026-11-10T17:58:44+01:00
category: datenbanken
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/pocketbase-docker-backend-framework
reading_time: 8
personalize_url: "https://s-edv.com/anleitungen/pocketbase-docker-backend-framework#domain={domain}"
variables:
  - name: domain
    label: "Ihre Domain"
    default: "example.com"
  - name: pb_admin_password
    label: "Passwort (pb admin password)"
    generated_in_browser: true
  - name: ihr_schluessel_32_zeichen
    label: "Ihr schluessel 32 zeichen"
    generated_in_browser: true
---

# PocketBase mit Docker installieren: Einzelnes Go-Binary als komplettes Backend

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{domain}}` | Ihre Domain | `example.com` |
| `{{pb_admin_password}}` | Passwort (pb admin password) | wird im Browser des Lesers zufällig erzeugt |
| `{{ihr_schluessel_32_zeichen}}` | Ihr schluessel 32 zeichen | wird im Browser des Lesers zufällig erzeugt |

Link mit eigenen Werten: https://s-edv.com/anleitungen/pocketbase-docker-backend-framework#domain=cloud.example.com

Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server. Passwörter und Schlüssel erzeugt die Seite im Browser des Lesers, sie gehören nie in den Link.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben.

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.

**Kurzfassung:** Sie erstellen einen Projektordner mit `compose.yaml` und `.env` und starten PocketBase mit `docker compose up -d`. Das Image legt den Superuser aus der `.env` beim Start selbst an; die Admin-Oberfläche erreichen Sie unter `http://localhost:8080/_/`. Das Volume `pb_data` hält alle Daten, der Endpunkt `/api/health` dient dem Healthcheck. Für den Produktivbetrieb gehören ein Reverse Proxy mit HTTPS und ein festgeschriebenes Image-Tag dazu.

## 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](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage).
- [ ] **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](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung).
- [ ] `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`.

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

> **Prüfen:** `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:

Datei: `.env`

```ini
# /opt/pocketbase/.env

# Superuser (legt das Image bei jedem Start per "superuser upsert" an bzw. aktualisiert ihn)
PB_ADMIN_EMAIL=admin@{{domain}}
PB_ADMIN_PASSWORD={{pb_admin_password}}

# 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:

```bash
$ chmod 600 /opt/pocketbase/.env
```

> **Prüfen:** `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 (hier `0.40.4`).

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.

```yaml
# /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 |

> **Prüfen:** `docker compose config --quiet && echo OK` gibt `OK` aus.

## Schritt 4: Container starten

Starten Sie PocketBase im Projektordner:

```bash
$ 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`.

> **Prüfen:** Der Container meldet `healthy`:
>
> ```bash
> $ docker compose ps
> ```

Erwartetes Ergebnis nach etwa 15 Sekunden:

```bash
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:

```bash
$ docker compose logs pocketbase
```

Der Health-Endpunkt antwortet:

```bash
$ 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:

```bash
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:

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

> **Prüfen:** 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`:

```bash
$ 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`:

```bash
# 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@{{domain}}","password":"{{pb_admin_password}}"}' | 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](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen).

> **Prüfen:** `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.

```bash
$ 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:

```bash
$ docker compose logs pocketbase | head -50
```

Zur Update-Benachrichtigung für Container siehe [Docker-Container automatisch aktualisieren nach dem Watchtower-Aus](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-wud).

> **Prüfen:** `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

1. **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.
2. **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"`).
3. **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.
4. **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.
5. `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.
6. **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).
7. **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](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung).

### 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

1. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
2. [Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root)
3. [Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung)
4. [3-2-1-Backup-Strategie umsetzen: Anleitung mit Restic, USB-Disk und S3-Cloud](https://s-edv.com/anleitungen/3-2-1-backup-strategie-praktisch-umsetzen)

Offizielle Quellen: [PocketBase Dokumentation: Going to Production](https://pocketbase.io/docs/going-to-production/) | [PocketBase GitHub Repository](https://github.com/pocketbase/pocketbase) | [ghcr.io/muchobien/pocketbase: Community Docker-Image](https://github.com/muchobien/pocketbase-docker)
