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

Einige Teams können ihren Datenverkehr nicht in die Cloud senden. Vielleicht befinden Sie sich hinter einer Unternehmensfirewall, die ausgehende Anrufe an Drittanbieterdienste blockiert. Vielleicht besagt eine Compliance-Regel, dass Anforderungs- und Antwortdaten auf von Ihnen kontrollierten Maschinen verbleiben müssen. Vielleicht ist die gesamte Umgebung luftisoliert (air-gapped) und nichts verlässt das Intranet überhaupt. In all diesen Fällen ist eine gehostete Mock-URL auf der Infrastruktur eines anderen keine Option, selbst wenn die Mock-Daten selbst gefälscht sind.

Apidog löst dies mit einem selbst gehosteten Runner. Anstatt dass Ihre Anfragen an Apidogs Cloud-Mock gesendet werden, stellen Sie ein kleines Programm auf einem Server bereit, der Ihnen gehört, und dieses Programm liefert die Mock-Antworten aus Ihrem eigenen Netzwerk zurück. Das Design bleibt wie immer in Ihrem Apidog-Projekt; nur die Bereitstellung wird auf Ihre Hardware verlegt. Dieser Leitfaden erklärt, was der Runner ist, wann Sie ihn dem Cloud-Mock vorziehen sollten, wie Sie ihn anhand der Dokumentation einrichten und eine Unterscheidung, die oft Verwirrung stiftet: Der Runner ist nicht die CLI. Wenn Sie ein umfassenderes Bild davon wünschen, warum Teams Mocks auf ihren eigenen Rechnern ausführen, behandelt der Leitfaden zu selbst gehosteten API-Mock-Servern den allgemeinen Fall, und die OpenAPI Initiative erklärt die Spezifikation, aus der diese Mocks generiert werden. Möchten Sie mitmachen? Laden Sie Apidog zuerst herunter.

Was der selbst gehostete Runner ist

Der Apidog Self-hosted Runner ist ein automatisiertes Programm, das Sie auf einem eigenständigen Server hosten. Er wird offiziell als General Runner bezeichnet und hat drei Aufgaben: Er führt geplante automatisierte Tests aus, importiert API-Dokumente und gibt Mock-Antworten zurück. Die dritte Aufgabe ist diejenige, um die es in diesem Artikel geht.

Hier ist die Kernidee. Sobald Sie einen General Runner bereitstellen und seinen Server Host einstellen, erscheint automatisch eine neue Umgebung namens Runner Mock in Ihrem Projekt. Jede Anfrage, die Sie über diese Umgebung senden, erhält ihre Mock-Antwort von Ihrem selbst gehosteten Runner anstelle von Apidogs Cloud-Mock. Gleiches Mock-Design, gleiche generierte Daten, eine andere Maschine übernimmt die Bereitstellung. Ihr Datenverkehr verlässt niemals Ihr Netzwerk.

Dies ist die selbst gehostete Alternative zum Cloud-Mock. Wenn Ihr Team das Internet erreichen kann und keine Regel dagegen spricht, ist der Apidog Cloud-Mock einfacher, da nichts bereitgestellt werden muss. Greifen Sie zum Runner, wenn einer der folgenden Punkte zutrifft:

• Ausgehender Datenverkehr zu externen Hosts ist blockiert oder strengstens überprüft.
• Eine Compliance-Richtlinie erfordert, dass Anforderungsdaten auf der internen Infrastruktur verbleiben.
• Die Umgebung ist luftisoliert (air-gapped) und kann überhaupt keinen Cloud-Endpunkt erreichen.
• Sie möchten die Mock-Latenz in Ihrem eigenen LAN messen und nicht über das öffentliche Internet.

Wenn keiner dieser Punkte zutrifft, ist der zusätzliche Docker-Host ein unnötiger Mehraufwand. Seien Sie ehrlich zu sich selbst, in welchem Lager Sie sich befinden, bevor Sie einen Server bereitstellen.

