CloudBeaver Community Edition läuft als Container auf einem Server und verwaltet Datenbankverbindungen und Berechtigungen zentral, bedient wird im Browser. Die Anleitung zeigt die Installation mit Docker Compose und einer PostgreSQL-Testdatenbank. Alle Schritte wurden am 30. September 2026 mit Version 26.2.1 getestet; nicht Getestetes ist gekennzeichnet.

Wofür CloudBeaver taugt und wo die Grenzen liegen

CloudBeaver ist der webbasierte Datenbank-Manager des DBeaver-Projekts (Community Edition: Apache-2.0, ohne Lizenzschlüssel) mit SQL-Editor, Daten-Editor, Schema-Navigator, Import und Export. Typischer Einsatz: Dienstleister erhalten Datenbankzugriff ohne VPN und ohne Zugangsdaten im Klartext.

Die Grenzen:

Kein Ersatz für DBeaver Desktop und kein Monitoring.
Community gegenüber Enterprise. Externe Identitätsanbieter, Cluster und Support nur in der kostenpflichtigen Edition; Community hat lokale Benutzer.
Kein Backup-Werkzeug. Sicherungen bleiben Aufgabe der Datenbank.
Eingebettete Konfigurationsdatenbank. Einstellungen liegen in einer H2-Datenbank im Workspace; genügt für kleine Installationen.

Geprüftes Projekt und Versionsstand

Angabe	Wert	Quelle, Stand 30. September 2026
Repository	dbeaver/cloudbeaver	GitHub
Lizenz	Apache-2.0	GitHub
Aktuelle Version	26.2.1 vom 21. September 2026	Docker-Hub-Tag-Liste
Laufender Build im Test	26.2.1.202609211213	Startprotokoll und API
Architekturen	amd64 und arm64	Docker-Hub-Tag-Liste
Image-Größe	rund 1,2 GB entpackt	eigener Test, `docker images`

Voraussetzungen und Ressourcenbedarf

Docker mit Compose-Plugin v2.
Arbeitsspeicher. Im Test im Leerlauf rund 200 MB plus 30 MB (PostgreSQL); planen Sie für die JVM unter Last mindestens 1 GB ein.
Plattenplatz. Rund 3 GB (Image, Workspace, JDBC-Treiber, Updates).
Startzeit. Im Test 40 bis 50 Sekunden bis zur ersten Antwort (1 CPU).
Netz. Internetzugang zum Nachladen von JDBC-Treibern.

Verifizieren: docker compose version gibt eine Version 2.x aus, free -h zeigt mindestens 1 GB verfügbaren Speicher.

Verzeichnisstruktur und persistente Pfade

Der gesamte Zustand liegt unter /opt/cloudbeaver/workspace; ohne persistentes Volume gehen Benutzer, Verbindungen und Einstellungen verloren. Workspace nach dem ersten Start im Test:

# Inhalt des Workspace nach dem ersten Start
drwxrwxr-x  dbeaver dbeaver  .data
drwxrwxr-x  dbeaver dbeaver  GlobalConfiguration
drwxrwxr-x  dbeaver dbeaver  .metadata
# In .data liegen die H2-Konfigurationsdatenbank und die Laufzeitkonfiguration
-rw-rw-r--  dbeaver dbeaver  cb.h2v2.dat.mv.db
-rw-rw-r--  dbeaver dbeaver  .cloudbeaver.runtime.conf
-rw-rw-r--  dbeaver dbeaver  .database-credentials.dat
# Die angelegten Verbindungen landen hier
GlobalConfiguration/.dbeaver/data-sources.json

Die Dateien gehören dbeaver (UID 8978), der Hauptprozess läuft als root. Ein benanntes Volume übernimmt die Rechte aus dem Image, bei Bind-Mounts siehe Typische Fehler. Die cloudbeaver.conf liest Umgebungsvariablen, eine eigene Datei ist nicht nötig.

Die vollständige compose.yaml

