DEV Community

Cover image for Apidogで社内ネットワークにセルフホスト型モックサーバーを構築する方法
Akira
Akira

Posted on • Originally published at apidog.com

Apidogで社内ネットワークにセルフホスト型モックサーバーを構築する方法

一部のチームはトラフィックをクラウドへ送信できません。企業ファイアウォールがサードパーティサービスへのアウトバウンド通信をブロックしている、コンプライアンス要件によりリクエスト・レスポンスデータを管理下のマシンに保持する必要がある、あるいは環境が完全にエアギャップされている、といったケースです。このような環境では、モックデータがダミーであっても、外部インフラストラクチャでホストされたモックURLは利用できません。

今すぐApidogを試す

Apidogのセルフホスト型ランナーを使うと、モックレスポンスを自分のネットワーク内から返せます。API設計とモック定義はApidogプロジェクトで管理し、実際のサービングだけを自社サーバー上のランナーで実行します。

このガイドでは、次を実装手順として説明します。

  • セルフホスト型ランナーを使うべきケース
  • DockerでGeneral Runnerをデプロイする方法
  • Runner Mock環境を有効化する方法
  • HTTPS、データマウント、再デプロイ時の注意点
  • General RunnerとApidog CLIの役割の違い

全体的なユースケースは、セルフホスト型APIモックサーバーに関するガイドも参照してください。モックの基礎となるAPI仕様については、OpenAPI Initiativeで確認できます。

セルフホスト型ランナーとは

Apidogセルフホスト型ランナーは、スタンドアロンサーバーで実行する自動化プログラムです。正式名称はGeneral Runnerで、主に次の役割を持ちます。

  1. スケジュールされた自動テストの実行
  2. APIドキュメントのインポート
  3. モックレスポンスの提供

本記事では、3番目のモック提供に焦点を当てます。

General Runnerの設定画面

General RunnerをデプロイしてServer Hostを設定すると、Apidogプロジェクトには自動的にRunner Mock環境が追加されます。

この環境を選択して送信したリクエストは、Apidogのクラウドモックではなく、セルフホスト型ランナーからレスポンスを受け取ります。モック定義と生成ロジックは同じで、レスポンスを提供するホストだけが変わります。

ランナーを選ぶケース

インターネット接続に制約がなければ、デプロイ不要のApidogクラウドモックの方がシンプルです。

次の条件に当てはまる場合は、General Runnerを使用してください。

  • 外部ホストへのアウトバウンド通信がブロックまたは厳格に監査されている
  • コンプライアンスポリシーにより、リクエストデータを内部インフラに保持する必要がある
  • 環境がエアギャップされている
  • パブリックインターネットではなくLAN内でモックのレイテンシを測定したい

これらに該当しない場合、Dockerホストの運用は追加オーバーヘッドになります。

General Runnerの設定には、チームまたはプロジェクトの管理者権限が必要です。リソースパネルが表示されない場合は、権限を確認してください。

始める前に必要なもの

General RunnerはDockerコンテナとして実行します。ホストにはDocker 20.10.0以上が必要で、20.10.13以上が推奨されています。

docker --version
Enter fullscreen mode Exit fullscreen mode

さらに、次の条件を満たすホストを用意します。

  • Linux、macOS、またはWindows
  • Apidogクライアントからアクセスできる
  • Apidogサービスと通信できる
  • 安定した内部IPアドレスまたはホスト名を持つ
  • Dockerを実行できる

つまり、必要なのはDocker、実行ホスト、管理者権限です。残りの設定はApidog上で行います。

General Runnerをデプロイする

デプロイコマンドはApidogが生成します。トークンを含むため、手動で作成する必要はありません。

1. デプロイコマンドを生成する

Apidogで次の手順を実行します。

  1. Apidogホームで対象チームを選択する
  2. 右側サイドバーのリソースを開く
  3. General Runnerをデプロイを選択する
  4. 表示されたポップアップで設定する

