Deploy Unleash with the unleash-feature-flags template

Stand up Unleash, an open-source feature-flags and experimentation platform, on a single Quake AI instance using the validated OpenTofu template unleash-feature-flags. You apply the template, log in and change the default admin password, create a project and a feature flag, connect a client SDK to read it, and put a domain in front for production use.

Unleash keeps your team's feature flags on infrastructure you own. You run it yourself; this is a self-hosted tool you operate, not a managed multi-tenant service.

Prerequisites#

You need:

• OpenTofu 1.6.0 or later (or Terraform 1.6.0 or later) installed locally.
• Your OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An SSH keypair that already exists in your project. Record its name for the key_name variable.
• A copy of the unleash-feature-flags template directory from the template reference page.
• Node.js installed locally, to run the client SDK example in this walkthrough.

Step 1: Apply the template#

Copy the template's example variables file and set key_name:

cp terraform.tfvars.example terraform.tfvars

key_name = "YOUR_KEY_NAME"

Initialize, preview, and apply:

tofu init
tofu plan
tofu apply

OpenTofu provisions a private network, a router, a security group, a block volume mounted at /var/lib/docker, an instance, and a floating IP. On first boot, cloud-init installs Docker Engine, generates the PostgreSQL password into /opt/unleash/.env, and starts both postgres and unleash: no held-back service waits on manual configuration.

Read the outputs and record floating_ip and app_url:

tofu output

Step 2: Log in and change the admin password#

1. Open app_url from the previous step (http://YOUR_FLOATING_IP:4242). The raw app port is restricted to the private network by default; tunnel over SSH if you have not opened app_allowed_cidr to your workstation.
2. Sign in with admin / unleash4all.
3. Go to Admin settings > My profile > Change password and set a new password.

Step 3: Create a project and a feature flag#

1. Select New project, name it (for example checkout-service), and create it.
2. Inside the project, select New feature flag, name it new-checkout-flow, and set the flag type to Release.
3. In the development environment, add a Standard strategy with a 50% gradual rollout, then toggle the environment on.

Step 4: Connect a client SDK#

From the Unleash admin UI, go to Admin settings > API access and generate a client API token scoped to your project and the development environment.

Install the Node.js SDK in a small test project:

npm install unleash-client

Initialize the SDK and check the flag:

const { initialize, isEnabled } = require("unleash-client");

const unleash = initialize({
  url: "http://YOUR_FLOATING_IP:4242/api/",
  appName: "checkout-service",
  customHeaders: { Authorization: "YOUR_CLIENT_API_TOKEN" },
});

unleash.on("synchronized", () => {
  console.log("new-checkout-flow enabled:", isEnabled("new-checkout-flow"));
});

The SDK polls Unleash on an interval and caches flag state locally, so your application keeps working with the last known state if Unleash is briefly unreachable.

Step 5: Serve Unleash over HTTPS for production use#

Unleash has no auth-callback URL that blocks first boot, so this step is recommended for production use rather than required to get started.

1. Create a DNS A record for your domain (for example flags.example.com) pointing at YOUR_FLOATING_IP. Follow How to point a domain at a Quake AI resource. Wait until it resolves:

dig +short flags.example.com

1. SSH to the instance and create /opt/unleash/Caddyfile:

flags.example.com {
  reverse_proxy 127.0.0.1:4242
}

1. Add Caddy to /opt/unleash/docker-compose.yml:

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    network_mode: host
    volumes:
      - /opt/unleash/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
volumes:
  caddy_data:

For background on certificates, see How to issue and auto-renew a TLS certificate with Let's Encrypt.

1. Edit /opt/unleash/.env and set the public URL, then restart Unleash:

UNLEASH_URL=https://flags.example.com

cd /opt/unleash
sudo docker compose up -d

UNLEASH_URL affects links in outgoing emails and integrations; it does not gate login or SDK access, so this step is safe to defer until you are ready to serve the app on a stable domain.

What you built#

• Applied the unleash-feature-flags template to provision a network, security group, data volume, instance, and floating IP, with PostgreSQL and Unleash both started automatically by cloud-init
• Changed the default admin password immediately after first login
• Created a project and a feature flag with a gradual rollout strategy
• Connected the Node.js client SDK to read the flag with a scoped API token
• Served Unleash over HTTPS through an optional Caddy reverse proxy for production use

Scope of this deployment#

This template runs a single-VM Unleash host, not a managed feature-flags cloud. The instance is CPU-only and runs in one region, and it bundles PostgreSQL as a container on the same host. You operate the instance, Docker, Unleash, the database, and the data volume yourself: back them up, patch them, and snapshot the volume before you resize or rebuild. For a larger team, move PostgreSQL onto its own instance and size the app host up.

Next steps#

• Unleash feature-flags template: the template reference, parameters, and resource map
• Self-managed PostgreSQL template: the database to point at when you outgrow the bundled one
• Infisical secrets management deployment: a natural pairing for storing the client API token this walkthrough generated
• Security hardening checklist: tighten SSH access and exposure before you connect production traffic

Clean up#

When you no longer need the deployment, destroy everything the template created:

tofu destroy

Then remove the DNS A record you created in step 5, if you added one. Because Unleash and its database both live on the instance and its attached volume, tofu destroy removes them along with the infrastructure.