CloudBeaver plus PostgreSQL-Testdatenbank; bei vorhandener Datenbank entfällt der zweite Dienst.

services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:26.2.1
    container_name: cloudbeaver
    restart: unless-stopped
    ports:
      # Nur an localhost binden, Veröffentlichung übernimmt der Reverse Proxy
      - "127.0.0.1:8978:8978"
    volumes:
      - cloudbeaver_workspace:/opt/cloudbeaver/workspace
    environment:
      TZ: Europe/Berlin
      CLOUDBEAVER_WEB_SERVER_PORT: "8978"
      # Anonymen Zugriff ausdrücklich abschalten
      CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLED: "false"
      # Eigene Verbindungen durch Benutzer erlauben
      CLOUDBEAVER_APP_SUPPORTS_CUSTOM_CONNECTIONS: "true"
      # Oberfläche auf Deutsch vorbelegen
      CLOUDBEAVER_CORE_LOCALIZATION: "de"
      # Schutz gegen Passwortraten aktiv lassen
      CLOUDBEAVER_BRUTE_FORCE_PROTECTION_ENABLED: "true"
      CLOUDBEAVER_MAX_FAILED_LOGINS: "10"
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - cb_net
  postgres:
    image: postgres:17-alpine
    container_name: cloudbeaver-postgres
    restart: unless-stopped
    ports:
      # Nur für lokale Werkzeuge, nicht nach außen öffnen
      - "127.0.0.1:5432:5432"
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - cb_net
volumes:
  cloudbeaver_workspace:
  postgres_data:
networks:
  cb_net:
    driver: bridge

Feste Version statt latest. Ein Versionssprung migriert den Workspace.
Bindung an 127.0.0.1. Sonst umgeht der Port die Host-Firewall.
Healthcheck an PostgreSQL mit depends_on. CloudBeaver startet erst nach der Datenbank.
Eigenes Netzwerk. Beide Dienste finden sich über ihre Dienstnamen.

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

Die .env-Datei

Die Zugangsdaten gehören in eine .env neben der compose.yaml, nicht ins Git.

# .env, liegt neben der compose.yaml; Platzhalter ersetzen
POSTGRES_DB=demo_db
POSTGRES_USER=demo_user
POSTGRES_PASSWORD=IHR_LANGES_ZUFALLSPASSWORT

# Zufallspasswort erzeugen
openssl rand -base64 32
# Rechte der .env einschränken
chmod 600 .env
# Prüfen, dass Compose die Werte korrekt einsetzt
docker compose config | grep -A2 POSTGRES_USER

Verifizieren: docker compose config zeigt Ihre Werte ohne Warnung über fehlende Variablen.

Die wichtigsten Umgebungsvariablen

Quelle: cloudbeaver.conf im Image, Standardwerte für Version 26.2.

Variable	Standard	Bedeutung
`CLOUDBEAVER_WEB_SERVER_PORT`	8978	Port, auf dem Jetty im Container lauscht
`CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLED`	true	Zugriff ohne Anmeldung. Sollte auf `false` stehen
`CLOUDBEAVER_APP_SUPPORTS_CUSTOM_CONNECTIONS`	false	Dürfen Benutzer selbst Verbindungen anlegen
`CLOUDBEAVER_CORE_LOCALIZATION`	en	Sprache der Oberfläche, `de` wird unterstützt
`CLOUDBEAVER_FORCE_HTTPS`	false	Erzwingt HTTPS. Hinter einem Reverse Proxy meist nicht nötig
`CLOUDBEAVER_BRUTE_FORCE_PROTECTION_ENABLED`	true	Sperrt nach zu vielen Fehlversuchen
`CLOUDBEAVER_MAX_FAILED_LOGINS`	10	Fehlversuche bis zur Sperre
`CLOUDBEAVER_BLOCK_PERIOD`	300	Sperrdauer in Sekunden
`CLOUDBEAVER_POLICY_MIN_LENGTH`	8	Mindestlänge für Benutzerpasswörter
`CLOUDBEAVER_EXPIRE_SESSION_AFTER_PERIOD`	1800000	Sitzungsablauf in Millisekunden, entspricht 30 Minuten
`CLOUDBEAVER_RESOURCE_QUOTA_SQL_RESULT_SET_ROWS_LIMIT`	100000	Obergrenze für Zeilen je Ergebnis, schützt den Arbeitsspeicher
`CLOUDBEAVER_DB_BACKUP_ENABLED`	true	Sicherung der internen H2-Datenbank vor Schema-Migrationen
`CLOUDBEAVER_APP_FORWARD_PROXY`	false	Auswertung von Proxy-Kopfzeilen, relevant hinter einem Reverse Proxy

