Skip to main content

Getting Started

This section only applies if you plan to self-host Unleash. If you are looking for our hosted solution you should head over to www.getunleash.io

Requirements

You will need:

Start Unleash server

Whichever option you choose to start Unleash, you must specify a database URI (it can be set in the environment variable DATABASE_URL). If your database server is not set up to support SSL you'll also need to set the environment variable DATABASE_SSL to false


Once the server has started, you will see the message:

Unleash started on http://localhost:4242

To run multiple replicas of Unleash simply point all instances to the same database.

Unleash v4: The first time Unleash starts it will create a default user which you can use to sign-in to you Unleash instance and add more users with:

  • username: admin
  • password: unleash4all

If you'd like the default admin user to be created with a different username and password, you may define the following environment variables when running Unleash:

  • UNLEASH_DEFAULT_ADMIN_USERNAME
  • UNLEASH_DEFAULT_ADMIN_PASSWORD

The way of defining these variables may vary depending on how you run Unleash.

Option 1 - use Docker

Useful links:

Steps:

  1. Create a network by running docker network create unleash
  2. Start a postgres database:
docker run -e POSTGRES_PASSWORD=some_password \
-e POSTGRES_USER=unleash_user -e POSTGRES_DB=unleash \
--network unleash --name postgres postgres
  1. Start Unleash via docker:
docker run -p 4242:4242 \
-e DATABASE_HOST=postgres -e DATABASE_NAME=unleash \
-e DATABASE_USERNAME=unleash_user -e DATABASE_PASSWORD=some_password \
-e DATABASE_SSL=false \
--network unleash --pull=always unleashorg/unleash-server

Option 2 - use Docker-compose

Steps:

  1. Clone the Unleash repository.
  2. Run docker compose up -d in repository root folder.

Option 3 - from Node.js

  1. Create a new folder/directory on your development computer.

  2. From a terminal/bash shell, install the dependencies:

    npm init
    npm install unleash-server --save
  3. Create a file called server.js, paste the following into it and save.

    const unleash = require('unleash-server');

    unleash
    .start({
    db: {
    ssl: false,
    host: 'localhost',
    port: 5432,
    database: 'unleash',
    user: 'unleash_user',
    password: 'password',
    },
    server: {
    port: 4242,
    },
    })
    .then((unleash) => {
    console.log(
    `Unleash started on http://localhost:${unleash.app.get('port')}`,
    );
    });
  4. Run server.js:

    node server.js

Create an api token for your client

Test your server and create a sample API call

Once the Unleash server has started, go to localhost:4242 in your browser. If you see an empty list of feature flags, try creating one with curl from a terminal/bash shell:

curl --location -H "Authorization: <apitoken from previous step>" \
--request POST 'http://localhost:4242/api/admin/features' \
--header 'Content-Type: application/json' --data-raw '{\
"name": "Feature.A",\
"description": "Dolor sit amet.",\
"type": "release",\
"enabled": false,\
"stale": false,\
"strategies": [\
{\
"name": "default",\
"parameters": {}\
}\
]\
}'

Version check

  • Unleash checks that it uses the latest version by making a call to https://version.unleash.run.
    • This is a cloud function storing instance id to our database for statistics.
  • This request includes a unique instance id for your server.
  • If you do not wish to check for upgrades define the environment variable CHECK_VERSION to anything else other than true before starting, and Unleash won't make any calls
    • export CHECK_VERSION=false