一般ランナー

Apidogのセルフホストランナーは、独立したサーバー上でホストできる自動化プログラムと理解できます。Apidog内のタスクを実行することができ、例えばスケジュールされた自動テスト、スケジュールされたAPIドキュメントのインポート、Mockレスポンス結果の返却などが含まれます。

準備

• Linuxサーバー
• Docker環境がインストールされていること。最低バージョンは20.10.0で、バージョン20.10.13が推奨されます。

クイックスタート

このセクションでは、サーバー上に一般ランナーをデプロイする方法を説明します。

1. 一般ランナーのデプロイ

Apidogホームページに移動し、希望のチームを選択し、右側のリソースをクリックします。そこから一般ランナーをデプロイをクリックして開始します。


2. ランナーデプロイコマンドの取得

一般ランナーをデプロイをクリックすると、ポップアップウィンドウから一般ランナーのデプロイコマンドをコピーできます。必要に応じてコマンドをカスタマイズでき、サーバーOS、公開ポート、マウントデータディレクトリなどをカスタマイズできます。以下はこれらの設定の詳細な説明です：

• サーバーOS: Dockerコンテナのオペレーティングシステムを指定します。Linux、macOS、Windowsが含まれます。正しいOSを選択することは、Dockerコンテナが正常に動作するために重要です。

• Dockerイメージ: 3つのバージョンがあります：General、Slim、Custom。もし「カスタムスクリプト」が外部プログラムを呼び出す必要がある場合、必要な環境に基づいて適切なイメージを選択してインストールします：

  • General: ランナーのすべての機能を含み、以下の言語環境がプリインストールされています：Node.js 18、Java 21、Python 3、PHP 8。
  • Slim: ランナーのすべての機能を含みますが、Node.js 18のみがプリインストールされています。
  • Custom: ランナーのすべての機能を含み、外部プログラムのためのカスタム言語環境をサポートします。必要に応じて独自のDockerfileを作成して環境を追加または削除できます。

• 公開ポート: デフォルトでは、Dockerコンテナは外部アクセスのために内部ポートを公開しません。-pパラメータを使用して、コンテナの内部ポートをホストマシンのポートにマッピングし、コンテナが提供するサービスに外部からアクセスできるようにします。例えば、-p 80:4524はコンテナの内部ポート4524をホストマシンのポート80にマッピングします。

• マウントデータディレクトリ: -vパラメータを使用して、ホストマシンのディレクトリをコンテナにマウントし、コンテナがホスト上のファイルにアクセスして操作できるようにします（例：データベース設定や外部プログラム）。例えば、-v "/opt/runner":/opt/runnerはホストの/opt/runnerディレクトリをコンテナの/opt/runnerディレクトリにマウントします。


:::tip

デプロイコマンドにはトークン情報が含まれており、データセキュリティの理由で一度だけ表示されます。一般ランナーをデプロイをクリックするたびに新しいコマンドが生成されます。

コマンドをローカルに保存してください。将来のランナーアップグレードに使用できます。
:::

3. サーバー上にランナーをデプロイ

コピーしたデプロイコマンドをサーバーのターミナルに貼り付け、ランナーのインストールが自動的に開始されます。

:::tip
環境変数を通じてランナーのデプロイプロパティを変更し、実際の使用シナリオに合わせることができます。詳細はランナーデプロイ環境を参照してください。
:::


インストールが完了すると、ターミナルに関連情報が表示されます。エラーが発生した場合、エラーの詳細に基づいてトラブルシューティングできます。それでも解決できない場合は、お問い合わせしてフィードバックを提供してください。

4. サーバー上のランナーステータスを確認

Dockerクライアントを通じてコンテナの実行ステータスを確認できます。


ターミナルでdocker psコマンドを使用して、コンテナの実行ステータスを確認することもできます。


5. Apidogでデプロイされた一般ランナーを確認

サーバー上のランナーコンテナがデプロイされ、有効化されたことを確認したら、Apidogに戻ります。「チームリソース」→「一般ランナー」で、ランナーがデプロイされ、Apidogに接続されていることを確認できます。