Ein Hinweis zu Plänen und Berechtigungen. Die Apidog-Dokumentation gibt keine explizite Unterscheidung zwischen kostenlos und kostenpflichtig für den General Runner oder für selbst gehostete Mocks an, und sie listet auch keine Preisinformationen dafür auf, daher wird dieser Leitfaden keine erfinden. Die Einrichtung erfordert jedoch Team- oder Projekt-Admin-Berechtigungen, da die Bereitstellung eines Runners innerhalb der Teamressourcen erfolgt und nur Administratoren diese Einstellungen öffnen können. Wenn Sie das Ressourcenpanel nicht sehen können, ist das der Grund.

Was Sie vor dem Start benötigen

Der Runner wird als Docker-Container geliefert, daher muss auf dem Host-Server Docker installiert sein. Die Dokumentation fordert eine Mindestversion von 20.10.0 und empfiehlt 20.10.13 oder neuer. Überprüfen Sie, was Sie haben:

docker --version

Sie benötigen außerdem einen Ort, an dem Sie es ausführen können: einen Linux-, macOS- oder Windows-Rechner, den sowohl die Apidog-Clients Ihres Teams als auch der Apidog-Dienst erreichen können. In einem Intranet bedeutet das normalerweise einen internen Server mit einer stabilen IP oder einem Hostnamen. Das ist die gesamte Voraussetzungsliste: Docker, ein Host und Administratorrechte im Team. Alles andere konfigurieren Sie in Apidog selbst.

Den General Runner bereitstellen

Der Bereitstellungsbefehl wird für Sie innerhalb von Apidog generiert und enthält ein Token, sodass Sie ihn nicht manuell schreiben müssen. So funktioniert der Ablauf.

Den Befehl generieren

Öffnen Sie Apidog Home, wählen Sie Ihr Team aus, klicken Sie dann in der rechten Seitenleiste auf Ressourcen und wählen Sie General Runner bereitstellen. Es erscheint ein Popup, in dem Sie einige Einstellungen vornehmen können:

• Server-Betriebssystem: Linux, macOS oder Windows, damit der generierte Befehl zu Ihrem Host passt.
• Docker-Image: wählen Sie General, Slim oder Custom. General wird mit vorinstalliertem Node.js 18, Java 21, Python 3 und PHP 8 geliefert. Slim enthält nur Node.js 18, für ein kleineres Image. Mit Custom können Sie Ihr eigenes Dockerfile bereitstellen, wenn Sie zusätzliche Laufzeiten für Testskripte benötigen.
• Exponierter Port: eingestellt mit dem -p-Parameter, zum Beispiel -p 80:4524, der den Host-Port 80 auf den internen Port des Runners abbildet.
• Gemountetes Datenverzeichnis: eingestellt mit dem -v-Parameter, damit Runner-Daten auf dem Host über Neustarts hinweg erhalten bleiben.

Wenn Sie fertig sind, kopieren Sie den generierten Befehl. Das ist wichtig: Der Befehl wird aus Gründen der Datensicherheit nur einmal angezeigt, da er Ihr Token enthält. Wenn Sie ihn verlieren, generieren Sie einen neuen, anstatt den alten wiederherzustellen. Erfassen Sie ihn sofort.

Auf dem Server ausführen

Fügen Sie den Befehl in das Terminal Ihres Servers ein. Die Installation startet von selbst und lädt das Image herunter. Ein fertiger Befehl sieht ungefähr so aus (Ihrer wird abweichen und das tatsächliche Token enthalten):

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

Bestätigen Sie, dass der Container läuft:

docker ps

Sie sollten den Runner-Container mit seiner Port-Zuordnung aufgelistet sehen. Ein Docker-Client wie Docker Desktop zeigt dasselbe an, wenn Sie lieber eine Benutzeroberfläche verwenden möchten.

Registrierung bestätigen

