Apidog Self-hosted Runner は、スタンドアロンサーバー上でホストできる自動化プログラムとして理解できます。スケジュールされた自動テスト、スケジュールされた API ドキュメントのインポート、モックレスポンス結果の返却など、Apidog 内のタスクを実行できます。ホストマシン（サーバーまたはローカル PC）には Docker がインストールされている必要があります。 必要な Docker の最小バージョンは 20.10.0 で、バージョン 20.10.13 を推奨します。
クイックスタート#
このセクションでは、サーバーに General Runner をデプロイする方法を説明します。1. General Runner をデプロイする#
Apidog Home ページに移動し、目的のチームを選択して、右側の Resources をクリックします。そこから Deploy General Runner をクリックして開始します。2. Runner デプロイコマンドを取得する#
Deploy General Runner をクリックしたら、ポップアップウィンドウから General Runner のデプロイコマンドをコピーします。必要に応じてコマンドをカスタマイズでき、カスタムサーバー OS、公開ポート、データディレクトリのマウントなどをサポートしています。以下に、これらの設定の詳細を説明します。Server OS: Docker コンテナのオペレーティングシステムを指定します。これには Linux、macOS、Windows が含まれます。Docker コンテナが正常に動作するようにするには、正しいオペレーティングシステムを選択することが重要です。
Docker Image: General、Slim、Custom の 3 つのバージョンを利用できます。「カスタムスクリプト」で外部プログラムを呼び出す必要がある場合は、必要な環境に基づいてインストールに適したイメージを選択してください。General: Runner のすべての機能を含み、Node.js 18、Java 21、Python 3、PHP 8 の各言語環境が事前にインストールされています。
Slim: Runner のすべての機能を含みますが、Node.js 18 のみが事前にインストールされています。
Custom: Runner のすべての機能を含み、外部プログラム用のカスタム言語環境をサポートします。必要に応じて環境を追加または削除するために、独自の Dockerfile を作成できます。
Exposed Port: デフォルトでは、Docker コンテナは外部アクセス用に内部ポートを公開しません。-p パラメータを使用すると、コンテナの内部ポートをホストマシンのポートにマッピングでき、コンテナが提供するサービスへの外部アクセスが可能になります。たとえば、-p 80:4524 はコンテナの内部ポート 4524 をホストマシンのポート 80 にマッピングします。
Mount Data Directory: -v パラメータを使用すると、ホストマシンのディレクトリをコンテナにマウントでき、コンテナがホスト上のファイル（例: データベース設定や外部プログラム）にアクセスして操作できるようになります。たとえば、-v "/opt/runner":/opt/runner はホストの /opt/runner ディレクトリをコンテナの /opt/runner ディレクトリにマウントします。
デプロイコマンドにはトークン情報が含まれており、データセキュリティ上の理由により一度だけ表示されます。Deploy General Runner をクリックするたびに新しいコマンドが生成されます。今後の Runner のアップグレードで使用できるため、コマンドをローカルに保存してください。
3. サーバーに Runner をデプロイする#
コピーしたデプロイコマンドをサーバーのターミナルに貼り付けると、Runner のインストールが自動的に開始されます。インストールが完了すると、ターミナルに関連情報が出力されます。エラーがある場合は、エラーの詳細に基づいてトラブルシューティングできます。それでも解決できない場合は、お問い合わせ いただき、フィードバックを提供してください。4. サーバー上の Runner ステータスを表示する#
Docker クライアントを通じて、コンテナの実行ステータスを表示できます。ターミナルで docker ps コマンドを使用して、コンテナの実行ステータスを表示することもできます。5. Apidog でデプロイ済みの General Runner を表示する#
サーバー上の Runner コンテナがデプロイされ、有効になっていることを確認したら、Apidog に戻ります。Team Resources → General Runner で、Runner がデプロイされ、Apidog に接続されていることを確認できます。General Runner がサーバー上で正常にデプロイされているにもかかわらず、Apidog クライアントに表示されない場合は、「General Runner」の右側にある更新ボタンをクリックしてページを更新し、再度確認してください。
| ステータス | 説明 |
|---|
| 開始済み | Runner はサーバー上のコンテナ内で正常に有効化されており、Apidog との通信を維持し、Apidog から発行された関連タスクを処理できます。 |
| 停止済み | Runner は Apidog で手動停止されていますが、サーバー上のコンテナ内では正常に実行され続け、通信も維持されています。Apidog から発行されたタスクは処理されず、新しいタスクで停止済みの Runner を実行対象として指定することはできません。Apidog で手動で有効化すると、Runner を開始済み状態に戻せます。 |
| オフライン | Runner は Apidog から切断されており、タスクを処理できません。これは、サーバー上で Runner コンテナが停止しているか、サーバーと Apidog 間の通信に問題があることが原因である可能性があります。Runner を復旧するには、Runner コンテナが実行中であり、Apidog との通信に問題がないことを確認してください。これにより、Runner を開始済み状態に復旧できます。 |
チーム内に複数の General Runner をデプロイできます。セルフホスト Runner を必要とするタスクを作成する際、チームメンバーは利用可能な Runner から選択できます。Runner でのファイル保存#
Runner を使用してエンドポイントリクエスト、テストシナリオ、スケジュールタスクなどのタスクを実行する場合、タスク実行をサポートするために特定のローカルファイルが必要になることがありま す。例は次のとおりです。カスタムスクリプトで他のプログラミング言語を呼び出す
Pre/Post Processor でデータベース接続を使用する
| 使用内容 | 指定ディレクトリパス（またはファイル名） | Docker コマンド例 |
|---|
| その他のプログラミング言語 | /app/external-programs/ | -v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms |
| データベース接続設定ファイル | /app/database/database-connections.json | -v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json |
| SSL 証明書リストファイル | /app/ssl/ssl-client-cert-list.json | -v /Users/xxx/runner/packages/api-test/ssl/ssl-client-cert-list.json:/app/ssl/ssl-client-cert-list.json |
Apidog クライアントから設定ファイルをエクスポートする方法については、このページ を参照できます。 Runner のアップグレードと再デプロイ#
Runner のアップグレード#
Runner の新しいバージョンがリリースされると、デスクトップ Runner UI にアップグレードアイコンが表示されます。アイコンをクリックして、Apidog が提供する最新バージョンをインストールします。Upgrade をクリックすると、現在実行中の Runner コンテナを停止するよう求められます。コンテナが停止すると、スケジュールタスクおよびクライアントからこの Runner に送信されたすべてのタスクは実行されなくなる点に注意してください。アップグレードを確認すると、Apidog は現在の Runner コンテナを自動的に停止し、新しいバージョンをデプロイするためのコマンドを提供します。初回デプロイ手順 に従って Runner を再デプロイしてください。デプロイが成功すると、最新バージョンを使用できるようになります。注: クライアント内の既存のスケジュールタスクは影響を受けず、再割り当てする必要はありません。Runner の再デプロイ#
Runner で問題が発生し、Q&A セクションで解決策が見つからない場合、または手順が役に立たない場合は、Runner の再デプロイを検討してください。これを行うには、該当する Runner の More Actions セクションに移動し、Redeploy をクリックします。再デプロイプ ロセスは、上記のアップグレード と同じです。注: 再デプロイでも Runner コンテナは停止されます。Q&A#
docker ps コマンドを使用して、問題のある Runner を特定します。
ステップ 1: 問題を診断するための情報を収集します。
開発者ツール（Alt+7+8）を開き、問題のある Runner にテストシナリオを送信して、エンドポイントの詳細を記録します
Runner ログを確認し、エラーメッセージや手がかりを探します
問題を特定でき、それが Apidog のバグに起因しない場合は、自分で修正します
問題を特定できない場合は、さらに支援を受けるために Apidog コミュニティに連絡してください
ステップ 1: タスクの完了を確認します。
スケジュールタスクのテストレポートが Apidog クライアントで利用可能かどうかを確認します
通知設定がスケジュールタスク内に保存されていることを確認します
条件と受信者が正しく設定されていることを再確認します
通知が正しく送信されるか確認するために、タスクを手動でトリガーしてみます
このエラーには 2 つの原因が考えられます。
デプロイコマンドが再生成された: コマンドを生成し、ポップアップを閉じてから再度クリックした場合、新しいトークンによって以前のトークンが無効化される可能性があります。これを修正するには、次の手順を実行します。左上隅で別のチームに切り替え、その後 Runner のデプロイが必要なチームに戻ります
デプロイコマンドを再生成してコピーし、実行します。プロセスが完了するまで、再生成を再度クリックしないようにしてください。
teamId 変数の ID データエラー: これは既知のバグであり、最新バージョンで修正されています。問題が解決しない場合は、次の手順を実行します。左上隅で別のチームに切り替え、その後 Runner のデプロイが必要なチームに戻ります
デプロイコマンドを再生成してコピーし、実行します。プロセスが完了するまで、再生成を再度クリックしないようにしてください。
