How to Use Unleash: The Beginner's Guide (First Deploy, First Flag, the Context Lesson, and Gradual Rollouts)

CodexFuse Team · 2026-11-01T06:56:54.026Z · 14 min read

Unleash is the open-source feature flag platform you self-host: deploy it with Docker Compose, create your first flag, wire up the SDK, learn the context lesson that makes strategies work, and roll out features gradually — this beginner's guide covers the full arc.

Learning how to use Unleash is the fastest way to stop deploying code just to flip a feature on: Unleash is the open-source, self-hosted feature flag management platform that lets you turn features on and off, roll them out gradually, and kill a broken release in seconds — without touching your deployment pipeline. (Quick disambiguation: this guide is about Unleash the feature-flag platform at unleash.dev, not any lifestyle brand sharing the name.) If you can follow a Docker beginner guide, you can have Unleash running on your own server in under an hour — and this Unleash tutorial — the Unleash for beginners walkthrough — takes you from first deploy to first flag, through the SDK context lesson every beginner needs, to gradual rollouts across environments.

What Is Unleash?

Unleash is an open-source feature flag platform you host yourself: a central dashboard where you define feature flags, and SDKs in your applications that check those flags at runtime to decide which code path executes. Release v8.3.1 (published 2026-10-29) is the current tag on the v8 line, the GitHub repository Unleash/unleash carries roughly 13,920 stars, and since v8.0.0 the server source moved from Apache 2.0 to the GNU AGPLv3 license — while the official pre-built Docker images remain Apache 2.0 and the SDKs are unaffected (all facts verified 2026-11-01). The pitch is simple: LaunchDarkly-grade feature flagging on your own infrastructure, with your data staying in your database.

Unleash is not a SaaS dashboard with an agent — it is a server plus SDKs. The server (default port 4242) stores flag definitions in PostgreSQL, and each SDK fetches the flag configuration and evaluates it — backend SDKs evaluate locally against a context your app supplies, while frontend SDKs ask Unleash's frontend API. That split, and the context it depends on, is the one lesson that separates beginners who fight the tool from beginners who get it.

How Do I Use Unleash for the First Time?

Using Unleash for the first time follows a ten-step arc: deploy, lock down the login, create your first flag, mint the right API token, wire up an SDK, learn the context lesson, add a gradual-rollout strategy, respect environments, compare backends vs frontends, and plan the rollout discipline. Here is the arc in order, with the detail behind each step in the sections that follow:

1. Deploy Unleash with Docker Compose. Pair the official unleashorg/unleash-server image with PostgreSQL 16, set DATABASE_URL, and run docker compose up -d — the server listens on port 4242.
2. Change the default login immediately. The first-run credentials are admin / unleash4all — they are the #1 security miss on every Unleash install.
3. Create your first feature flag in the Default project. Name it after the feature (new-checkout), and enable it for the development environment first.
4. Learn the environment rule. Enabling a flag in development does not touch production — flags are evaluated per environment, and the API token you mint picks which one.
5. Mint a backend API token in the Admin UI. Go to Admin settings, Access control, API access — docs recommend creating tokens there over seeding them with environment variables.
6. Connect a backend SDK. npm install unleash-client, point it at http://YOUR-SERVER:4242/api with your backend token, and wait for the synchronized event before evaluating.
7. Learn the context lesson. Unleash does not know your users — your app must pass userId, sessionId, remoteAddress, and custom properties with every evaluation, or strategies silently evaluate to false.
8. Add a gradual-rollout strategy. Start with flexibleRollout at 10% stuck to userId, watch, then raise the percentage — never 0-to-100 in one jump.
9. Keep frontend and backend tokens apart. Browser apps use frontend tokens against /api/frontend; a backend token in client-side code is a leaked secret.
10. Kill the flag when the rollout finishes. A flag at 100% in production is technical debt — remove it from code once the feature is permanent.

What Is Feature Flag Management?

