DEV Community

Cover image for Anleitung: Selbst gehosteten Mock-Server im Intranet mit Apidog einrichten
Emre Demir
Emre Demir

Posted on • Originally published at apidog.com

Anleitung: Selbst gehosteten Mock-Server im Intranet mit Apidog einrichten

Einige Teams dürfen API-Daten nicht in die Cloud senden: Unternehmensfirewalls blockieren ausgehende Verbindungen, Compliance-Vorgaben verlangen interne Verarbeitung oder die Umgebung ist vollständig luftisoliert. In diesen Fällen ist ein gehosteter Mock-Endpunkt keine Option – auch dann nicht, wenn die Mock-Daten selbst synthetisch sind.

Apidog noch heute testen

Apidog löst dieses Szenario mit einem selbst gehosteten Runner. Statt Anfragen an den Cloud-Mock zu senden, betreiben Sie einen kleinen Dienst auf Ihrer eigenen Infrastruktur. Das API-Design und die Mock-Regeln bleiben im Apidog-Projekt, aber die Mock-Antworten werden aus Ihrem Netzwerk ausgeliefert.

Dieser Leitfaden zeigt:

  • wann ein selbst gehosteter Runner sinnvoll ist,
  • wie Sie ihn per Docker bereitstellen,
  • wie Sie die Umgebung Runner Mock aktivieren,
  • wie Sie HTTPS und persistente Daten konfigurieren,
  • warum der Runner nicht mit der Apidog CLI verwechselt werden darf.

Für den allgemeinen Hintergrund lesen Sie den Leitfaden zu selbst gehosteten API-Mock-Servern. Die OpenAPI Initiative beschreibt die Spezifikation, auf deren Grundlage viele API-Mocks erzeugt werden.

Was der selbst gehostete Runner ist

Der Apidog Self-hosted Runner ist ein Dienst, den Sie auf einem eigenen Server betreiben. In der Oberfläche heißt er General Runner.

Er kann:

  1. geplante automatisierte Tests ausführen,
  2. API-Dokumentationen importieren,
  3. Mock-Antworten bereitstellen.

Für selbst gehostetes Mocking ist der dritte Punkt entscheidend.

Apidog General Runner

Nach der Bereitstellung konfigurieren Sie einen Server Host. Apidog erzeugt daraufhin automatisch die Umgebung Runner Mock in Ihrem Projekt.

Der Ablauf ist dann:

Apidog-Client → Runner Mock → Ihr Docker-Host → Mock-Antwort
Enter fullscreen mode Exit fullscreen mode

Das Mock-Design bleibt im Projekt. Nur die Auslieferung der Antworten findet auf Ihrer Infrastruktur statt.

Wann Sie den Runner statt des Cloud-Mocks verwenden sollten

Der Apidog Cloud-Mock ist einfacher, wenn Ihr Team externe Dienste erreichen darf. Sie müssen keinen Server verwalten.

Setzen Sie den selbst gehosteten Runner ein, wenn mindestens einer dieser Punkte zutrifft:

  • Ausgehender Traffic zu externen Hosts ist blockiert oder wird streng geprüft.
  • Compliance-Regeln verlangen, dass Request- und Response-Daten intern bleiben.
  • Ihre Umgebung ist air-gapped und kann keine Cloud-Endpunkte erreichen.
  • Sie möchten Latenzen innerhalb Ihres LANs statt über das öffentliche Internet messen.

Falls keine dieser Bedingungen gilt, bedeutet ein zusätzlicher Docker-Host meist nur mehr Betriebsaufwand.

Sie benötigen Team- oder Projekt-Admin-Rechte, um einen Runner zu verwalten. Die Dokumentation nennt keine explizite kostenlose oder kostenpflichtige Freigabe für General Runner oder selbst gehostete Mocks; daher sollten Sie die Berechtigungen und verfügbaren Optionen direkt in Ihrem Team prüfen.

Voraussetzungen

Der Runner läuft als Docker-Container. Prüfen Sie zuerst Ihre Docker-Version:

docker --version
Enter fullscreen mode Exit fullscreen mode

Die Dokumentation verlangt mindestens Docker 20.10.0 und empfiehlt 20.10.13 oder neuer.