サーバー上で一般ランナーが正常にデプロイされているが、Apidogクライアントに表示されない場合は、「一般ランナー」の右側にある更新ボタンをクリックしてページを更新し、再度確認してください。

ランナーの名前変更、説明の追加、削除が可能で、チームメンバーがこのランナーをよりよく使用できるようにします。また、ランナーを停止/再開することもできます。

停止されたランナーは、指定されたスケジュールタスクを実行しなくなり、新しい関連タスクを作成してこのランナーを指定して実行することもできなくなります。



ランナーのステータス説明については、以下の表を参照してください：

ステータス	説明
開始済み	サーバー上のコンテナ内でランナーが正常に有効化され、Apidogとの通信を維持し、Apidogから発行された関連タスクを処理できます。
停止済み	ランナーがApidogで手動で停止されましたが、サーバー上のコンテナ内では正常に実行され、通信を維持しています。Apidogから発行されたタスクを処理せず、新しいタスクは停止されたランナーを指定して実行できません。Apidogで手動で有効化することで、ランナーを開始済みの状態に戻すことができます。
オフライン	ランナーがApidogから切断され、タスクを処理できません。これは、サーバー上のランナーコンテナが停止しているか、サーバーとApidog間の通信に問題があるためです。ランナーを復元するには、ランナーコンテナが実行中であり、Apidogとの通信に問題がないことを確認し、ランナーを開始済みの状態に戻します。

チーム内で複数の一般ランナーをデプロイできます。セルフホストランナーを必要とするタスクを作成する際、チームメンバーは利用可能なランナーから選択できます。

ランナー内でのファイル保存

ランナーを使用してAPIリクエスト、テストシナリオ、スケジュールタスクなどのタスクを実行する際、タスクの実行をサポートするために特定のローカルファイルが必要になる場合があります。例としては：

• カスタムスクリプトで他のプログラミング言語を呼び出す
• 前/後処理でデータベース接続を使用する
• リクエスト送信時にSSL証明書を使用する

これに対応するため、必要なファイルをDockerコンテナ内の指定ディレクトリに保存します。ランナーが関連タスクを実行する際、タスクの要件に従って指定ディレクトリからファイル内容を読み取り、タスクの成功を確保します。

以下の表を参照して、適切な形式と内容のファイルを指定ディレクトリに配置して使用します：