Feature flag management is the practice of wrapping new code in runtime switches so features can be turned on or off without a new deployment: deploy the code dark, flip the flag for 10% of users, watch the metrics, then ramp to 100% or roll back instantly. It decouples release (shipping code) from launch (exposing the feature), which is why every serious continuous-delivery team eventually adopts it.

Beginners often start with config files or environment variables, but those are not feature flags — they require restarts or redeploys to change, they cannot target specific users, and they have no audit trail. A real flag platform gives you per-environment state, targeting strategies (percentages, user lists, IPs), an audit log of who flipped what, and SDKs that evaluate flags in milliseconds. That is the gap Unleash fills on your own hardware.

What Do You Need Before You Start?

You need a server, Docker, and a domain name (optional but recommended): any small VPS with 2 GB of RAM comfortably runs Unleash plus PostgreSQL, since the server is a single Node.js process and the database does the heavy lifting. Unleash self hosted on a modest box is the sweet spot — no managed database, no Kubernetes, no per-seat bill. If you have never rented a server before, read what is VPS hosting first — Unleash is a textbook self-hosted workload.

Beyond the server you need nothing installed except Docker and Docker Compose, plus Node.js 22.13 or newer on your development machine if you plan to follow the SDK section. No Kubernetes, no managed services, no credit card — the open-source edition runs the whole flag lifecycle on one box.

How Do You Install Unleash with Docker?

You install Unleash with Docker by pairing the official unleashorg/unleash-server:8 image with PostgreSQL in a compose file, because Unleash requires a PostgreSQL database and v8.x needs PostgreSQL 15 or newer. Save this as compose.yml (or generate your own base with a Docker Compose generator and adapt it):

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: unleash
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: unleash
    volumes:
      - pgdata:/var/lib/postgresql/data
  unleash:
    image: unleashorg/unleash-server:8
    depends_on:
      - postgres
    environment:
      DATABASE_URL: postgres://unleash:change-me@postgres:5432/unleash
      UNLEASH_URL: http://localhost:4242
    ports:
      - "4242:4242"
volumes:
  pgdata:

Run docker compose up -d and open http://YOUR-SERVER-IP:4242: the setup asks you to create the admin account, and the documented first-run credentials are username admin, password unleash4all. This Unleash Docker pattern keeps the whole stack — server plus database — on one host with one file to back up. Change that password the moment you log in — a public Unleash with default credentials hands strangers the keys to every feature flag you own.

On API tokens, prefer the Admin UI over environment variables: the docs mark INIT_CLIENT_API_TOKENS as deprecated in favor of INIT_BACKEND_API_TOKENS, and the current recommendation is to mint tokens at Admin settings, Access control, API access — where "secure tokens" have been the default since v8.3.

How Do You Create Your First Feature Flag?

You create your first flag in the dashboard by opening the Default project, clicking New flag, and naming it after the feature — for example new-checkout — then enabling it for the development environment first. Unleash feature flags are simply named switches stored in PostgreSQL with per-environment state; the flag starts disabled everywhere, and the strategies tab is where you decide who gets it.

The beginner trap is environments: the open-source edition ships exactly two, development and production, plus a single project called Default — and a flag enabled in development is still off in production. This is a feature, not a bug: you test the rollout strategy in development, then promote the same flag to production with its own strategy, deliberately.

How Do You Connect the Unleash SDK to Your App?

You connect a Node.js backend by installing the official client with npm install unleash-client (note the package name — it is unleash-client, not a scoped @unleash/client), initializing one global instance with your backend token, and evaluating flags only after the client reports it is synchronized:

import { initialize } from 'unleash-client';

const unleash = initialize({
  url: 'http://YOUR-SERVER:4242/api',
  appName: 'my-node-app',
  customHeaders: { Authorization: '<YOUR_BACKEND_API_TOKEN>' },
});

unleash.on('synchronized', () => {
  const enabled = unleash.isEnabled('new-checkout', {
    userId: currentUser.id,
    sessionId: req.sessionID,
    remoteAddress: req.ip,
    properties: { region: currentUser.region },
  });
  if (enabled) {
    // new checkout code path
  } else {
    // old checkout code path
  }
});