Sie benötigen außerdem:

  • einen Linux-, macOS- oder Windows-Host mit Docker,
  • eine stabile interne IP-Adresse oder einen Hostnamen,
  • Netzwerkzugriff zwischen Ihren Apidog-Clients und dem Runner,
  • Admin-Rechte im Apidog-Team.

General Runner bereitstellen

1. Docker-Befehl in Apidog erzeugen

Öffnen Sie in Apidog:

  1. Home
  2. Team auswählen
  3. Ressourcen
  4. General Runner bereitstellen

Im Dialog konfigurieren Sie folgende Werte:

  • Server-Betriebssystem: Linux, macOS oder Windows.
  • Docker-Image:
    • General: enthält Node.js 18, Java 21, Python 3 und PHP 8.
    • Slim: enthält nur Node.js 18.
    • Custom: für ein eigenes Dockerfile mit weiteren Laufzeiten.
  • Exponierter Port: zum Beispiel -p 80:4524.
  • Datenverzeichnis: per -v, damit Daten Container-Neustarts überdauern.

Apidog generiert anschließend einen Docker-Befehl inklusive Token.

Kopieren Sie den Befehl sofort. Das Token wird aus Sicherheitsgründen nur einmal angezeigt. Wenn Sie es verlieren, erzeugen Sie einen neuen Befehl.

2. Container starten

Führen Sie den generierten Befehl auf Ihrem Server aus. Er sieht ungefähr so aus:

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  apidog/runner:latest \
  --token <YOUR_GENERATED_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Prüfen Sie anschließend, ob der Container läuft:

docker ps
Enter fullscreen mode Exit fullscreen mode

Erwartetes Ergebnis: Der Runner-Container wird angezeigt und enthält die konfigurierte Port-Zuordnung, etwa 0.0.0.0:80->4524/tcp.

Für eine schnelle Diagnose können Sie zusätzlich die Container-Logs ansehen:

docker logs apidog-runner
Enter fullscreen mode Exit fullscreen mode

3. Registrierung in Apidog bestätigen

Gehen Sie zurück zu:

Team-Ressourcen → General Runner
Enter fullscreen mode Exit fullscreen mode

Klicken Sie auf Aktualisieren. Der Runner sollte als bereitgestellt mit dem Status Gestartet erscheinen.

Die wichtigsten Statuswerte:

Status Bedeutung Nächster Schritt
Gestartet Runner ist aktiv und verarbeitet Aufgaben. Keine Aktion nötig.
Angehalten Runner wurde in Apidog manuell pausiert. Bei Bedarf wieder starten.
Offline Runner kann Apidog nicht erreichen. Container, Token und Netzwerkpfad prüfen.

Wenn der Runner nicht sofort erscheint, warten Sie kurz und klicken Sie erneut auf Aktualisieren.

Runner Mock aktivieren

Die Container-Bereitstellung allein leitet noch keinen Mock-Traffic um. Dafür setzen Sie den Server Host.

Öffnen Sie den General Runner in den Team-Ressourcen und tragen Sie die Adresse ein, über die der Runner erreichbar ist.

Beispiele:

http://127.0.0.1:80
Enter fullscreen mode Exit fullscreen mode

Für einen lokalen Test.

http://runner.internal.example.com:80
Enter fullscreen mode Exit fullscreen mode

Für einen gemeinsam genutzten Intranet-Host.

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Wenn TLS über einen Reverse Proxy terminiert wird.

Sobald der Server Host gespeichert ist:

  1. Öffnen Sie Ihr Apidog-Projekt.
  2. Wechseln Sie in die Umgebungsverwaltung.
  3. Prüfen Sie, ob Runner Mock in der Umgebungsliste erscheint.

Diese Umgebung wird automatisch erzeugt. Sie müssen sie nicht manuell anlegen.

Anfrage über den selbst gehosteten Mock senden

Angenommen, Ihr API-Projekt enthält diesen Endpunkt:

GET /orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

So testen Sie ihn gegen den Runner:

  1. Öffnen Sie den Endpunkt in Apidog.
  2. Wählen Sie im Umgebungs-Dropdown Runner Mock.
  3. Senden Sie die Anfrage.

Alternativ können Sie den Runner direkt ansprechen:

curl http://runner.internal.example.com:80/orders/10583
Enter fullscreen mode Exit fullscreen mode

Bei einem passenden Order-Schema kann die Antwort beispielsweise so aussehen:

{
  "orderId": 10583,
  "customerEmail": "amelia.turner@example.com",
  "status": "shipped",
  "total": 148.5,
  "currency": "USD",
  "createdAt": "2026-07-14T09:32:11Z"
}
Enter fullscreen mode Exit fullscreen mode

Die Antwort wird aus dem Endpunktschema erzeugt und vom Runner innerhalb Ihres Netzwerks bereitgestellt.

Für kontrollierte Antworten hinterlegen Sie am Endpunkt Mock-Erwartungen. Der selbst gehostete Runner verwendet dafür denselben Mock-Mechanismus wie der Cloud-Mock. Der Unterschied liegt ausschließlich im ausliefernden Host.

Weitere Details zur schema-basierten Generierung finden Sie im Artikel zur automatischen Generierung realistischer Mock-Daten mit Smart Mock. Die grundlegenden Konzepte von API-Mocking bleiben unverändert.

HTTPS, Daten-Mounts und Betrieb

HTTPS mit Reverse Proxy konfigurieren

Der Runner verwaltet keine TLS-Zertifikate und stellt HTTPS nicht eigenständig bereit. Wenn Sie https:// benötigen, setzen Sie einen Reverse Proxy vor den Runner, beispielsweise Nginx.

Beispiel:

server {
    listen 443 ssl;
    server_name runner.example.com;

    ssl_certificate     /etc/ssl/certs/runner.example.com.pem;
    ssl_certificate_key /etc/ssl/private/runner.example.com.key;

    location / {
        proxy_pass http://127.0.0.1:4524;
        proxy_set_header Host $host;
    }
}
Enter fullscreen mode Exit fullscreen mode

Setzen Sie danach in Apidog diesen Server Host:

https://runner.example.com:443
Enter fullscreen mode Exit fullscreen mode

Ohne Reverse Proxy verwenden Sie HTTP:

http://runner.internal.example.com:80
Enter fullscreen mode Exit fullscreen mode

Der MDN-Leitfaden zu HTTPS bietet eine gute Einführung in TLS und HTTPS.

Dateien an die erwarteten Container-Pfade mounten

Falls Ihre Tests oder Mocks zusätzliche Dateien verwenden, mounten Sie diese in die vom Runner erwarteten Pfade:

Zweck Container-Pfad
Externe Programme /app/external-programs/
Datenbank-Konfiguration /app/database/database-connections.json
SSL-Client-Zertifikate /app/ssl/ssl-client-cert-list.json

Beispiel für einen zusätzlichen Mount:

docker run -d \
  --name apidog-runner \
  -p 80:4524 \
  -v /opt/apidog-runner/data:/app/data \
  -v /opt/apidog-runner/external-programs:/app/external-programs \
  apidog/runner:latest \
  --token <YOUR_GENERATED_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Verwenden Sie Host-Mounts, damit diese Dateien bei Container-Neustarts erhalten bleiben.

Upgrade und erneute Bereitstellung

Wenn eine neue Runner-Version verfügbar ist, können Sie ein Upgrade ausführen oder unter Weitere Aktionen die Option Neu bereitstellen wählen.

Dabei wird der laufende Container kurz gestoppt und neu gestartet. Bestehende geplante Aufgaben im Apidog-Client bleiben laut Dokumentation erhalten. Planen Sie dennoch ein kurzes Wartungsfenster ein, da der Mock-Service während des Container-Neustarts nicht erreichbar ist.

Runner und Apidog CLI richtig einordnen

Der Runner und die Apidog CLI sind unterschiedliche Werkzeuge:

Werkzeug Aufgabe
General Runner Hostet Mocks und führt geplante Aufgaben aus.
Apidog CLI Führt Testszenarien in CI/CD aus und verwaltet Mock-Erwartungen als Daten.

Die CLI startet keinen Mock-Server. Es gibt keinen Befehl wie:

apidog run mock
Enter fullscreen mode Exit fullscreen mode

oder:

apidog mock serve
Enter fullscreen mode Exit fullscreen mode

