Skip to content

Install a Docker runner

A runner you host can reach whatever its network reaches: databases, internal APIs, Elasticsearch, Prometheus. This guide installs one, then a second for redundancy.

You need: an Owner or Admin role, and a Linux host with Docker that can reach both what you want to check and your SREInsights URL over HTTPS (port 443, outbound only).

  1. Go to Runners and select New runner group.
  2. Runs on: Runners you host.
  3. Name it after where it runs and what it can reach, such as prod-eu-dc. Monitors name it in their Runner group. Use lower-case letters, digits, ., _ or -.
  4. Add a Description, such as “Frankfurt data centre, can reach Elasticsearch and the payments cluster”.
  5. Select Create group.

On the group, select Add runner.

  • Runners this token can register: how many runners may use this token (1 to 50). Use 2 if you’re about to install two.
  • Valid for: 1 hour, 24 hours, 3 days or 7 days.

Select Create install command. The token is shown only this time.

Terminal window
docker run -d --name sreinsights-runner --restart unless-stopped --stop-timeout 40 \
-e SREINSIGHTS_URL=https://console.sreinsights.com \
-e SREINSIGHTS_REGISTRATION_TOKEN=prt_… \
-v sreinsights-runner:/var/lib/sreinsights-runner \
ghcr.io/bintree-softwares/sreinsights-runner:latest

Choose Docker Compose above the command for the same thing as a file. A hardened version:

services:
sreinsights-runner:
image: ghcr.io/bintree-softwares/sreinsights-runner:latest
restart: unless-stopped
environment:
SREINSIGHTS_URL: https://console.sreinsights.com
SREINSIGHTS_REGISTRATION_TOKEN: prt_… # needed on first start only
SREINSIGHTS_RUNNER_NAME: dc1-runner-a
SREINSIGHTS_RUNNER_LABELS: elastic-prod,eu
volumes:
- sreinsights-runner:/var/lib/sreinsights-runner
stop_grace_period: 40s
read_only: true
tmpfs:
- /tmp
cap_drop: [ALL]
security_opt: ["no-new-privileges:true"]
volumes:
sreinsights-runner: {}
Terminal window
docker compose up -d

The drawer shows Waiting for the runner to check in… until the runner registers, then its name and status. You can close it.

On Runners, the group shows 1 of 1 runner online, with the runner’s labels (os, arch and yours), job types, version and when it was last seen. Create a monitor on the group and select Run now.

Setting Why
The volume at /var/lib/sreinsights-runner Holds the runner’s private key. Without it, every restart needs a new registration token.
--stop-timeout 40 / stop_grace_period: 40s Running checks get 30 seconds to finish on shutdown. Docker’s default of 10 seconds cuts them off.
--read-only, a tmpfs at /tmp, --cap-drop ALL, no-new-privileges Hardening. Keep /tmp writable: script checks write their code and output there.
SREINSIGHTS_RUNNER_LABELS Your own labels. A monitor’s Runner labels must all be on a runner for it to take the run.
SREINSIGHTS_RUNNER_NAME How the runner shows on the Runners page. Defaults to the host name.

All settings are in Runner settings.

Run at least two runners per group, on different hosts, so checks keep running when one goes down. Repeat steps 2 and 3 on another host (or create one token for two runners). Runs go to whichever runner asks first.

  • Node scripts run on the image’s own Node.
  • Python and shell scripts need a runner image with those installed, or runtime: docker.
  • runtime: docker runs each script in a fresh container. The runner needs a Docker daemon: mount the Docker socket and add the Docker CLI to the image. Private images use a Docker registry connection.

For a connection only this group’s runners use, choose Keep them on the runners when you add the connection, and set the variables it lists on each runner:

Terminal window
-e SREINSIGHTS_SECRET_ORDERS_DB_PASSWORD=…

See Connections and secrets.

On Runners, Disable a runner. It is cut off at its next call and its runs go back to the group. Then stop the container and delete its volume. To delete a group, first move its monitors elsewhere.