Getting Started

Unleash is an open source feature flag management platform that lets you toggle features on and off, run A/B tests, and perform gradual rollouts without redeploying your application. Available as an open web service in Eyevinn Open Source Cloud, Unleash supports 30+ official SDKs for both frontend and backend applications. This tutorial walks you through the steps to get started.

Prerequisites

Step 1: Create a PostgreSQL database

Unleash requires a PostgreSQL database to store feature flags, strategies, user data, and configuration. Navigate to the PostgreSQL service in the Eyevinn OSC web console. Click on the button "Create psql-db" and enter a name for the instance and a password.

Based on the IP and port, the URI to your PostgreSQL database is postgres://postgres:<password>@<IP>:<PORT>/postgres.

Step 2: Store connection URL and API tokens as secrets

It is a good practice to store credentials as secrets and refer to them when creating an instance. Navigate to the Unleash service in Eyevinn Open Source Cloud web console. Go to the tab "Service Secrets" and click on "New Secret".

Create the following secrets:

  • dburl with the PostgreSQL connection URL from Step 1 (e.g. postgres://postgres:mypassword@172.232.131.169:10505/postgres)
  • frontendtoken with a token string for frontend SDK authentication (e.g. my-frontend-token)
  • backendtoken with a token string for backend/server-side SDK authentication (e.g. my-backend-token)

Step 3: Create the Unleash instance

Go to the tab "My unleashes" and click on "Create unleash". Fill in:

  • Name: a name for your instance (alphanumeric only)
  • DatabaseUrl: {{secrets.dburl}}
  • InitFrontendApiTokens: {{secrets.frontendtoken}}
  • InitBackendApiTokens: {{secrets.backendtoken}}

Click on the instance card when the status is green and "running".

Step 4: Log in to Unleash

Open the instance URL in your browser. Login using the default admin credentials:

username: admin

password: unleash4all

Important: Change the default password immediately after your first login. Navigate to the admin settings to update the admin password.

Step 5: Create your first feature flag

Once logged in, click "New feature flag" to create your first toggle. You can configure:

  • Flag type: Release, Experiment, Operational, Kill switch, or Permission
  • Activation strategies: Gradual rollout, UserIDs, IPs, Hostnames, or custom strategies
  • Environments: Manage flags across development, staging, and production

Step 6: Connect your application

Use one of the 30+ official Unleash SDKs to connect your application.

Backend SDK example (Node.js):

const { initialize } = require('unleash-client');

const unleash = initialize({
  url: 'https://<your-instance-url>/api/',
  appName: 'my-app',
  customHeaders: { Authorization: '<your-backend-api-token>' },
});

unleash.on('ready', () => {
  if (unleash.isEnabled('my-feature')) {
    console.log('Feature is enabled!');
  }
});

Frontend SDK example (React):

import { FlagProvider } from '@unleash/proxy-client-react';

const config = {
  url: 'https://<your-instance-url>/api/frontend/',
  clientKey: '<your-frontend-api-token>',
  appName: 'my-react-app',
};

function App() {
  return (
    <FlagProvider config={config}>
      <YourComponent />
    </FlagProvider>
  );
}

Replace <your-instance-url> with your Unleash instance URL and use the API tokens you configured in Step 2.

Using the CLI

You can also create an Unleash instance using the OSC CLI:

# First create a PostgreSQL database
osc create birme-osc-postgresql mydb -o PostgresPassword="mypassword"

# Create the Unleash instance
osc create unleash-unleash myunleash \
  -o DatabaseUrl="postgres://postgres:mypassword@<IP>:<PORT>/postgres" \
  -o InitFrontendApiTokens="my-frontend-token" \
  -o InitBackendApiTokens="my-backend-token"

Resources