Introduction
Unleash is an open-source platform dedicated to managing feature flags (or feature toggles), essential for progressive deployments, A/B tests, and quick rollbacks without redeploying your code. In 2026, with the rise of microservices architectures and advanced CI/CD pipelines, Unleash has become an indispensable tool for DevOps and development teams.
Why use it? Imagine rolling out a new feature to just 10% of users, measuring its impact, and then activating it globally or disabling it with a single click—no urgent hotfixes required. This beginner tutorial guides you from Docker deployment to integration in a Node.js app, with complete configs and working code. By the end, you'll master the basics to supercharge your releases. (About 120 words)
Prerequisites
- Docker and Docker Compose installed (version 20+ recommended)
- Node.js 18+ for client examples
- Basic terminal and JavaScript knowledge
- A code editor like VS Code
Create the docker-compose.yml file
version: '3.8'
services:
unleash-server:
image: unleashorg/unleash-server:6.5.0
ports:
- "8080:8080"
environment:
DATABASE_URL: postgres://unleash_user:password@db:5432/unleash
NODE_ENV: production
INITIAL_ADMIN_USER:
- email=user@unleash.local
userName=admin
password=unleash4fun
depends_on:
- db
restart: always
db:
image: postgres:15
environment:
POSTGRES_DB: unleash
POSTGRES_USER: unleash_user
POSTGRES_PASSWORD: password
volumes:
- unleash_db:/var/lib/postgresql/data
restart: always
volumes:
unleash_db:This docker-compose file deploys Unleash with an integrated PostgreSQL database. It exposes port 8080 for the web interface and configures an initial admin user (email: user@unleash.local, password: unleash4fun). Note: In production, use secrets for environment variables and a persistent volume for the database.
Launch Unleash locally
Save the code above to a docker-compose.yml file in the root of a project folder. Open a terminal and run docker compose up -d. Wait 1-2 minutes for the database to initialize.
Access http://localhost:8080 and log in with the admin credentials. You'll see an empty dashboard ready for your first feature flags. Check logs with docker compose logs -f if needed.
Install the Node.js client
mkdir unleash-client-demo
cd unleash-client-demo
npm init -y
npm install @unleash/proxy @unleash/sdk
npm install typescript @types/node ts-node --save-devThis script initializes a Node.js project and installs the official Unleash SDK for proxy and client. The proxy is ideal for secure server-side environments, avoiding public exposure of the Unleash API. Use TypeScript for type safety.
Configure the client proxy
Create a unleash-proxy.js file to relay calls to Unleash. This hides your instance and handles flag polling. In the Unleash UI, create a project named 'default', then a feature toggle named 'ma-nouvelle-fonction' enabled for 100% of traffic (using the 'default' strategy).
Implement the Unleash proxy
const express = require('express');
const { ProxyEngine } = require('@unleash/proxy');
const app = express();
app.use(express.json());
// Config proxy
new ProxyEngine({
unleashUrl: 'http://localhost:8080/api/',
proxySecret: 'ceci-est-un-secret-changez-le',
proxyPort: 4242,
unleashAppName: 'unleash-proxy',
metrics: true,
}).then((engine) => {
engine.start();
console.log('Proxy démarré sur http://localhost:4242');
}).catch(console.error);
app.listen(3001, () => {
console.log('Serveur proxy sur port 3001');
});This Express proxy relays client requests to Unleash on localhost:8080. It uses a secret for authentication and exposes an endpoint on /proxy. Run it with node unleash-proxy.js. Change the secret in production and enable HTTPS.
Client app example with SDK
const { initialize } = require('@unleash/sdk');
async function demo() {
const config = {
url: 'http://localhost:4242/proxy',
clientKey: 'default:development:ceci-est-un-secret-changez-le',
appName: 'client-demo',
environment: 'default',
refreshInterval: 5000,
};
const unleash = initialize(config);
await unleash.start();
// Vérifier un flag
if (unleash.isEnabled('ma-nouvelle-fonction')) {
console.log('✅ Fonctionnalité activée !');
} else {
console.log('❌ Fonctionnalité désactivée');
}
// Stop propre
setTimeout(() => {
unleash.stop();
}, 10000);
}
demo();This script initializes the SDK client, points it to the proxy, and checks the 'ma-nouvelle-fonction' flag. Run node client-demo.js after starting the proxy. The client polls for updates every 5 seconds. In production, handle connection errors and fallbacks.
Test in the Unleash interface
In the UI (localhost:8080), edit 'ma-nouvelle-fonction': add a 'gradual-rollout' strategy at 20% and a 'userId' context. Test with curl "http://localhost:4242/proxy?token=ceci-est-un-secret-changez-le&context.userId=123". You'll see the flag change dynamically without restarting the app.
Cleanup and stop script
docker compose down -v
docker volume rm $(docker volume ls -q | grep unleash)This script stops the containers and removes volumes for a clean reset. Use -v to avoid persistent data in development. Verify with docker ps that everything is cleaned up.
Best practices
- Secure secrets: Use Docker Secrets or Vault for DATABASE_URL and proxySecret in production.
- Monitor metrics: Enable Prometheus in Unleash to track flag activations.
- Contextual strategies: Always use userId or sessionId for targeted rollouts.
- Client fallbacks: Implement default values if the SDK fails.
- Automated tests: Integrate E2E tests that mock Unleash with
nock.
Common errors to avoid
- Forgetting to wait for the DB: Unleash fails if Postgres isn't ready—add
healthcheckto docker-compose. - Secret mismatch: Client and proxy must share the same secret, or you'll get 401 Unauthorized.
- Port conflicts: Check
netstat -tuln | grep 8080beforeup. - No HTTPS in prod: Expose via reverse proxy (Nginx/Traefik) with Let's Encrypt certs.
Next steps
Explore the official Unleash docs, integrate with Kubernetes using Helm charts, or check out Learni DevOps training. For advanced setups (multi-tenant, SSO), consider Unleash Enterprise.