使用内容	指定ディレクトリパス（またはファイル名）	例 Dockerコマンド
他のプログラミング言語	/app/external-programs/	-v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms
データベース(apidog://link/pages/646353) 接続設定ファイル	/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

以下はデータベース接続設定ファイルの例です：

{
    "19731": {
        "configs": {
            "default": {
                "username": "accountname",
                "password": "123456",
                "host": "192.168.0.0"
            }
        },
        "id": 19731,
        "name": "データベース名",
        "type": "mysql",
        "projectId": 1320441,
        "description": "ダミーデータ。",
        "createdAt": "2022-09-27T07:51:09.000Z",
        "updatedAt": "2024-05-09T11:38:07.000Z",
        "deletedAt": null
    }
}

Apidogクライアントから設定ファイルをエクスポートする方法はこちらを参照してください。

SSL証明書リストファイルの例：

[
    {
        "name": "domain1",
        "matches": ["https://test.domain1.com/*", "https://www.domain1/*"],
        "key": {"src": "./client.domain1.key"},
        "cert": {"src": "./client.domain1.crt"},
        "passphrase": "changeme"
    },
    {
        "name": "domain2",
        "matches": ["https://domain2.com/*"],
        "key": {"src": "./client.domain2.key"},
        "cert": {"src": "./client.domain2.crt"},
        "passphrase": "changeme"
    }
]

ランナーのアップグレードと再デプロイ

ランナーのアップグレード

ランナーの新しいバージョンがリリースされると、デスクトップランナーUIにアップグレードアイコンが表示されます。アイコンをクリックして、Apidogが提供する最新バージョンをインストールします。


「アップグレード」をクリックすると、現在実行中のランナーコンテナを停止するように促されます。コンテナが停止すると、スケジュールタスクやクライアントからこのランナーに送信されたタスクは実行されなくなりますのでご注意ください。


アップグレードを確認すると、Apidogは現在のランナーコンテナを自動的に停止し、新しいバージョンをデプロイするためのコマンドを提供します。初期デプロイ手順に従ってランナーを再デプロイします。デプロイが成功すると、最新バージョンを使用していることになります。注意：クライアント内の既存のスケジュールタスクは影響を受けず、再割り当てする必要はありません。


ランナーの再デプロイ

ランナーに問題が発生し、Q&Aセクションで解決策が見つからない場合、または指示が役に立たない場合は、ランナーを再デプロイすることを検討してください。これを行うには、特定のランナーの「その他のアクション」セクションに移動し、再デプロイをクリックします。


再デプロイプロセスは上記のアップグレードと同じです。注意：再デプロイするとランナーコンテナも停止します。

Q&A

1. ランナーログを確認して問題を診断する方法は？

• docker psコマンドを使用して問題のあるランナーを特定します。
• 以下のコマンドを使用してログを確認します：
  ```YAML
  // コンテナabc123の最後の100行のログを確認（推奨）：
  docker logs --tail 100 abc123

// 過去5分間のログを確認：
docker logs --since 5m abc123

// 特定のタイムスタンプの5分前からのログを確認：
docker logs --until 2023-10-01T00:00:00 abc123
docker logs --until 5m abc123

// すべてのログを確認（データが大きいため非推奨）：
docker logs abc123

```
2. ランナーがダウン/切断されたり、タスクを実行できない場合、どうすればよいですか？

ステップ1：問題を診断するための情報を収集します：

• エラーパターンや操作の詳細を探します。例えば：
  • 以前は正常に動作していたスケジュールタスクが今日は実行されない。
  • ランナーが切断されていると表示される。
  • 割り当てたタスクが実行されない。
• 開発者ツールを開き（Alt+7+8）、問題のあるランナーにテストシナリオを送信し、APIの詳細を記録します。
• ランナーログを確認して、エラーメッセージや手がかりを探します。（ランナーログの確認方法を参照）

ステップ2：問題を解決します：

• 問題を特定でき、Apidogのバグによるものでない場合は、自分で修正します。ランナー関連の問題の場合、ランナーを再デプロイしてみてください。
• 問題を特定できない場合は、Apidogコミュニティに連絡してさらなる支援を受けてください。

3. ランナーがスケジュールタスクを完了した後、通知が届かないのはなぜですか？

ステップ1：タスクの完了を確認します：

• Apidogクライアントでスケジュールタスクのテストレポートが利用可能か確認します。
• ランナーログを確認して問題がないか確認します。（ランナーログの確認方法を参照）

ステップ2：通知設定を確認します：

• スケジュールタスク内に通知設定が保存されていることを確認します。
• 条件と受信者が正しく設定されているか再度確認します。
• 手動でタスクをトリガーして、通知が正しく送信されるか確認します。

4. 「ランナー権限なし」エラーの意味と修正方法は？

このエラーには2つの原因が考えられます：

• デプロイコマンドが再生成された場合： コマンドを生成し、ポップアップを閉じてから再度クリックすると、新しいトークンが生成され、以前のトークンが無効になる可能性があります。これを修正するには：

  • 左上のコーナーで別のチームに切り替え、ランナーデプロイが必要なチームに戻ります。
  • デプロイコマンドを再生成し、コピーして実行します。プロセスが完了するまで再生成をクリックしないように注意してください。

• teamId変数のIDデータエラー： これは既知のバグで、最新バージョンで修正されています。問題が続く場合は：

  • 左上のコーナーで別のチームに切り替え、ランナーデプロイが必要なチームに戻ります。
  • デプロイコマンドを再生成し、コピーして実行します。プロセスが完了するまで再生成をクリックしないように注意してください。