Three SDK rules matter from day one: backend SDKs fetch the full flag configuration from /api and evaluate it locally, polling every 15 seconds by default — so your app keeps evaluating even on brief network hiccups. Until the first synchronized event fires, every flag evaluates to false, so never gate startup-critical code on a flag before sync. And keep one singleton client per process — the docs explicitly warn against creating instances per request.

What Is the Unleash Context — and Why Does It Matter?

The Unleash context is the set of facts your application passes with every flag evaluation — and it matters because Unleash does not know who your users are: strategies like "10% of users" or "these user IDs" can only work if your code supplies the user IDs, session IDs, IP addresses, and custom attributes at evaluation time. Skip the context and every targeting strategy silently evaluates to false, which is the single most common "my flag doesn't work" support question.

The context fields are appName and environment (static, set once per client), userId, sessionId, and remoteAddress (dynamic per evaluation), plus properties — a map of custom key-value pairs like region or plan tier — and currentTime. All fields are optional, and any strategy constraint referencing a field you did not supply simply returns false rather than erroring.

The money moment: pass context once, centrally, wherever your app calls isEnabled — a helper that always attaches the current user, session, IP, and tenant properties. Every strategy you will ever write reads from that one helper, so getting it right on day one pays off on every flag afterward.

How Do Gradual Rollouts Work in Unleash?

Gradual rollouts in Unleash work through activation strategies attached to a flag per environment: the modern flexibleRollout strategy takes a percentage, a stickiness key, and a group ID, and deterministically assigns each user to the on or off cohort. All Unleash strategies — percentages, user lists, IP targeting — are configured per flag per environment, so the same flag can dogfood internally in development while rolling out to 10% in production. Start at 10% with stickiness on userId so the same users see the feature consistently, watch your metrics, then raise to 25, 50, and 100 — a bad deploy at 10% is a footnote; at 100% it is an incident.

Beyond percentages, the built-in strategies cover the everyday targeting cases: userWithId enables a flag for an explicit list of user IDs (perfect for internal dogfooding), remoteAddress targets specific IP addresses (office and staging machines), and applicationHostname targets hostnames. Strategy variants add A/B testing on top — variants are now configured on the strategy per environment, and the SDK's getVariant returns which variant a user landed in.

Backend vs Frontend Tokens: Which One Does Your App Need?

Your app needs a backend token if it runs on a server and a frontend token if it runs in a browser: backend tokens authenticate against /api, fetch the full flag configuration, and evaluate locally — they are secrets and must never be exposed to end users. Frontend tokens authenticate against /api/frontend, where Unleash itself evaluates the flags and returns only the results for the requesting context.

The rule is absolute and the docs state it plainly: backend tokens cannot be used in frontend SDKs — use frontend tokens instead. Frontend SDKs like unleash-proxy-client never evaluate strategies themselves; they send the context to the frontend API and get back a yes/no. If you are building a React or Next.js app, create the frontend token in the Admin UI, keep the backend token on your API server, and never let the two cross.

Unleash vs LaunchDarkly (and the Other Self-Hosted Options)

Unleash vs LaunchDarkly is self-hosted open source vs commercial SaaS: LaunchDarkly is the managed category leader — you pay per seat and they run everything — while Unleash is the AGPL-licensed platform you run on your own server for the cost of a VPS. For teams comparing self hosted feature flags platforms, the decision usually comes down to data residency and pricing model, not feature checklists. If you want flag data inside your own network, or you refuse per-seat pricing, Unleash wins; if you want zero infrastructure and enterprise hand-holding, LaunchDarkly wins.

The self-hosted field has its own contenders, worth knowing before you commit: GrowthBook adds experimentation and A/B analytics on top of flags, Flipt is a leaner flag-only alternative with a strong GitOps story, and Flagsmith covers flags plus remote config with a hosted option. None of them are wrong — but Unleash has the largest SDK ecosystem and the longest self-hosting track record of the open-source bunch.