Kehren Sie zu Apidog zurück, gehen Sie zu Team-Ressourcen und öffnen Sie General Runner. Klicken Sie auf die Schaltfläche Aktualisieren. Der Runner sollte nun als bereitgestellt mit dem Status „Gestartet“ angezeigt werden. Wenn er anfangs nicht erscheint, ist die Aktualisierungs-Schaltfläche Ihre Lösung; warten Sie einen Moment und klicken Sie erneut.

Der Runner-Status hat drei wissenswerte Zustände:

• Gestartet: aktiviert, kommuniziert mit Apidog, bearbeitet Aufgaben. Dies ist der gewünschte Zustand.
• Angehalten: jemand hat ihn manuell in Apidog angehalten. Er bleibt bereitgestellt, verarbeitet aber keine Aufgaben.
• Offline: er hat die Verbindung zu Apidog verloren, sodass er nichts verarbeiten kann. Überprüfen Sie den Container und den Netzwerkpfad.

Runner Mock aktivieren

Die Bereitstellung des Runners gibt Ihnen den Agenten. Ein weiterer Schritt leitet Ihren Mock-Traffic darauf.

Öffnen Sie in den Team-Ressourcen den General Runner und suchen Sie das Feld Server Host. Geben Sie die Adresse ein, unter der Ihr Runner erreichbar ist. Bei einer einfachen HTTP-Einrichtung sind dies der Host und der Port, den Sie exponiert haben, wie http://127.0.0.1:80 für einen lokalen Test oder http://runner.internal.example.com:80 für einen gemeinsam genutzten Intranet-Host. Hinter einem TLS-terminierenden Proxy sieht es aus wie https://runner.example.com:443. Mehr zu HTTPS in Kürze.

Sobald der Server Host eingestellt ist, richtet Apidog die Runner-Mock-Umgebung für Ihr Projekt automatisch ein. Überprüfen Sie dies: Öffnen Sie das Projekt, gehen Sie zur Umgebungsverwaltung und bestätigen Sie, dass Runner Mock jetzt in der Umgebungsliste angezeigt wird. Sie haben es nicht manuell erstellt; die Einstellung des Server Hosts hat es erscheinen lassen.

Eine Anfrage über den selbst gehosteten Mock senden

Nutzen Sie es jetzt. Angenommen, Sie haben einen Endpunkt GET /orders/{orderId} in einem Projekt für eine interne Auftragsverwaltungs-API. Öffnen Sie diesen Endpunkt und wählen Sie dann im Umgebungs-Dropdown oben Runner Mock anstelle der Cloud-Umgebung aus. Senden Sie die Anfrage.

Die Antwort kommt von Ihrem Runner zurück. Da Apidog Mock-Daten aus Ihrem Schema generiert, liefert ein gut definiertes Order-Schema realistische Werte anstelle von leeren Platzhaltern:

curl http://runner.internal.example.com:80/orders/10583

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

Dieses JSON hat das öffentliche Internet nie berührt. Der Runner hat es aus dem Schema Ihres Endpunkts erstellt und es innerhalb Ihres Netzwerks bereitgestellt. Eine feldbezogene Generierung wie der customerEmail-Wert oben ergibt sich aus Apidogs Lesevorgang der Schematypen und Feldnamen, derselbe Mechanismus, der im Begleitartikel zur automatischen Generierung realistischer Mock-Daten mit Smart Mock behandelt wird. Wenn Sie genau steuern möchten, was eine bestimmte Anfrage zurückgibt, fügen Sie dem Endpunkt eine Mock-Erwartung hinzu, und der Runner erfüllt diese Erwartung auf die gleiche Weise wie der Cloud-Mock. Die Mechanismen zur Erstellung guter Mock-Antworten sind dieselben, unabhängig davon, ob der Server von Apidog oder von Ihnen stammt; nur der Host ändert sich. Die allgemeinen Konzepte hinter dem API-Mocking bleiben unverändert.

HTTPS, Daten-Mounts und andere praxisrelevante Details