主な設定項目は次のとおりです。

  • サーバーOS

    Linux、macOS、Windowsから選択します。選択内容に応じて生成コマンドが変わります。

  • Dockerイメージ

    • General: Node.js 18、Java 21、Python 3、PHP 8を含む
    • Slim: Node.js 18のみを含む軽量イメージ
    • Custom: テスト用に追加ランタイムが必要な場合、自分のDockerfileを利用する

  • 公開ポート

    -pで設定します。たとえば、-p 80:4524はホストの80番ポートをコンテナの4524番ポートにマッピングします。

  • データディレクトリのマウント

    -vで設定します。再起動後もランナーのデータを保持するために使用します。

生成されたコマンドにはトークンが埋め込まれています。このトークンは一度しか表示されないため、すぐに安全な場所へ保存してください。紛失した場合は、既存トークンを復元するのではなく、新しいコマンドを生成します。

2. サーバーでコンテナを起動する

生成したコマンドをサーバー上のターミナルで実行します。コマンドはおおむね次の形式です。

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

起動後、コンテナを確認します。

docker ps
Enter fullscreen mode Exit fullscreen mode

apidog-runnerがポートマッピング付きで表示されれば、コンテナは起動しています。

3. Apidogに登録されたことを確認する

Apidogに戻り、次の順で確認します。

  1. チームリソースを開く
  2. General Runnerを選択する
  3. 更新ボタンをクリックする

ランナーがStartedとして表示されれば準備完了です。すぐに表示されない場合は少し待ち、再度更新してください。

ランナーのステータスは次の3種類です。

ステータス 意味 対応
Started Apidogと通信し、タスクを処理できる 正常状態
Stopped Apidog上で手動停止されている 必要に応じて開始する
Offline Apidogへの接続を失っている コンテナとネットワークを確認する

Runner Mockを有効にする

ランナーをデプロイしただけでは、モックリクエストはまだランナーに向きません。Server Hostを設定します。

  1. チームリソースでGeneral Runnerを開く
  2. Server Hostフィールドを探す
  3. ランナーに到達可能なURLを入力する

HTTPでの設定例:

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

共有イントラネットホストの例:

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

TLS終端プロキシを使う場合:

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

Server Hostを保存すると、Apidogはプロジェクト用にRunner Mock環境を自動作成します。

プロジェクトを開き、環境管理でRunner Mockが環境一覧に表示されることを確認してください。手動で環境を作成する必要はありません。

セルフホスト型モック経由でリクエストを送信する

たとえば、社内受注管理APIに次のエンドポイントがあるとします。

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

Apidogでこのエンドポイントを開き、上部の環境ドロップダウンからクラウド環境ではなくRunner Mockを選択してリクエストを送信します。

直接確認する場合は、ランナーのServer Hostに対してcurlを実行できます。

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

レスポンス例:

