General Runner

This section introduces the general runner, which is an automated program that helps you execute your tasks.

The Apidog General Runner can be understood as an automated program that can be hosted on a standalone server. It can execute tasks within Apidog, such as scheduled automated tests, scheduled API document imports, and Returning mock response results.

Preparation

• Linux server
• Docker environment installed. The minimum version should be 20.10.0, Version 20.10.13 is recommended.

Quick Start

This section will guide you on how to deploy General Runner on your server.

1. Deploy General Runner

Go to the team "Resources" at Apidog and click on "Deploy General Runner".

2. Generate the Runner Deployment Command

After clicking on "Deploy General Runner", a pop-up window will display the deployment command script for the General Runner of the current team. You need to copy this command and deploy it on your server.

3. Deploy Runner on the Server

Paste the copied deployment command into the server's terminal, and the Runner installation will start automatically.

tip

You can modify the deployment properties of the Runner through environment variables to better match your actual usage scenarios. Read Runner Running Environment for more information.

After the installation is complete, the terminal will print relevant information. If there is an error, you can troubleshoot it based on the error details. If you still can't solve it, please contact us and provide feedback.

4. View Runner Status on the Server

You can view the running status of the container through the Docker client.

You can also use the docker ps command in the terminal to view the running status of the container.

5. View Deployed General Runner at Apidog

After confirming that the Runner container on the server has been deployed and enabled, return to Apidog. You can see that the Runner has been deployed and connected to Apidog in "Team Resources" → "General Runner".

If the General Runner has been successfully deployed on the server, but it is not displayed in the Apidog client, please click the refresh button on the right side of "General Runner" to refresh the page and check again.

You can rename, add descriptions, and delete the Runner so that your team members can better use this Runner; you can also stop/restart the Runner.

The suspended Runner will no longer execute the specified scheduled tasks, nor will it be able to create new related tasks and specify this Runner to execute.

Refer to the table below for the status explanation of the Runner:

Status	Description
Started	The Runner is enabled normally in the container on the server, maintains communication with Apidog, and can handle related tasks issued by Apidog.
Stopped	The Runner is manually stopped in Apidog but continues to run normally in the container on the server and maintains communication. It will not process tasks issued by Apidog, and new tasks cannot specify a stopped Runner for execution. You can manually enable it at Apidog to restore the Runner to the started state.
Offline	The Runner is disconnected from Apidog and cannot process tasks. This may be due to the Runner container stopping on the server or communication issues between the server and Apidog. To restore the Runner, ensure the Runner container is running and there are no communication problems with Apidog, allowing the Runner to restore to the started state.

You can deploy multiple General Runners within a team. When creating tasks that require self-hosted Runners, team members can choose from the available Runners.

Saving Files in Runner

When using Runner to execute tasks such as endpoint requests, test scenarios, and scheduled tasks, certain local files may be required to support task execution. Examples include:

• Calling other programming languages in custom scripts
• Using database connections in Pre/Post Processors
• Using SSL certificate when sending a request

To accommodate this, save the necessary files in the specified directory within the Docker container. When the Runner executes related tasks, it will read the file content from the specified directory according to the task requirements to ensure successful completion.

Refer to the following table to place files with the appropriate formats and content into the specified directory for use:

Use Content	Specified Directory Path (or File Name)	Example Docker Command
Other Programming Languages	/app/external-programs/	-v /Users/xxx/runner/packages/api-test/external-programs:/app/externalPrograms
Database Connection Configuration File	/app/database/database-connections.json	-v /Users/xxx/runner/packages/api-test/database/database-connections.json:/app/database/database-connections.json
SSL Certificate List File	/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

Here is an example of the database connection configuration file:

{
    "19731": {
        "configs": {
            "default": {
                "username": "accountname",
                "password": "123456",
                "host": "192.168.0.0"
            }
        },
        "id": 19731,
        "name": "Database Name",
        "type": "mysql",
        "projectId": 1320441,
        "description": "Dummy data.",
        "createdAt": "2022-09-27T07:51:09.000Z",
        "updatedAt": "2024-05-09T11:38:07.000Z",
        "deletedAt": null
    }
}

You can refer to here to see how to export the configuration file from the Apidog client.

Example of the SSL certificate list file:

[
    {
        "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"
    }
]