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/home/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_DEPLOYMENT_MODE=self-hosted
RUNTZ_PUBLIC_URL=http://localhost:3000
CORS_ALLOWED_ORIGINS=http://localhost:3000
RUNTZ_VERSION=1.0.0-rc1

Central/cloud deployments also need Stripe and the private license signing key:

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_PRO_CLOUD=price_...
STRIPE_PRICE_ENTERPRISE_CLOUD=price_...
STRIPE_PRICE_PRO_SELF_HOSTED=price_...
STRIPE_PRICE_ENTERPRISE_SELF_HOSTED=price_...
RUNTZ_LICENSE_PRIVATE_KEY=base64-ed25519-private-key

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