Wer APIs entwickelt oder testet, greift oft reflexartig zu Postman – dabei schickt man dabei alle Anfragen und Collections in die Cloud eines US-amerikanischen Unternehmens. Hoppscotch bietet hier eine datenschutzkonforme Alternative: Das quelloffene API-Entwicklungs-Ökosystem unterstützt REST, GraphQL, WebSocket, SSE, Socket.IO und MQTT in einer modernen Browser-Oberfläche. Mit 79.500+ GitHub-Sternen (Stand Juni 2026) und monatlichen Releases ist das Projekt aktiv gepflegt – und seit 2024 lässt es sich dank des fertigen All-in-One-Docker-Images in Minuten selbst hosten, ohne auch nur eine Zeile Quellcode zu bauen. Für Entwicklungsteams in KMU, die ihre API-Workflows aus der Cloud holen wollen, ist Hoppscotch damit ein ernsthafter Kandidat.

Voraussetzungen

Docker Engine v20+ und Docker Compose Plugin v2+ installiert – falls noch nicht vorhanden, hilft die Anleitung Docker und Docker Compose auf Linux installieren weiter.
Linux-Host, VM oder NAS mit Docker-Unterstützung (x86-64 oder ARM64); mindestens 1 CPU-Kern und 2 GB RAM für den Betrieb, 4 Kerne / 4 GB RAM empfohlen.
Ports 3000, 3100 und 3170 erreichbar (lokal oder per Firewall-Regel freigegeben).
Mindestens 1 GB freier Speicher für das PostgreSQL-Volume.
openssl oder PowerShell verfügbar, um einen sicheren 32-Zeichen-Schlüssel zu generieren.
Optional: Domain + TLS-Zertifikat für HTTPS-Produktivbetrieb; einen SMTP-Server für Team-Einladungen per E-Mail.

Schritt 1: Eckdaten und Projektordner anlegen

Bevor es losgeht, ein Überblick über die wichtigsten Kenndaten des Setups:

Parameter	Wert
Image	hoppscotch/hoppscotch:latest (AIO)
Aktuelle Version	2026.5.0 (28. Mai 2026)
Imagegröße	~239 MB (amd64), ~236 MB (arm64)
Datenbank-Image	postgres:15
Port Frontend	3000
Port Admin-Dashboard	3100
Port Backend-API	3170
Persistenz	Named Volume hoppscotch-db-data
Lizenz	MIT (Community Edition, kostenlos)

Lege zunächst einen Projektordner an und wechsle hinein:

mkdir -p /opt/hoppscotch
cd /opt/hoppscotch

Verifizieren: Der Ordner existiert und ist leer.

ls -la /opt/hoppscotch

Schritt 2: .env-Datei mit Secrets anlegen

Hoppscotch bezieht seine gesamte Konfiguration aus Umgebungsvariablen – es gibt kein Config-File im Container. Wichtig: Niemals Anführungszeichen um die Werte in der .env-Datei verwenden, da Hoppscotch sie wörtlich interpretiert und Anführungszeichen als Teil des Wertes behandelt.

Generiere zunächst zwei sichere Schlüssel. Unter Linux/macOS:

# 32-Zeichen-Schlüssel für DATA_ENCRYPTION_KEY
openssl rand -base64 32 | cut -c1-32

# Sicheres PostgreSQL-Passwort
openssl rand -base64 24 | tr -dc 'a-zA-Z0-9' | head -c 20

Unter Windows (PowerShell):

-join ((65..90)+(97..122)+(48..57) | Get-Random -Count 32 | ForEach-Object {[char]$_})

Erstelle nun die .env-Datei mit den generierten Werten:

# ─── Datenbank ────────────────────────────────────────────────────
DATABASE_URL=postgresql://postgres:DEIN_SICHERES_PASSWORT@hoppscotch-db:5432/hoppscotch
POSTGRES_PASSWORD=DEIN_SICHERES_PASSWORT

# ─── Verschlüsselung (EXAKT 32 Zeichen!) ──────────────────────────
DATA_ENCRYPTION_KEY=DEIN_32_ZEICHEN_SCHLUESSEL_HIER

