Skip to main content

Custom runner

Video tutorial

Watch the Artemis AI video tutorial on setting up and using a custom runner here: Configuring a custom runner

Custom runner overview​

A custom runner enables you to validate your code by running builds, tests, and benchmarks on a preferred virtual machine.

Whilst validation commands can be executed on the runners available by default it is preferable to use a custom runner because there are a limited number of default runners available, and it is likely the default runners will not have the dependencies your project requires to be built and run.

Download the custom runner​

Download the zip file from the downloads page and extract it to the directory of your choice somewhere on your local machine.

Configure environment variables​

Navigate into your extracted Artemis custom runner directory.

cd artemis-custom-runner

Update .env.credentials with your Artemis username, password, and runner name which is a short string to help you identify your runner i.e. <your name - your project>

nano .env.credentials

.env.credentials

ARTEMIS_USERNAME="<your artemis email address>"
ARTEMIS_PASSWORD="<your artemis password>"
ARTEMIS_RUNNER_NAME="<your runner name>"
ARTEMIS_TARGET_ENVIRONMENT="production"

Install the custom runner​

The remainder of this page directs you through the process of setting up a custom runner, you have three options for how :

  1. Run via the quick-start script
  2. Install and run manually
  3. Run via Docker
  4. Build and deploy the custom runner Docker image
  5. Add the custom runner to a pre-existing Docker image

Quick-start​

OS Support

The quickstart script runs natively on Linux, and macOS, and can be run on Windows via the WSL.

Run the quick-start script to install the required dependencies and start the runner. For instructions on manual installation see the manual installation instructions elsewhere on this page

bash quickstart.sh

If Artemis is installed and running correctly, you should see something like the following at the end of the stdout.

[INFO]  12:18:58,473 [loki_listener] Polling for tasks
Managing Python Dependencies

The quick-start script creates a new virtual environment inside the Artemis custom runner directory - if your project has any Python dependencies they should be added to this virtual environment. For example by stopping the runner with Ctrl+C and running the below from the Artemis custom runner directory:

source .venv/bin/activate

python3 -m pip install -r /path/to/your/project/requirements.txt
python3 -m pip install module_name

Set the ARTEMIS_SKIP_DEPS variable to 1 to avoid installing Python again and recreating the virtual environment and restart the runner with the quick-start script.

export ARTEMIS_SKIP_DEPS=1
bash quickstart.sh

Enter your runner name in the Runner Name field and click the save button.

runner name

You are now ready to start validating code with your runner, see the documentation pages on Evaluating Recommendations for next steps.

Manual Installation​

If you are unable to use the quick-start script (for example is you are installing the runner on Windows) you can install the runner manually using the instructions below.

Create virtual environment​

Create a virtual environment with Python 3.11 inside the extracted custom runner directory:

python3.11 -m venv .venv
source .venv/bin/activate

Install wheels​

Install the Python dependencies for the runner from the wheels directory via the below pip command:

pip install wheels/*.whl
Updating wheels

If you need to upgrade an existing custom runner you can update the wheels in an existing environment by running the following:

pip install --upgrade --force-reinstall wheels/*.whl

Run the runner​

python -m runner --runner-name <your runner name>
Environments

The runner defaults to the production environment. If using the dev or staging environment, pass the --environment command line argument to program. For example, to use the staging environment:

python -m runner --environment=staging --runner-name <your runner name>

All valid values can be inspected using python -m runner --help

Custom Runner Docker Image​

If you prefer you can deploy the runner as a Docker container using the instructions below.

Build the image​

Build the Docker image from the dockerfile so you can run it later, this image includes Python, Bash, and git by default but you may need to modify it to include additional dependencies should your project require them i.e Maven, or Clang.

docker build --target python -f docker/Dockerfile . -t artemis-runner:python-latest

Deploy the container​

You can run the container explicitly using docker or arrange the execution using docker compose so volume management and environment configuration is easier.

Run container using plain docker​
docker run -v /location/of/file/.env.credentials:/app/.env.credentials -e ARTEMIS_RUNNER_NAME="<your runner name>"  
artemis-runner:python-latest
Run container using docker compose​

Create a Docker Compose file with the following service and run docker compose up.

version: "3"
services:
  artemis-runner:
  image: artemis-runner:python-latest
  container_name: artemis-runner
  hostname: artemis-runner
  build:
    dockerfile: ./docker/Dockerfile
    context: ./../
    target: python
  environment:
    ARTEMIS_RUNNER_NAME: <your runner name>
  volumes:
    - ./../.env.credentials:/app/.env.credentials

Adding the runner to an existing docker image​

In case you already have a working image for your application or software stack, you can just reuse that image and just copy the binary for the Artemis runner and execute it by standard ENTRYPOINT or CMD docker method, for example by adding snippet below to your existing Dockerfile:

FROM artemis-runner:base-latest as base
COPY --from=base /dist/artemis_runner /app/artemis_runner
ENTRYPOINT ["/app/artemis_runner"]

Next steps​

Now you have configured your custom runner you should set commands to run builds, tests, and benchmarks on your runner via the Build Settings page in the Artemis web console.