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

Create a .env file with the two required secrets — the engine refuses to start with empty or placeholder values:

cat > .env <<EOF
JWT_SECRET=$(openssl rand -base64 32)
RUNTZ_INGEST_TOKEN=$(openssl rand -base64 24)
EOF

Start the platform in detached mode:

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
JWT_SECRET=          # required — openssl rand -base64 32
RUNTZ_INGEST_TOKEN=  # required — openssl rand -base64 24
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.

Self-hosted Google and GitHub authentication are Pro/Enterprise features. After activation, configure your own OAuth apps and set GOOGLE_CLIENT_ID, GITHUB_CLIENT_ID, and GITHUB_CLIENT_SECRET on the engine — the frontend picks up the Google 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   # fill JWT_SECRET and RUNTZ_INGEST_TOKEN
docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build