apidog run führt Testszenarien, Szenario-Ordner und Testsuiten aus. Die mock-Befehlsgruppe verwaltet Mock-Erwartungen, hostet aber keinen HTTP-Endpunkt.

Ein sinnvoller Workflow sieht so aus:

  1. API-Endpunkte und Schemas im Apidog-Projekt pflegen.
  2. Mit dem Runner Frontend-Teams einen internen Mock-Endpunkt bereitstellen.
  3. Das reale Backend mit der CLI gegen denselben API-Vertrag testen.
  4. Tests in CI/CD bei jedem Push ausführen.

Beispiel für einen CLI-Testlauf:

apidog run -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

Der Befehl führt Tests gegen Ihr Live-Backend aus und erzeugt HTML- sowie CLI-Reports.

Installieren Sie die CLI mit:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Voraussetzung ist Node.js ab Version 16. Details zu Login und Tokens finden Sie im Installationsleitfaden für Apidog CLI. Für die Pipeline-Integration nutzen Sie den Apidog CLI CI/CD-Leitfaden.

Warum die CLI Mock-Definitionen verwaltet, aber keine Mock-Server hostet, erklärt der Beitrag zum Mocking von APIs über die CLI.

FAQ

Benötige ich den selbst gehosteten Runner, wenn mein Team Internetzugriff hat?

Wahrscheinlich nicht. Der Cloud-Mock benötigt keine eigene Infrastruktur und ist einfacher zu betreiben. Verwenden Sie den Runner, wenn Compliance, Firewalls oder eine air-gapped Umgebung externe Mock-Endpunkte ausschließen.

Zum Vergleich eignet sich der Leitfaden zu Apidog Cloud-Mock.

Kann die Apidog CLI einen selbst gehosteten Mock-Server starten?

Nein. Die CLI führt Tests aus und verwaltet Mock-Erwartungen als Daten. Der General Runner oder der Cloud-Mock stellt den eigentlichen Mock-Traffic bereit.

Unterstützt der Runner HTTPS ohne zusätzliche Komponenten?

Nein. Der Runner stellt keine Zertifikate bereit und terminiert TLS nicht selbst. Platzieren Sie einen Reverse Proxy wie Nginx davor und konfigurieren Sie anschließend die HTTPS-Adresse des Proxys als Server Host.

Warum wird mein Runner nach dem Start nicht angezeigt?

Prüfen Sie zuerst den Container:

docker ps
Enter fullscreen mode Exit fullscreen mode

Öffnen Sie dann in Apidog Team-Ressourcen → General Runner und klicken Sie auf Aktualisieren.

Wenn der Status weiterhin Offline ist, prüfen Sie:

  • ob der Container läuft,
  • ob das Token korrekt ist,
  • ob der Host den Apidog-Dienst erreichen kann,
  • ob Firewall- oder Proxy-Regeln die Verbindung blockieren.

Können mehrere Teams einen Runner gemeinsam nutzen?

Ein Runner registriert sich beim Team, in dem er bereitgestellt wurde. Die Umgebung Runner Mock wird pro Projekt angezeigt. Für verteilte Teams hilft der Leitfaden zum Teilen von Mock-Umgebungen in globalen Teams, die Anzahl und Platzierung Ihrer Runner zu planen.

Zusammenfassung

Mit dem General Runner stellen Sie Apidog-Mocks auf Ihrer eigenen Infrastruktur bereit:

  1. Docker auf einem internen Host installieren.
  2. General Runner in Apidog konfigurieren.
  3. Generierten Docker-Befehl ausführen.
  4. Container und Runner-Status prüfen.
  5. Server Host festlegen.
  6. Die automatisch erzeugte Umgebung Runner Mock auswählen.

Damit bleiben Request- und Response-Daten in Ihrem Netzwerk, während API-Schemas und Mock-Regeln weiterhin zentral im Apidog-Projekt verwaltet werden.

Wenn Ihre Umgebung Cloud-Mocks erlaubt, ist der Cloud-Mock meist der schnellere Weg. Wenn Compliance, Firewall-Regeln oder Air-Gapping externe Endpunkte verhindern, ist der selbst gehostete Runner die passende Option.

Apidog herunterladen, Runner bereitstellen und die erste interne Mock-Antwort ausliefern.

Top comments (0)