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.

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

Alternatively, you can provide a name and email address for the initial admin user:

  • UNLEASH_DEFAULT_ADMIN_NAME
  • UNLEASH_DEFAULT_ADMIN_EMAIL

Unleash will then create the admin account using the provided name and email address. Instead of setting an initial password during account creation, an email will be sent to the specified address with a link for the new admin user to securely set their 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