Ein Testlauf auf http://127.0.0.1 ist einfach. Eine gemeinsame Intranet-Bereitstellung birgt einige Tücken, die man kennen sollte, bevor man sie einem Team zur Verfügung stellt.

HTTPS benötigt einen Reverse Proxy

Der Runner verfügt über keine integrierte HTTPS-Zertifikatsunterstützung und übernimmt keine automatische Zertifikatsbereitstellung. Er wird kein TLS-Zertifikat für Sie abrufen oder verwalten. Wenn Sie https:// benötigen, beenden Sie TLS an einem Reverse Proxy vor dem Runner, zum Beispiel Nginx mit Ihrem Zertifikat, und richten Sie dann den Server Host auf die HTTPS-URL des Proxys aus. Ohne Proxy bleiben Sie bei http://host:port. Stellen Sie den Server Host nicht auf https:// ein und erwarten Sie nicht, dass der Runner TLS direkt beantwortet; das kann er nicht.

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;
    }
}

Dann wird Server Host zu https://runner.example.com:443. Der MDN-Leitfaden zu HTTPS ist eine gute Auffrischung, falls TLS-Terminierung für Ihr Team neu ist.

Dateimounts sind pfadspezifisch

Wenn Ihre Mocks oder Tests zusätzliche Dateien benötigen, erwartet der Runner diese an festen Pfaden innerhalb des Containers. Mounten Sie sie daher dort:

• Externe Programme gehören nach /app/external-programs/.
• Datenbankverbindungs-Konfiguration gehört nach /app/database/database-connections.json.
• SSL-Client-Zertifikate gehören nach /app/ssl/ssl-client-cert-list.json.

Verbinden Sie diese über Ihre -v-Mounts, damit sie Neustarts überdauern.

Verhalten bei erneuter Bereitstellung und Upgrade

Wenn eine neue Runner-Version ausgeliefert wird, sehen Sie eine Upgrade-Option, und unter Weitere Aktionen können Sie „Neu bereitstellen“ wählen. Beides stoppt den laufenden Container, während der neue hochfährt. Der beruhigende Teil: Bestehende geplante Aufgaben im Apidog-Client sind von einer erneuten Bereitstellung oder einem Upgrade unberührt, sodass Sie den Live-Dienst nur für den Moment des Container-Neustarts unterbrechen und keine Konfiguration verlieren.

Den Workflow mit der Apidog CLI automatisieren

Hier ist die Unterscheidung, die Verwirrung erspart: Der Runner ist ein langlebiger Agent, der Mocks bereitstellen und geplante Aufgaben ausführen kann, während die Apidog CLI ein einmaliger Test-Runner für CI ist. Es sind unterschiedliche Tools. Die CLI kann keinen Mock-Server bereitstellen, starten oder hosten. Es gibt kein apidog run mock und kein apidog mock serve. Der apidog run-Befehl der CLI führt Testszenarien, Testszenarien-Ordner und Testsuiten aus, und die mock-Befehlsgruppe führt lediglich CRUD-Operationen an Mock-Erwartungen als Daten durch. Das Bereitstellen von Mocks ist die Aufgabe des Runners, niemals die der CLI.

Die beiden passen also wie folgt zusammen. Die CLI und KI-Codierungsagenten wie Cursor, Claude Code und Codex können die Endpunkte und Schemata in Ihrem Projekt erstellen und aktualisieren, wodurch Ihre Mock-Ausgabe während der Entwicklung der Spezifikation genau bleibt. Sobald der selbst gehostete Mock die Frontend-Arbeiten freigegeben hat, laufen die Testszenarien desselben Projekts in CI mit einem einzigen Befehl ohne grafische Oberfläche ab und validieren das reale Backend gegen genau den Vertrag, den der Mock beschrieben hat:

apidog run -t <scenario_id> -e <env_id> -r html,cli