One boundary to draw: PostHog also ships feature flags, but they are a feature of a product-analytics suite — funnels, cohorts, session replay — while Unleash is a dedicated flag platform. If analytics is the job, read a PostHog beginner guide; if flags are the job, stay here.

Is Unleash Really Free?

Yes — the open-source edition is genuinely free and runs the complete flag lifecycle: unlimited flags, activation strategies with stickiness, the playground for testing strategies, impression data, export/import, webhooks, the Terraform provider, and every SDK. The limits are structural, not crippling: one project (called Default), two environments (development and production), basic roles, and community support.

What costs money is the Enterprise tier, and the split is honest: SSO and SCIM, service accounts, change-request approval workflows, release templates, automated release progression, flag and variant dependencies, login history, the advanced audit log, full analytics, and the multi-region Enterprise Edge are enterprise-only. For a team learning feature flags, the open-source ceiling is far above what you will hit in your first year.

How Do You Put Unleash Behind HTTPS?

You put Unleash behind HTTPS with a reverse proxy in front of port 4242 and set UNLEASH_URL to your public URL, because SDKs and the frontend API build callback URLs from that variable. The simplest path is a Caddy beginner guide setup: one Caddyfile block reverse-proxying your domain to localhost:4242 gets you automatic TLS with zero certificate management. Update UNLEASH_URL to https://flags.yourdomain.com in the compose file and recreate the container — then the admin UI and every SDK speak TLS.

Sources

• Unleash official documentation — Quickstart (get-started/quickstart) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Node.js SDK (sdks/node) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Configuring Unleash (deploy/configuring-unleash) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Activation strategies (concepts/activation-strategies) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Open-source vs Enterprise comparison (support/oss-comparison) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Upgrading Unleash, AGPLv3 license change (deploy/upgrading-unleash) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — API tokens and client keys (concepts/api-tokens-and-client-keys) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Unleash context (concepts/unleash-context) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Environments (concepts/environments) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Next.js implementation guide (guides/implement-feature-flags-in-nextjs) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Django implementation guide (guides/implement-feature-flags-in-django) — docs.getunleash.io — fetched 2026-11-01.
• Unleash official documentation — Demo walkthrough (guides/demo-walkthrough) — docs.getunleash.io — fetched 2026-11-01.
• GitHub — Unleash/unleash releases (v8.3.1, 2026-10-29) — api.github.com — fetched 2026-11-01.
• GitHub — Unleash/unleash repository (13,920 stars, AGPL-3.0) — api.github.com — fetched 2026-11-01.
• Docker Hub — unleashorg/unleash-server image tags — hub.docker.com — fetched 2026-11-01.
• omax.tech — "Unleash: Integrating Feature Flags in React Applications" — community guide — fetched 2026-11-01.

Frequently Asked Questions

Is Unleash open source?

Yes. The Unleash server source is open source under the GNU AGPLv3 since v8.0.0 (previously Apache 2.0), the official pre-built Docker images remain Apache 2.0, and the SDKs are unaffected by the license change. You can run the full platform on your own server without paying anyone.

Does Unleash need a database?

Yes — Unleash requires PostgreSQL to store flag definitions, strategies, and audit data; v8.x needs PostgreSQL 15 or newer. Set DATABASE_URL in your compose file and Unleash connects on startup; there is no SQLite or embedded-database mode.

Can I use Unleash flags in a browser app?

Yes, with a frontend token: browser SDKs authenticate against /api/frontend, where Unleash evaluates the flags server-side and returns only the results. Never ship a backend token in client-side code — backend tokens fetch the full flag configuration and are secrets.

How many environments does the free version include?

Two: development and production, inside a single project called Default. Which environment an SDK sees is decided by the API token it authenticates with, not by a client-side setting — mint one token per environment.

Is Unleash better than LaunchDarkly?

It depends on what you are buying: Unleash is the self-hosted open-source answer — your data, your server, no per-seat pricing — while LaunchDarkly is the fully managed commercial answer with deeper analytics and support. Teams that must keep flag data inside their own network, or that refuse seat-based pricing, pick Unleash.