Schalten Sie vor dem Produktivbetrieb den anonymen Zugriff ab und erhöhen Sie die Passwort-Mindestlänge.

Start und Ersteinrichtung

sudo mkdir -p /opt/stacks/cloudbeaver
sudo chown "$USER": /opt/stacks/cloudbeaver
cd /opt/stacks/cloudbeaver
# compose.yaml und .env hier ablegen, dann starten
docker compose up -d
docker compose ps
docker compose logs -f cloudbeaver

Beim ersten Start erscheinen diese Zeilen; der Hinweis zur fehlenden Auto-Konfiguration ist kein Fehler:

DEBUG io.cloudbeaver.server.CBApplication - CloudBeaver Community 26.2.1.202609211213 is starting
INFO  io.cloudbeaver.server.CBApplication - No auto configuration was found. Server must be configured manually

Rufen Sie dann http://127.0.0.1:8978/ auf (entfernt per SSH-Tunnel ssh -L 8978:127.0.0.1:8978 benutzer@server). Der Assistent fragt Servername, Server-URL und das erste Administratorkonto ab. Im Test meldete der Server nach der Ersteinrichtung configurationMode: false, die Anmeldung gelang.

Wählen Sie ein langes, einmaliges Administratorpasswort (Zugriff auf alle Verbindungen) und schließen Sie die Einrichtung sofort ab: Bis dahin kann jeder mit Zugriff das Administratorkonto anlegen.

Verifizieren: docker compose ps zeigt beide Container als Up, PostgreSQL mit (healthy). Nach der Einrichtung erscheint beim Aufruf der Oberfläche die Anmeldemaske statt des Assistenten.

Verbindung zur PostgreSQL-Datenbank anlegen

Legen Sie in der Oberfläche eine neue PostgreSQL-Verbindung an. Als Host gehört der Dienstname aus der Compose-Datei eingetragen, also postgres, nicht localhost (das wäre der Container selbst). Im Test scheiterte localhost mit „Connection to localhost:5432 refused“.

Feld	Wert
Treiber	PostgreSQL
Host	`postgres`
Port	5432
Datenbank	Wert aus `POSTGRES_DB`
Benutzer	Wert aus `POSTGRES_USER`
Passwort	Wert aus `POSTGRES_PASSWORD`

Eine Testtabelle legen Sie so an:

docker compose exec postgres psql -U demo_user -d demo_db \
  -c "CREATE TABLE kunden (id serial primary key, name text, ort text);" \
  -c "INSERT INTO kunden (name, ort) VALUES ('Beispiel GmbH','Dresden');" \
  -c "SELECT * FROM kunden;"

Dateibasierte Treiber (DuckDB, eingebettetes H2, SQLite) sind ab Werk deaktiviert, da sie Dateizugriffe auf dem Server erlauben.

Verifizieren: Der Verbindungstest in der Oberfläche meldet Erfolg, und im SQL-Editor liefert SELECT * FROM kunden; die Zeile „Beispiel GmbH“.

Funktions- und Healthcheck

Das Image hat keinen Healthcheck und weder curl noch wget. Dieser Healthcheck prüft per bash, ob Jetty Verbindungen annimmt (die /dev/tcp-Prüfung lief im Test im Container, als Healthcheck-Block nicht):

    healthcheck:
      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8978"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 90s