# ─── Öffentliche URLs (bei Reverse-Proxy: echte Domain eintragen) ─
VITE_BASE_URL=http://localhost:3000
VITE_SHORTCODE_BASE_URL=http://localhost:3000
VITE_ADMIN_URL=http://localhost:3100
VITE_BACKEND_GQL_URL=http://localhost:3170/graphql
VITE_BACKEND_WS_URL=ws://localhost:3170/graphql
VITE_BACKEND_API_URL=http://localhost:3170/v1

# ─── CORS-Whitelist (alle genutzten URLs, kommasepariert) ─────────
WHITELISTED_ORIGINS=http://localhost:3170,http://localhost:3000,http://localhost:3100,app://localhost_3200,app://hoppscotch

# ─── Authentifizierung ────────────────────────────────────────────
VITE_ALLOWED_AUTH_PROVIDERS=EMAIL

# ─── SMTP für Team-Einladungen (optional, aber für EMAIL-Auth nötig)
# MAILER_SMTP_URL=smtps://user@domain.com:pass@smtp.domain.com
# MAILER_USE_CUSTOM_CONFIGS=false

Ersetze DEIN_SICHERES_PASSWORT und DEIN_32_ZEICHEN_SCHLUESSEL_HIER durch die zuvor generierten Werte. Das Passwort in DATABASE_URL und POSTGRES_PASSWORD muss identisch sein. Der DATA_ENCRYPTION_KEY muss exakt 32 Zeichen lang sein – ein abweichender Wert führt zu einem Startfehler des Backends.

Verifizieren: Prüfe die Schlüssellänge:

grep DATA_ENCRYPTION_KEY /opt/hoppscotch/.env | awk -F= '{print length($2)}'
# Erwartete Ausgabe: 32

Schritt 3: compose.yaml erstellen

Das Setup besteht aus drei Services: der PostgreSQL-Datenbank, einem einmaligen Migrationsdienst und dem eigentlichen Hoppscotch-Container. Der Migrationsdienst ist kein optionaler Komfort – ohne ihn startet das Backend in einer Dauerschleife, weil die Datenbankschemas fehlen. Wer sich mit dem Compose-Format noch nicht auskennt, findet die Grundlagen in der Anleitung Docker Compose: Multi-Container-Stacks aufbauen.

services:
  hoppscotch-db:
    image: postgres:15
    restart: unless-stopped
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: hoppscotch
    volumes:
      - hoppscotch-db-data:/var/lib/postgresql/data
    networks:
      - hoppscotch-net
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d hoppscotch"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  hoppscotch-migrate:
    image: hoppscotch/hoppscotch:latest
    env_file:
      - .env
    command: ["pnpm", "exec", "prisma", "migrate", "deploy"]
    depends_on:
      hoppscotch-db:
        condition: service_healthy
    networks:
      - hoppscotch-net
    restart: on-failure

  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "3000:3000"
      - "3100:3100"
      - "3170:3170"
    depends_on:
      hoppscotch-db:
        condition: service_healthy
      hoppscotch-migrate:
        condition: service_completed_successfully
    networks:
      - hoppscotch-net

volumes:
  hoppscotch-db-data:

networks:
  hoppscotch-net:
    driver: bridge

Zwei Designentscheidungen verdienen eine kurze Erklärung: hoppscotch wartet per condition: service_completed_successfully darauf, dass der Migrationsdienst erfolgreich abgeschlossen hat – das verhindert Startfehler wegen fehlender DB-Tabellen. Der Healthcheck auf PostgreSQL stellt sicher, dass weder Migration noch App starten, bevor die Datenbank wirklich bereit ist.

Verifizieren: Beide Dateien liegen im Projektordner:

ls -1 /opt/hoppscotch
# Erwartete Ausgabe:
# .env
# compose.yaml

Schritt 4: Container starten

Starte alle Services im Hintergrund. Docker Compose lädt das Image beim ersten Start automatisch herunter (~239 MB):

cd /opt/hoppscotch
docker compose up -d

