Docker Compose

Run the full runtz stack (frontend, backend engine and MongoDB) on any machine with Docker. The stack uses the published images runtzdev/runtz-engine and runtzdev/runtz-frontend from Docker Hub.

Requirements

• Docker and Docker Compose.

Install

Download the compose file:

curl -fsSL https://runtz.dev/docker-compose.yml -o docker-compose.yml

Start the platform in detached mode — there are no secrets to set, since the engine issues and stores its own sessions, API keys and login codes:

docker compose up -d

Open the platform:

http://localhost:3000

The backend health endpoint is available at:

http://localhost:8080/health

MongoDB is available on:

localhost:27017

If 8080, 3000 or 27017 are already in use, change BACKEND_PORT, FRONTEND_PORT and MONGODB_PORT in .env.

First access

On the first access, runtz asks for:

• Admin username
• Password
• Workspace Name

After this setup, the admin user can create workspaces and manage users in Settings.

Environment variables

PORT=8080
MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=runtz
RUNTZ_PUBLIC_URL=http://localhost:3000
CORS_ALLOWED_ORIGINS=http://localhost:3000

All optional — docker compose up -d works with none of them set. The image tag defaults to :rc — the newest published build, release candidate or stable; set RUNTZ_VERSION in .env to pin a specific release instead, e.g. RUNTZ_VERSION=1.0.0-rc25.

Upgrading

Pull the newest images and recreate the containers that changed — MongoDB and its data are untouched:

docker compose pull
docker compose up -d

By default this tracks :rc, so it always picks up the newest published build with no other action needed. If .env pins a specific RUNTZ_VERSION instead, bump it there first — check the changelog for what changed — then run the same two commands.

Confirm which version is actually running:

curl http://localhost:8080/health

There's no downgrade path: treat RUNTZ_VERSION as one-directional.

Self-hosted Pro and Enterprise activation

Self-hosted Free runs fully inside your infrastructure. Pro and Enterprise are activated from the in-app Settings -> Billing screen.

The self-hosted engine does not need Stripe keys. It starts Checkout through the central engine, redirects the admin to Stripe, then returns to the same installation and activates the license automatically. The only network requirement is outbound HTTPS access to:

https://engine.runtz.dev

Each license can activate one installation. The engine keeps scan data local and sends only the Stripe checkout session plus installation id to the central validation endpoint for activation and heartbeat.

Google authentication is available on every self-hosted plan, including Free. GitHub authentication is cloud-only and isn't available for self-hosted deployments. To enable Google sign-in, configure your own OAuth app and set GOOGLE_CLIENT_ID on the engine — the frontend picks up the client id at runtime.

Build from source

To build the images locally instead of pulling from Docker Hub, clone the repository and use the dev override:

git clone https://github.com/runtz-dev/runtz
cd runtz
cp .env.example .env   # optional: ports, OAuth, email login
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build