Get Rune running
in minutes.

Download the production Compose file

This file pulls the pre-built engine image from GitHub Container Registry. No source code clone needed.

curl -O https://raw.githubusercontent.com/praveenraj-sk/Rune/main/docker-compose.prod.yml

This downloads a single docker-compose.prod.yml file to your current directory. Inspect it before running — it defines two services: postgres and rune-engine.

Generate secrets before starting

Run these two commands once. Store the output in a password manager — you'll need them in the next step.

# Salt for hashing API keys (required — never change after issuing keys)
openssl rand -hex 32
# → e.g. 3f9a2b...  ← copy this as API_KEY_SALT

# Admin dashboard key (optional — omit to disable the /dashboard UI)
openssl rand -hex 32
# → e.g. 8d71cc...  ← copy this as ADMIN_API_KEY

Create a .env file

Create .env in the same directory as your compose file and fill in the values from Step 2.

# Required
DATABASE_URL=postgresql://rune:runepassword@postgres:5432/runedb
PORT=4078
NODE_ENV=production

# Security — paste values from Step 2
API_KEY_SALT=your-32-byte-hex-from-openssl
ADMIN_API_KEY=your-32-byte-hex-from-openssl

# Tuning (defaults are production-safe)
MAX_CACHE_SIZE=10000
MAX_BFS_DEPTH=20
MAX_BFS_NODES=1000
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW_MS=10000

Start the engine

Docker Compose will pull the Rune image, start Postgres, run the database migrations, and start the API server — all in one command.

docker compose -f docker-compose.prod.yml up -d

The first run downloads the image (~80MB). Subsequent starts are instant. Both services run in the background (-d flag).

docker compose -f docker-compose.prod.yml ps
# Both services should show "Up" or "running"

docker compose -f docker-compose.prod.yml logs rune-engine
# Should show: Rune engine running on port 4078

Create your first tenant and API key

The engine is running but has no tenants yet. Run setup to create your first tenant and receive an API key.

docker compose -f docker-compose.prod.yml exec rune-engine pnpm run setup

When prompted, enter a name for your tenant (e.g. acme-corp). Setup will output:

  ✓ Setup complete!

  Tenant ID  84d1aef9-3c2b-4f10-a891-...
  API Key    rune_158Yy...

  ⚠️  Save your API key — it will not be shown again.

Verify the deployment

Run these checks to confirm the engine is healthy and accepting authenticated requests.

curl http://localhost:4078/v1/health
# → {"status":"ok","db":"connected"}

curl -s -X POST http://localhost:4078/v1/can \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"subject":"user:test","action":"read","object":"doc:hello"}' | jq .

# Expected (no tuples yet — this is correct behaviour):
# {"decision":"deny","status":"NOT_FOUND","reason":"No path found..."}

Install the SDK and make your first check

In your application project, install the SDK and connect to the running engine.

npm install @runeauth/sdk

import { Rune } from '@runeauth/sdk'

const rune = new Rune({
  apiKey:  process.env.RUNE_API_KEY,   // API key from Step 5
  baseUrl: 'http://localhost:4078',
})

// Grant alice viewer access on doc:report
await rune.allow({
  subject:  'user:alice',
  relation: 'viewer',
  object:   'doc:report',
})

// Check access — returns ALLOW
const result = await rune.can('user:alice').do('read').on('doc:report').check()
console.log(result.status) // "ALLOW"
console.log(result.trace)  // full decision path

Harden for production

Before exposing the engine to the internet, complete these steps.

• 1 Put a reverse proxy in front. Run Nginx, Caddy, or a cloud load balancer that terminates TLS. Never expose the engine's port (4078) directly to the public internet.
• 2 Set NODE_ENV=production in your .env. This disables verbose error messages in API responses.
• 3 Restrict ADMIN_API_KEY access. The /admin dashboard should only be accessible internally (e.g., via VPN or IP allowlist on your proxy).
• 4 Use a managed Postgres instance (RDS, Cloud SQL, Supabase) instead of the Docker Compose Postgres for production databases. Enable daily backups and point-in-time recovery.
• 5 Store secrets in a secret manager (AWS Secrets Manager, Vault, Doppler). Never commit .env to source control.
• 6 Set up log shipping. The engine emits structured JSON logs via Pino. Forward them to Datadog, CloudWatch, Loki, or your log aggregator of choice.