Der Ablauf beim ersten Start: PostgreSQL startet und wird gesund gemeldet → der Migrationsdienst läuft die Prisma-Migrationen durch → erst dann startet der Hoppscotch-Container. Das dauert je nach Verbindungsgeschwindigkeit und Hardware 1–3 Minuten.

Verifizieren: Prüfe den Status aller Container:

docker compose ps
# Erwartete Ausgabe (STATUS):
# hoppscotch-db       running (healthy)
# hoppscotch-migrate  exited (0)       ← 0 = erfolgreich abgeschlossen
# hoppscotch          running

Prüfe, ob das Frontend antwortet:

curl -I http://localhost:3000
# Erwartete Ausgabe: HTTP/1.1 200 OK

Bei Problemen helfen die Logs weiter:

docker compose logs hoppscotch --tail=50
docker compose logs hoppscotch-migrate --tail=50

Schritt 5: Admin-Dashboard und Erst-Einrichtung

Nach dem ersten Start ist die Instanz noch nicht nutzbar – du musst zunächst den ersten Admin-Nutzer anlegen. Öffne dazu im Browser:

Admin-Dashboard: http://localhost:3100 – hier läuft der Setup-Wizard für den ersten Admin
Hoppscotch-App: http://localhost:3000 – die eigentliche API-Testing-Oberfläche

Gehe auf Port 3100 und folge dem Setup-Wizard: E-Mail und Passwort für den ersten Admin-Account eingeben, bestätigen – fertig. Danach kannst du im Admin-Dashboard weitere Nutzer einladen, Teams anlegen und die Instanz verwalten.

Falls du VITE_ALLOWED_AUTH_PROVIDERS=EMAIL gesetzt hast, benötigst du außerdem einen funktionierenden SMTP-Server, damit der E-Mail-Versand für Einladungen und Passwort-Reset funktioniert. Trage dazu die entsprechenden Variablen in der .env-Datei nach und starte den Container neu:

docker compose up -d --force-recreate hoppscotch

Verifizieren: Öffne http://localhost:3000 im Browser. Du solltest die Hoppscotch-Oberfläche sehen und dich mit dem im Admin-Dashboard angelegten Account einloggen können. Erstelle einen Test-Request (z. B. GET https://httpbin.org/get) und überprüfe, ob die Antwort korrekt angezeigt wird.

curl -I http://localhost:3100
# Erwartete Ausgabe: HTTP/1.1 200 OK (Admin-Dashboard erreichbar)

Schritt 6: Updates und Datensicherung

Hoppscotch folgt einem monatlichen Release-Rhythmus (Format: Jahr.Monat.Patch). Ein Update läuft wie bei allen Docker-Compose-Setups ab – vorher unbedingt ein PostgreSQL-Backup erstellen. Die Anleitung MySQL & PostgreSQL Backup automatisieren mit cron und rclone beschreibt, wie du diesen Schritt automatisierst.

cd /opt/hoppscotch

# Vorher: PostgreSQL-Backup erstellen
docker exec hoppscotch-db pg_dump -U postgres hoppscotch > hoppscotch_backup_$(date +%Y%m%d).sql

# Images aktualisieren und Container neu starten
docker compose pull
docker compose up -d

Beim Update führt der hoppscotch-migrate-Service automatisch neue Datenbankmigrationen aus, bevor der Hauptcontainer hochkommt. Wichtig: Verwende beim Herunterfahren niemals docker compose down -v – das löscht das Named Volume mit allen Datenbankdaten. Ohne das Flag (docker compose down) bleiben die Volumes erhalten.

Verifizieren: Nach dem Update zeigt die Versions-Info im Admin-Dashboard (Port 3100) die neue Versionsnummer. Prüfe außerdem, ob alle Collections und Teams noch vorhanden sind.

docker compose ps
# Alle Container sollten wieder im Status "running" sein

Optional: Reverse Proxy und HTTPS

Für den Produktivbetrieb solltest du Hoppscotch hinter einem Reverse Proxy mit TLS betreiben. Die Anleitung Traefik als Docker-Reverse-Proxy mit automatischem HTTPS zeigt den empfohlenen Weg. Passe dafür die VITE_*-Variablen in der .env-Datei auf deine Domain an:

VITE_BASE_URL=https://hoppscotch.example.com
VITE_SHORTCODE_BASE_URL=https://hoppscotch.example.com
VITE_ADMIN_URL=https://admin.hoppscotch.example.com
VITE_BACKEND_GQL_URL=https://api.hoppscotch.example.com/graphql
VITE_BACKEND_WS_URL=wss://api.hoppscotch.example.com/graphql
VITE_BACKEND_API_URL=https://api.hoppscotch.example.com/v1
WHITELISTED_ORIGINS=https://hoppscotch.example.com,https://admin.hoppscotch.example.com,https://api.hoppscotch.example.com,app://localhost_3200,app://hoppscotch
TRUST_PROXY=true

Beachte: Bei HTTPS muss VITE_BACKEND_WS_URL zwingend wss:// statt ws:// verwenden, sonst schlagen WebSocket-Verbindungen im Browser fehl. Alle genutzten Domains müssen in WHITELISTED_ORIGINS eingetragen sein. Alternativ lassen sich alle drei Dienste über einen einzigen Port bündeln: ENABLE_SUBPATH_BASED_ACCESS=true aktiviert Routing über / (App), /admin (Dashboard) und /backend (API) – das vereinfacht das Reverse-Proxy-Setup erheblich.

Troubleshooting / Typische Fehler

„Can't reach database server at localhost:5432" – In DATABASE_URL steht localhost statt des Docker-Service-Namens. Der Hostname im Connection-String muss hoppscotch-db lauten.
„Invalid encryption key length" / Backend-Absturz beim Start – DATA_ENCRYPTION_KEY ist nicht exakt 32 Zeichen lang. Mit openssl rand -base64 32 | cut -c1-32 generieren und Länge prüfen: echo -n "SCHLUESSEL" | wc -c.
CORS-Fehler im Browser – Die aufrufende Origin fehlt in WHITELISTED_ORIGINS. Alle genutzten URLs inklusive Ports kommasepariert und ohne Leerzeichen eintragen, danach Container neu starten.
Login schlägt fehl / Admin-Dashboard zeigt leere Seite – Entweder wurde der erste Admin-Nutzer noch nicht über Port 3100 angelegt, oder VITE_ALLOWED_AUTH_PROVIDERS ist leer. Mindestens EMAIL eintragen.
WebSocket-Verbindung schlägt fehl bei HTTPS – VITE_BACKEND_WS_URL verwendet noch ws:// statt wss://. Bei SSL-Deployment zwingend wss:// verwenden.
Anführungszeichen in .env führen zu Verbindungsfehlern – Hoppscotch interpretiert Anführungszeichen als Teil des Wertes. DATABASE_URL="postgresql://..." schlägt fehl, DATABASE_URL=postgresql://... ist korrekt.
hoppscotch startet, aber Backend läuft in Dauerschleife – Der Migrationsdienst wurde nicht erfolgreich abgeschlossen. Logs prüfen: docker compose logs hoppscotch-migrate. Häufige Ursache: falsche DATABASE_URL oder falscher Hostname.
Nach Update sind Daten weg – docker compose down -v wurde verwendet, das löscht Named Volumes. Für reguläres Herunterfahren immer docker compose down ohne -v verwenden.
VITE_*-URLs zeigen auf localhost, Anwendung hinter Reverse-Proxy nicht erreichbar – Alle VITE_*-Variablen auf die öffentliche Domain anpassen und Container neu erstellen: docker compose up -d --force-recreate hoppscotch.

Häufige Fragen

Muss ich das GitHub-Repository klonen, um Hoppscotch selbst zu hosten?

Nein. Das AIO-Image (hoppscotch/hoppscotch:latest) aus Docker Hub ist vollständig und enthält Frontend, Backend und Admin-Dashboard. Du benötigst lokal nur die compose.yaml und die .env-Datei – kein Build-Schritt, kein Klonen des Repositories.