Von außen prüfen Sie so:

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8978/
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8978/status
docker compose logs cloudbeaver | grep "is starting"

Verifizieren: Beide curl-Aufrufe liefern 200, der letzte Befehl zeigt die laufende Version.

Sichere Netzwerkfreigabe und Reverse Proxy mit TLS

Stellen Sie CloudBeaver nie ungeschützt ins Internet: Es hält Datenbank-Zugangsdaten und einen SQL-Editor mit Schreibzugriff. Reihenfolge:

Port ausschließlich an 127.0.0.1 binden.
CLOUDBEAVER_APP_ANONYMOUS_ACCESS_ENABLED auf false setzen.
Ersteinrichtung mit dem Administratorkonto sofort abschließen.
Erst danach einen Reverse Proxy mit TLS davorsetzen.
Wenn möglich zusätzlich VPN oder eine Beschränkung nach Quell-IP nutzen.

Mit Caddy (Zertifikat automatisch), nur der erlaubte Zweig wird weitergeleitet, sonst 403. Nicht getestet:

datenbank.example.com {
    @erlaubt remote_ip 203.0.113.0/24 198.51.100.10
    handle @erlaubt {
        reverse_proxy 127.0.0.1:8978
    }
    handle {
        respond 403
    }
}

Mit nginx; die WebSocket-Kopfzeilen sind für die Ereignisverbindung nötig. Nicht getestet:

server {
    listen 443 ssl http2;
    server_name datenbank.example.com;
    ssl_certificate     /etc/letsencrypt/live/datenbank.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/datenbank.example.com/privkey.pem;
    client_max_body_size 128M;
    location / {
        proxy_pass http://127.0.0.1:8978;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
    }
}

Hinter einem Reverse Proxy CLOUDBEAVER_APP_FORWARD_PROXY auf true setzen, sonst sieht der Passwortraten-Schutz nur eine Adresse.

Verifizieren: Von einem anderen Rechner schlägt curl http://SERVER-IP:8978/ fehl, über die Domain erscheint die Anmeldemaske mit gültigem Zertifikat.

Der AI Assistant und die Datenschutzfolgen

Seit 26.2.0 enthält CloudBeaver laut Changelog einen AI Assistant (Chat im SQL-Editor, KI-Profile für OpenAI und Copilot), der Tabellen- und Spaltennamen, gegebenenfalls Beispieldaten, an den Anbieter sendet.

Ohne API-Schlüssel ist er nicht nutzbar; laut Changelog lassen sich alle KI-Funktionen in der Serverkonfiguration abschalten. Bei personenbezogenen Daten ohne Auftragsverarbeitungsvertrag: abschalten und dokumentieren (nicht getestet).

Backup und vollständige Wiederherstellung

Zu sichern sind Workspace (Benutzer, Verbindungen) und Datenbank-Nutzdaten (pg_dump). Das Volume heißt nach dem Compose-Projekt, bei /opt/stacks/cloudbeaver cloudbeaver_cloudbeaver_workspace (docker volume ls --filter name=cloudbeaver). Im Test samt Wiederherstellung in ein geleertes Volume durchgespielt.

sudo mkdir -p /opt/backups/cloudbeaver
# 1. Container stoppen, damit die H2-Datenbank konsistent ist
docker compose stop cloudbeaver
# 2. Volume in ein Archiv sichern
docker run --rm \
  -v cloudbeaver_cloudbeaver_workspace:/workspace:ro \
  -v /opt/backups/cloudbeaver:/backup \
  alpine tar czf /backup/cloudbeaver-workspace.tar.gz -C /workspace .
# 3. Datenbank getrennt sichern
docker compose exec -T postgres pg_dump -U demo_user demo_db \
  | sudo tee /opt/backups/cloudbeaver/demo_db.sql > /dev/null
# 4. Container wieder starten
docker compose start cloudbeaver

Wiederherstellung:

