Installation

NodePit Runner is distributed as a set of Docker images and runs with Docker Compose. A typical installation takes under ten minutes.

Prerequisites

System requirements

• 2 CPUs, 8 GB RAM, 50 GB disk (minimum)
• Any OS that runs Docker — Linux (Debian/Ubuntu) recommended for production

Software

• Docker
• Docker Compose v2 (docker compose, not docker-compose)

Step 1 — Download docker-compose.yml

The nodepit/runner repository on GitHub is the single source for all Runner distribution files: the Docker images, the official compose file, and optional extensions for HTTPS, backups, and more.

Download the official compose file from GitHub:

curl -O https://raw.githubusercontent.com/nodepit/runner/main/docker-compose.yml

Or download it directly and save it to an empty directory.

Step 2 — Start Runner

docker compose up -d

Docker pulls the images on first run, which may take a minute or two. Once all containers are healthy, Runner is available at http://localhost:8080.

Step 3 — Create the admin account

Open http://localhost:8080 in your browser. On first launch you will be prompted to set a password and create the initial admin account.

Once logged in, go to Settings to configure your time zone, SMTP for notifications, and your license key.

Upgrading

Pull the latest images and restart the stack:

docker compose pull
docker compose up -d

Database migrations run automatically on startup. No manual steps are required.

Next steps

• Configuration — set secrets, configure a public URL, set up a reverse proxy, scale executors
• Quick Start — create your first project and run a workflow