Kann ich Hoppscotch ohne OAuth-Provider (GitHub/Google) betreiben?

Ja, wenn EMAIL als Auth-Provider konfiguriert ist und ein funktionierender SMTP-Server verfügbar ist. Für rein lokale Tests ohne E-Mail-Versand kannst du zunächst ohne SMTP starten und den Admin-Account direkt über Port 3100 anlegen – die eigentliche App auf Port 3000 ist danach mit diesem Account nutzbar.

Was ist der Unterschied zwischen dem AIO-Image und den getrennten Images?

Das AIO-Image (hoppscotch/hoppscotch:latest) kombiniert Frontend, Backend und Admin in einem Container – einfacher zu betreiben und ideal für KMU. Die getrennten Images (hoppscotch/hoppscotch-frontend, -backend, -admin) ermöglichen unabhängiges Skalieren einzelner Komponenten, erfordern aber eine aufwändigere Konfiguration mit drei separaten Services.

Ist die Community Edition dauerhaft kostenlos für Teams?

Ja. Die Community Edition (MIT-Lizenz) ist vollständig kostenlos und enthält Team-Kollaboration, geteilte Collections, Workspaces und rollenbasierte Zugriffskontrolle. Die Enterprise Edition bietet zusätzlich SSO/SAML und erweiterte RBAC-Features gegen Lizenzgebühr – für die meisten KMU ist die CE ausreichend.

Wie aktualisiere ich Hoppscotch auf eine neue Version?

Mit docker compose pull && docker compose up -d – der hoppscotch-migrate-Service führt dabei automatisch neue Datenbankmigrationen aus. Erstelle vorher unbedingt ein PostgreSQL-Backup (pg_dump), falls eine Migration schiefläuft.

Wie generiere ich einen sicheren DATA_ENCRYPTION_KEY?

Unter Linux/macOS: openssl rand -base64 32 | cut -c1-32. Unter Windows (PowerShell): -join ((65..90)+(97..122)+(48..57) | Get-Random -Count 32 | ForEach-Object {[char]$_}). Der Schlüssel muss exakt 32 Zeichen lang sein – weder mehr noch weniger, sonst verweigert das Backend den Start.

Unterstützt Hoppscotch ARM-Prozessoren (Apple Silicon, Raspberry Pi)?

Ja. Das offizielle AIO-Image wird für linux/amd64 und linux/arm64 bereitgestellt. Es läuft damit auf Apple-Silicon-Macs (M1/M2/M3), ARM-basierten NAS-Systemen und Raspberry Pi 4/5 mit 64-Bit-OS ohne Einschränkungen.

Fazit

Hoppscotch ist eine ausgereifte, datenschutzkonforme Alternative zu Postman und Insomnia, die sich dank des AIO-Docker-Images in unter 20 Minuten selbst hosten lässt. Der größte Stolperstein ist die .env-Konfiguration: Der DATA_ENCRYPTION_KEY muss exakt 32 Zeichen lang sein, Anführungszeichen in der .env führen zu Fehlern, und alle genutzten Origins müssen in WHITELISTED_ORIGINS stehen. Wer diese drei Punkte beachtet, hat innerhalb weniger Minuten eine voll funktionsfähige API-Testing-Plattform, die komplett unter eigener Kontrolle läuft. Für Teams, die Wert auf DSGVO-Konformität legen und keine Cloud-Abhängigkeit von US-Diensten möchten, ist Hoppscotch eine klare Empfehlung.

Weiterführende Anleitungen und Quellen

Docker und Docker Compose auf Linux installieren (Ubuntu/Debian) – die Grundlage für dieses Setup
Traefik als Docker-Reverse-Proxy mit automatischem HTTPS – für den Produktivbetrieb mit TLS
MySQL & PostgreSQL Backup automatisieren mit cron und rclone – PostgreSQL-Backup für Hoppscotch-Daten
Strapi mit Docker installieren – weiteres Open-Source-Tool für API-getriebene Entwicklung

Offizielle Quellen: Hoppscotch Dokumentation – Community Edition | Hoppscotch GitHub Repository | Docker Hub – Image-Tags