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 toggles, 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