docker compose stop cloudbeaver
docker run --rm \
  -v cloudbeaver_cloudbeaver_workspace:/workspace \
  -v /opt/backups/cloudbeaver:/backup:ro \
  alpine tar xzf /backup/cloudbeaver-workspace.tar.gz -C /workspace
docker compose start cloudbeaver

Verifizieren: Nach dem Start (im Test rund 36 Sekunden) liefert http://127.0.0.1:8978/ wieder 200, die Anmeldung mit dem Administratorkonto gelingt, und die zuvor angelegten Verbindungen sind vorhanden.

Updates und die Grenzen des Rollbacks

# 1. Workspace sichern (siehe oben), Datei z. B. workspace-vor-update.tar.gz
# 2. Versionsangabe in der compose.yaml auf die neue Fassung setzen
# 3. Neues Image laden und Container neu erstellen
docker compose pull cloudbeaver
docker compose up -d
# 4. Migration im Protokoll verfolgen
docker compose logs -f cloudbeaver

CloudBeaver migriert beim Start das H2-Schema, meist nicht rückwärtskompatibel. Rollback heißt: altes Image plus Workspace-Archiv von vor dem Update. Überspringen Sie keine Hauptversionen.

Verifizieren: docker compose logs cloudbeaver | grep "is starting" zeigt die neue Version, Anmeldung und Verbindungen funktionieren.

Typische Fehler, Diagnose und Lösung

Port bereits belegt. Docker meldet dann:

Bind for 127.0.0.1:8978 failed: port is already allocated

Prozess finden: ss -tlnp | grep 8978; sonst freien Host-Port wählen, etwa 127.0.0.1:18978:8978.

Verbindung zur Datenbank schlägt fehl. Meist steht localhost als Host, siehe Abschnitt Verbindung. Erreichbarkeit im Container prüfen:

docker compose exec cloudbeaver getent hosts postgres
docker compose exec cloudbeaver bash -c "(exec 3<>/dev/tcp/postgres/5432) && echo erreichbar"

Externe Datenbank: deren IP eintragen und den Container in deren Firewall zulassen.

Rechteprobleme am Volume. Meist ein Bind-Mount mit falschem Eigentümer (UID/GID 8978):

docker compose exec cloudbeaver ls -lan /opt/cloudbeaver/workspace
sudo chown -R 8978:8978 /opt/stacks/cloudbeaver/workspace

Container beendet sich sofort.

docker compose logs --tail 80 cloudbeaver
docker inspect cloudbeaver --format '{{.State.ExitCode}} {{.State.OOMKilled}}'

OOMKilled true: zu wenig Arbeitsspeicher, typisch bei großen Ergebnismengen. Senken Sie CLOUDBEAVER_RESOURCE_QUOTA_SQL_RESULT_SET_ROWS_LIMIT oder erhöhen Sie den Speicher.

Oberfläche antwortet kurz nach dem Start nicht. Rund 40 Sekunden sind normal (siehe Startzeit).

Saubere Deinstallation

# Container und Netzwerk entfernen, Daten in den Volumes bleiben erhalten
docker compose down
docker image rm dbeaver/cloudbeaver:26.2.1 postgres:17-alpine

Warnung: Der folgende Befehl löscht ohne Rückfrage auch Workspace und PostgreSQL-Datenbank. Vorher sichern.

docker compose down -v
docker volume ls --filter name=cloudbeaver

Verifizieren: docker volume ls --filter name=cloudbeaver und docker compose ps geben keine Einträge mehr aus.

Passende Anleitungen auf S-EDV

Quellen

GitHub: dbeaver/cloudbeaver, Projektstand, Lizenz und Changelog, abgerufen am 30. September 2026
CloudBeaver Wiki: Deployment, offizielle Hinweise zum Betrieb im Container
Offizielle CloudBeaver-Dokumentation, Serverkonfiguration, Funktionsumfang und Editionsunterschiede
Docker Hub: dbeaver/cloudbeaver, Tag-Liste und Architekturen, abgerufen am 30. September 2026