Dieser eine Befehl führt Ihre Szenarien gegen das Live-Backend aus und schreibt einen HTML- und CLI-Bericht. Die Installation erfolgt über npm install -g apidog-cli auf Node.js v16 oder höher; der Installationsleitfaden für Apidog CLI behandelt apidog login und die Token-Einrichtung. Um diesen Testlauf bei jedem Push auszuführen, integrieren Sie ihn mit dem Apidog CLI CI/CD-Leitfaden in Ihre Pipeline. Der Artikel über das Mocking von APIs über die CLI erklärt genau, warum das Terminal Mock-Definitionen verwaltet, aber nicht hostet.

FAQ

Benötige ich den selbst gehosteten Runner, wenn mein Team das Internet erreichen kann?

Wahrscheinlich nicht. Der Cloud-Mock benötigt keine Bereitstellung und ist der einfachere Weg. Wählen Sie den Runner, wenn ausgehender Datenverkehr blockiert oder überprüft wird, eine Compliance-Regel Daten auf der internen Infrastruktur hält oder die Umgebung luftisoliert (air-gapped) ist. Wenn Sie zuerst den gehosteten Ansatz mit dem verwalteten vergleichen, ist die exemplarische Darstellung von Apidog Cloud-Mock die natürliche Ergänzung zu diesem Leitfaden.

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

Nein. Die CLI führt Tests mit apidog run aus und verwaltet Mock-Erwartungen als Daten mit ihrer mock-Befehlsgruppe. Das Bereitstellen von Mock-Traffic wird vom General Runner oder vom Cloud-Mock übernommen, niemals von der CLI. Wenn Sie gehofft haben, einen Terminalbefehl einzugeben und einen laufenden Mock auf einem Port zu erhalten, ist das die Aufgabe des Runners, der wie oben beschrieben über die GUI eingerichtet wird.

Unterstützt der Runner HTTPS eigenständig?

Er liefert keine Zertifikate mit und stellt sie auch nicht automatisch bereit. Platzieren Sie einen Reverse Proxy wie Nginx davor, um TLS zu terminieren, und richten Sie dann den Server Host auf die https://-URL des Proxys aus. Ohne Proxy verwenden Sie http://host:port.

Warum wird mein Runner nicht angezeigt, nachdem ich den Befehl ausgeführt habe?

Öffnen Sie Team-Ressourcen, gehen Sie zu General Runner und klicken Sie auf die Schaltfläche Aktualisieren. Die Registrierung kann einen Moment verzögert sein. Wenn er immer noch nicht angezeigt wird, vergewissern Sie sich mit docker ps, dass der Container läuft und dass der Host von Apidog aus erreichbar ist. Ein Status von „Offline“ bedeutet, dass die Verbindung unterbrochen wurde; „Gestartet“ ist der gewünschte Zustand.

Können mehrere Teams einen Runner für globales Mock-Serving nutzen?

Ein Runner registriert sich bei dem Team, in dem Sie ihn bereitgestellt haben, und seine Runner-Mock-Umgebung wird pro Projekt angezeigt. Wenn Sie verteilte Teams betreiben, die Mock-Umgebungen gemeinsam nutzen, helfen Ihnen die Muster im Leitfaden zum Teilen von Mock-Umgebungen in globalen Teams bei der Entscheidung, wie viele Runner Sie wo bereitstellen sollten.

Zusammenfassung

Selbst gehostetes Mocking mit dem General Runner hält Ihre Anforderungsdaten auf der von Ihnen kontrollierten Infrastruktur, während Ihr Mock-Design genau dort bleibt, wo es immer war, in Ihrem Apidog-Projekt. Sie stellen einen Docker-Container bereit, legen den Server Host fest, und die Runner-Mock-Umgebung erledigt den Rest. Greifen Sie darauf zurück, wenn die Cloud tabu ist, und bleiben Sie beim Cloud-Mock, wenn dies nicht der Fall ist. Bereit, Mocks in Ihrem eigenen Netzwerk auszuführen? Laden Sie Apidog herunter, stellen Sie einen Runner bereit und liefern Sie Ihre erste Runner-Mock-Antwort, ohne dass ein einziges Paket Ihr Intranet verlässt.