{
  "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

このレスポンスは、ランナーがエンドポイントのスキーマをもとに生成し、内部ネットワークから返します。

customerEmailのようなフィールドを意識したデータ生成は、Apidogがスキーマの型とフィールド名を解釈することで実現されます。詳細は、スマートモックによる現実的なモックデータの自動生成を参照してください。

特定のレスポンスを固定したい場合は、エンドポイントにモックの期待値を追加します。General Runnerはクラウドモックと同じように期待値を返します。モックの設計方法自体はホスト方式に依存しません。APIモッキングの基本的な考え方もそのまま適用できます。

HTTPS、データマウント、運用上の注意点

HTTPSにはリバースプロキシを使用する

General RunnerはHTTPS証明書を内蔵しておらず、証明書の自動取得・更新も行いません。

HTTPSを使う場合は、ランナーの前段にNginxなどのリバースプロキシを置き、そこでTLSを終端します。NginxのHTTPS設定については、Nginx公式ドキュメントを参照してください。

最小構成の例です。

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

この場合、ApidogのServer Hostには次を設定します。

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

リバースプロキシを使わない場合は、http://host:portを指定してください。ランナー自身にhttps://で直接応答させることはできません。HTTPSの基礎はMDNのHTTPS解説も参考になります。

ファイルマウントは固定パスに合わせる

モックやテストで追加ファイルを使う場合、ランナーはコンテナ内の固定パスを参照します。ホスト側ディレクトリを-vで対応するパスへマウントしてください。

用途 コンテナ内パス
外部プログラム /app/external-programs/
データベース接続設定 /app/database/database-connections.json
SSLクライアント証明書 /app/ssl/ssl-client-cert-list.json

データを永続化する場合も、ホスト側ディレクトリをマウントして再起動に備えます。

再デプロイとアップグレード

新しいランナーバージョンが公開されると、Apidogにはアップグレードオプションが表示されます。また、その他のアクションから再デプロイできます。

どちらの操作でも、実行中のコンテナは停止して新しいコンテナが起動します。そのため、モックのライブサービングはコンテナ再起動中に一時中断します。

一方で、Apidogクライアント内にある既存のスケジュール済みタスク設定は、再デプロイやアップグレードによって失われません。

Apidog CLIでワークフローを自動化する

General RunnerとApidog CLIは別のツールです。

ツール 主な用途
General Runner モックの提供、スケジュールタスクの実行
Apidog CLI CI環境でのワンショットテスト実行、モック期待値の管理

Apidog CLIはモックサーバーを起動・提供・ホストしません。apidog run mockやapidog mock serveといったコマンドはありません。

CLIの役割は次のとおりです。

  • apidog runでテストシナリオ、フォルダ、テストスイートを実行する
  • mockコマンドグループでモック期待値をCRUD操作する

セルフホスト型モックの提供はGeneral Runner、またはクラウドモックが担当します。

CIでテストシナリオを実行する例:

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

このコマンドはライブバックエンドに対してシナリオを実行し、HTMLとCLIレポートを出力します。

Node.js v16以降でCLIをインストールします。

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

ログインとトークン設定は、Apidog CLIインストールガイドを参照してください。プッシュごとにテストを実行する場合は、Apidog CLI CI/CDガイドに従ってパイプラインへ組み込みます。

CLIがモック定義を管理できてもサーバーとして提供しない理由は、CLIからのAPIモッキングで確認できます。

よくある質問

チームがインターネットに接続できる場合でも、セルフホスト型ランナーは必要ですか？

通常は不要です。クラウドモックの方がデプロイや運用が不要でシンプルです。

ただし、アウトバウンド通信の制限、コンプライアンス、エアギャップ要件がある場合はランナーを選択してください。Apidogクラウドモックの解説も、選定時の参考になります。

Apidog CLIはセルフホスト型モックサーバーを起動できますか？

いいえ。CLIはテストの実行とモック期待値の管理を行います。モックトラフィックの提供はGeneral Runnerまたはクラウドモックの役割です。

ランナー単体でHTTPSをサポートできますか？

できません。NginxなどのリバースプロキシでTLSを終端し、そのHTTPS URLをServer Hostに設定してください。リバースプロキシがない場合はhttp://host:portを使用します。

コマンドを実行したのにランナーが表示されないのはなぜですか？

以下を順に確認してください。

  1. チームリソースのGeneral Runner画面で更新ボタンを押す
  2. docker psでコンテナが起動していることを確認する
  3. ホストからApidogへのネットワーク経路を確認する
  4. ステータスがOfflineではなくStartedになっていることを確認する

複数チームで1つのランナーを共有できますか？

ランナーはデプロイしたチームに登録され、Runner Mock環境はプロジェクトごとに表示されます。グローバルチームでモック環境を共有する設計については、グローバルチーム間でモック環境を共有するガイドを参照してください。

まとめ

General Runnerを使うと、モック設計はApidogプロジェクトで一元管理しながら、リクエストとレスポンスの通信を自社インフラストラクチャ内に保持できます。

実装手順は次のとおりです。

  1. Dockerホストを準備する
  2. ApidogでGeneral Runnerのデプロイコマンドを生成する
  3. サーバー上でコンテナを起動する
  4. ApidogでランナーのStartedステータスを確認する
  5. Server Hostを設定する
  6. プロジェクトでRunner Mock環境を選択してリクエストを送信する

クラウドを利用できない、または利用すべきでない環境では、セルフホスト型ランナーを使ってください。準備ができたら、Apidogをダウンロードし、最初のRunner Mockレスポンスをイントラネット内から返してみましょう。

Top comments (0)