Wer APIs entwickelt oder testet, nutzt häufig Postman und legt damit Anfragen und Collections in der Cloud eines US-Anbieters ab. 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. Das Projekt erscheint monatlich in neuen Versionen und lässt sich mit dem fertigen All-in-One-Image (AIO, ein Container für Frontend, Backend und Admin-Dashboard) ohne eigenen Build selbst hosten.

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 inklusive PostgreSQL; 4 Kerne und 4 GB RAM nennt der Hersteller nur für den Eigenbau des Images, der hier entfällt.
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.
Für die Anmeldung: ein SMTP-Zugang (für Magic Links und Einladungen) oder OAuth-Zugangsdaten von GitHub, Google oder Microsoft.
Optional: Domain und TLS-Zertifikat für den HTTPS-Produktivbetrieb.

Schritt 1: Eckdaten und Projektordner anlegen

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

Parameter	Wert
Image	hoppscotch/hoppscotch:2026.9.0 (AIO)
Aktuelle Version	2026.9.0 (30. September 2026)
Imagegröße	~266 MB (amd64), ~263 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)

Legen Sie einen Projektordner an und wechseln Sie 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 liest seine Konfiguration aus Umgebungsvariablen. 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.

Erzeugen Sie 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]$_})

Erstellen Sie nun die .env-Datei mit den erzeugten Werten:

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

# ─── Verschlüsselung (EXAKT 32 Zeichen!) ──────────────────────────
DATA_ENCRYPTION_KEY=IHR_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 Magic Links und Einladungen (für EMAIL-Auth nötig)
# MAILER_SMTP_URL=smtps://user@domain.com:pass@smtp.domain.com
# MAILER_USE_CUSTOM_CONFIGS=false

Ersetzen Sie IHR_SICHERES_PASSWORT und IHR_32_ZEICHEN_SCHLUESSEL_HIER durch die zuvor erzeugten 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üfen Sie 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:2026.9.0
    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:2026.9.0
    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

Die Image-Version ist fest auf 2026.9.0 gesetzt, damit ein docker compose pull nicht unbemerkt eine neue Version einspielt. 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

Starten Sie alle Services im Hintergrund. Docker Compose lädt das Image beim ersten Start herunter (rund 266 MB):

cd /opt/hoppscotch
docker compose up -d

Beim ersten Start wird zuerst PostgreSQL als gesund gemeldet, dann führt der Migrationsdienst die Prisma-Migrationen aus, erst danach startet der Hoppscotch-Container. Das dauert ein bis drei Minuten.

Verifizieren: Prüfen Sie den Status aller Container:

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

Prüfen Sie, 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: Zuerst schließen Sie das Onboarding im Admin-Dashboard ab. Öffnen Sie dazu im Browser:

Admin-Dashboard: http://localhost:3100 – hier läuft das Onboarding, der erste angemeldete Nutzer wird Administrator
Hoppscotch-App: http://localhost:3000 – die eigentliche API-Testing-Oberfläche

Hoppscotch kennt keine Passwort-Anmeldung. Im Onboarding auf Port 3100 wählen Sie mindestens einen Anmeldeweg: E-Mail (Magic Link, setzt eine SMTP-Konfiguration im Reiter SMTP voraus) oder OAuth über GitHub, Google bzw. Microsoft mit den Zugangsdaten des jeweiligen Anbieters. Danach melden Sie sich an; der erste angemeldete Nutzer erhält Administratorrechte. Im Admin-Dashboard laden Sie anschließend weitere Nutzer ein, legen Workspaces an und verwalten die Instanz.

Ohne funktionierenden SMTP-Versand verschickt Hoppscotch keine Magic Links, eine Anmeldung per E-Mail ist dann nicht möglich. Tragen Sie die SMTP-Werte im Onboarding oder als Variablen in der .env-Datei ein und erstellen Sie den Container danach neu:

docker compose up -d --force-recreate hoppscotch

Verifizieren: Öffnen Sie http://localhost:3000 im Browser. Die Hoppscotch-Oberfläche erscheint, und Sie melden sich mit demselben Konto an wie im Admin-Dashboard. Senden Sie 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 Sie diesen Schritt automatisieren.

cd /opt/hoppscotch

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

# Neue Version in compose.yaml eintragen (beide Image-Zeilen), dann:
docker compose pull
docker compose up -d

Beim Update führt hoppscotch-migrate neue Datenbankmigrationen aus, bevor der Hauptcontainer startet. Verwenden Sie nie docker compose down -v: Das löscht das Volume mit allen Datenbankdaten.

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

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

Optional: Reverse Proxy und HTTPS

Für den Produktivbetrieb betreiben Sie Hoppscotch hinter einem Reverse Proxy mit TLS. Die Anleitung Traefik als Docker-Reverse-Proxy mit automatischem HTTPS zeigt den empfohlenen Weg. Passen Sie dafür die VITE_*-Variablen in der .env-Datei an Ihre 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

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. Im Subpath-Modus lauscht der AIO-Container intern auf Port 80, das Port-Mapping in der compose.yaml passen Sie entsprechend an.

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, kein Magic Link kommt an – SMTP ist nicht aktiviert oder falsch konfiguriert; ohne SMTP verschickt Hoppscotch keine Anmelde-E-Mails. SMTP im Admin-Dashboard (Reiter SMTP) oder in der .env einrichten bzw. einen OAuth-Anbieter aktivieren. Ist VITE_ALLOWED_AUTH_PROVIDERS 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) aus Docker Hub enthält Frontend, Backend und Admin-Dashboard. Sie benötigen 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. Ohne SMTP und ohne OAuth-Anbieter ist keine Anmeldung möglich, auch nicht für den ersten Administrator. Für lokale Tests genügt ein einfacher SMTP-Testserver wie Mailcatcher, den die Hoppscotch-Dokumentation nennt.

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

Das AIO-Image (hoppscotch/hoppscotch) kombiniert Frontend, Backend und Admin in einem Container und ist einfacher zu betreiben. 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. SSO/SAML und erweiterte Rollenrechte bietet nur die kostenpflichtige Enterprise Edition.

Wie aktualisiere ich Hoppscotch auf eine neue Version?

Neue Version in beiden Image-Zeilen der compose.yaml eintragen, dann docker compose pull && docker compose up -d – der Migrationsdienst läuft dabei automatisch. Vorher ein pg_dump-Backup erstellen (siehe Schritt 6).

Wie generiere ich einen sicheren DATA_ENCRYPTION_KEY?

Mit openssl rand -base64 32 | cut -c1-32 (Linux/macOS) oder dem PowerShell-Befehl aus Schritt 2. Der Schlüssel muss exakt 32 Zeichen lang sein, sonst startet das Backend nicht.

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, ARM-NAS-Systemen und Raspberry Pi 4/5 mit 64-Bit-System.

Fazit

Hoppscotch ersetzt Postman und Insomnia für viele Teams und lässt sich mit dem AIO-Image in etwa 20 Minuten selbst hosten. Die Stolpersteine liegen in der .env (Schlüssellänge, Anführungszeichen, WHITELISTED_ORIGINS) und in der Anmeldung, die SMTP oder OAuth voraussetzt. Dann läuft die API-Plattform vollständig unter Ihrer Kontrolle, ohne Abhängigkeit von einem US-Clouddienst.

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