Skip to main content
Openfuse

Try Locally

Run a self-hosted Openfuse instance on your laptop in under 5 minutes. No domain, no DNS, no cloud account — just Docker.

This guide gets Openfuse running on your machine so you can explore the dashboard, create breakers, and test the SDK against a real instance. Everything runs in Docker.

Prerequisites

  • Docker Desktop (Mac, Windows, or Linux) with Docker Compose v2
  • mkcert for locally-trusted HTTPS certificates
  • Ports 80 and 443 available

Install mkcert if you don't have it:

brew install mkcert
mkcert -install
apt install mkcert
mkcert -install
sudo apt install mkcert
mkcert -install

You'll also need to trust the CA in your Windows browser. Copy the CA cert to Windows and install it:

mkcert -CAROOT  # shows the CA directory

Open that path from Windows Explorer and double-click the rootCA.pem file to install it in the Windows certificate store.

Check if anything is using the required ports:

lsof -i :80 -i :443 -P -n

Start Openfuse

Run the installer — it automatically uses lvh.me for local development:

curl -sSL https://get.openfuse.io/install | bash

The installer detects lvh.me as a local domain and automatically:

  • Generates all required secrets
  • Uses mkcert for locally-trusted HTTPS certificates (no browser warnings)
  • Starts a local mail server (Mailpit) for capturing emails
  • Sets up a default admin account

lvh.me is a public DNS that resolves all subdomains (*.lvh.me) to 127.0.0.1. This gives you working subdomain routing without editing /etc/hosts.

Install a specific version

curl -sSL https://get.openfuse.io/install | bash -s -- --version 1.2.0

What happens on first startup

First boot takes 2-3 minutes while the services initialize:

  1. PostgreSQL creates the openfuse and keycloak databases
  2. Keycloak starts and becomes healthy (~60s)
  3. Config Importer imports realm configuration into Keycloak, then exits
  4. API runs database migrations and creates your admin user
  5. UI starts serving the dashboard

Watch the progress:

cd openfuse/
docker compose logs -f

Verify it works

Once docker compose ps shows all services as healthy:

WhatURLYou should see
UIhttps://lvh.meOpenfuse dashboard / login redirect
SSOhttps://sso.lvh.meKeycloak login with Openfuse theme
API healthhttps://admin.api.lvh.me/health200 OK
Mailpithttp://localhost:8025Email inbox (captured emails)

If you see a certificate warning, make sure you ran mkcert -install before running the installer. The installer uses mkcert to generate certificates trusted by your system.

Sign in and create your first company

  1. Go to https://lvh.me and click Sign in
  2. Log in with the default credentials: admin@lvh.me / Admin123!@#local
  3. Follow the onboarding flow to create your first company (e.g., acme)
  4. Generate SDK credentials (client ID and secret) from the dashboard

Connect the SDK

Install the SDK in your project:

npm install @openfuseio/sdk

Point it at your local instance:

app.ts
import { Openfuse } from '@openfuseio/sdk'

const openfuse = new Openfuse({
  baseUrl: 'https://acme.api.lvh.me',
  system: 'payments',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
})

await openfuse.init()

const payments = openfuse.breaker('stripe')
const result = await payments.protect(() => callStripeAPI())

Replace acme with the company slug you created. See the Quickstart for a full walkthrough of the SDK.

Manual setup (alternative)

If you prefer to configure everything yourself instead of using the installer:

cd openfuse/
cp .env.example .env

Edit .env:

ROOT_DOMAIN=lvh.me
COMPOSE_PROFILES=bundled-db,local

DATABASE_PASSWORD=localdev
SESSION_SECRET=          # run: openssl rand -hex 32

KC_BOOTSTRAP_ADMIN_PASSWORD=admin

# Generate each with: openssl rand -hex 24
KC_STAFF_BACKEND_CLIENT_SECRET=
KC_STAFF_BFF_CLIENT_SECRET=
KC_TENANTS_BACKEND_CLIENT_SECRET=
KC_TENANTS_BFF_CLIENT_SECRET=
KC_TENANTS_SDK_CLIENT_SECRET=

ROOT_USER_EMAIL=admin@lvh.me
ROOT_USER_PASSWORD=Admin123!@#local

# Mailpit runs inside the stack via the "local" profile
SMTP_HOST=mailpit
SMTP_PORT=1025
SMTP_USER=openfuse
SMTP_PASSWORD=openfuse

Generate mkcert certificates and swap to the local Caddyfile:

mkdir -p certs
mkcert -cert-file certs/cert.pem -key-file certs/key.pem \
  lvh.me "*.lvh.me" "*.api.lvh.me" localhost 127.0.0.1
cp Caddyfile.local Caddyfile
bash scripts/setup.sh   # validates your configuration
docker compose up -d

Troubleshooting

ProblemCauseFix
Port already in useAnother process on 80 or 443lsof -i :<port> then stop the process
API can't connect to DBDatabase still initializingWait 30s, check docker compose logs db
Browser certificate warningmkcert CA not installedRun mkcert -install and restart the installer
Keycloak config import failsKeycloak not healthy yetCheck docker compose logs keycloak — it needs ~60s to start
# Check service status
docker compose ps

# View logs for a specific service
docker compose logs api
docker compose logs keycloak
docker compose logs keycloak-config-importer

# Restart a single service
docker compose restart api

# Shell into a container
docker compose exec api sh

Clean up

# Stop containers, keep data for next time
docker compose down

# Stop containers and delete all data (clean slate)
docker compose down -v

Next steps

SDK Quickstart

Connect your application to Openfuse and protect your first call.

Deploy to cloud

Ready to share with your team? Deploy on a VM with a real domain.

Configuration reference

Every environment variable explained.

Overview

Deploy Openfuse on your own infrastructure. Full control over your circuit breaker platform with Docker Compose, Kubernetes, or any container orchestrator.

Deploy to Cloud

Deploy a self-hosted Openfuse instance on a cloud VM or from a CI pipeline. Non-interactive setup with automatic secret generation for team evaluation and staging environments.

On this page

PrerequisitesStart OpenfuseInstall a specific versionWhat happens on first startupVerify it worksSign in and create your first companyConnect the SDKManual setup (alternative)TroubleshootingClean upNext steps