Getting started

Unleash offers several hosting options, including fully self-hosted setups. This guide helps you set up Unleash Open Source or Unleash Enterprise in your own environment using Docker.

Alternatively, for Unleash Enterprise, you can sign up for a cloud-hosted instance.

You can set up Unleash in your environment using two main approaches with Docker:

• Docker Compose: This method relies on a Docker Compose file to define and manage the Unleash server and its database, simplifying the setup and startup process.
• Docker CLI: This method gives you more direct control by using individual docker commands to set up the network and run the Unleash and database containers separately.

Start Unleash server

Using Docker Compose

To start the Unleash server, clone the Unleash repository and start the server with Docker Compose:

$
git clone git@github.com:Unleash/unleash.git
$
$
cd unleash
$
docker compose -f docker-compose-enterprise.yml up -d

Using Docker CLI

This method involves running separate containers for PostgreSQL and Unleash and connecting them manually via a Docker network.

Create Docker network

This allows the Unleash container to communicate with the database container by name.

$
docker network create unleash

Start PostgreSQL database container

This command starts a PostgreSQL container, sets up the necessary user, unleash_user and database unleash, assigns a password, and connects it to the unleash network.

$
docker run -d \
>
  -e POSTGRES_PASSWORD=your_secure_password \
>
  -e POSTGRES_USER=unleash_user \
>
  -e POSTGRES_DB=unleash \
>
  --network unleash \
>
  --name postgres \
>
  postgres:17 # or any 14+ version

Start Unleash server container

This command starts the Unleash server, maps port 4242 on your host to the container, connects to the PostgreSQL database you started, disables database SSL, connects to the unleash network, and ensures you have the latest image.

$
docker run -d -p 4242:4242 \
>
  -e DATABASE_HOST=postgres \
>
  -e DATABASE_NAME=unleash \
>
  -e DATABASE_USERNAME=unleash_user \
>
  -e DATABASE_PASSWORD=your_secure_password \
>
  -e DATABASE_SSL=false \
>
  --network unleash \
>
  --name unleash \
>
  --pull=always \
>
  unleashorg/unleash-enterprise

Log in to the Unleash Admin UI

Test your server connection

You can quickly test if your server is running and accepting API requests using curl. For example, you can attempt creating a feature flag via the Admin API. Replace <API_TOKEN> with a valid API token and adjust the URL http://localhost:4242 if needed.

$
curl --location --request POST 'http://localhost:4242/api/admin/features' \
>
--header 'Authorization: <API_TOKEN>' \
>
--header 'Content-Type: application/json' \
>
--data-raw '{
>
  "name": "Test Feature Flag",
>
  "description": "Feature flag for testing",
>
  "type": "release",
>
  "enabled": false,
>
  "stale": false,
>
  "strategies": [
>
    {
>
      "name": "default",
>
      "parameters": {}
>
    }
>
  ]
>
}'

Disable version check

By default, your self-hosted Unleash instance periodically checks https://version.unleash.run to inform you about new releases. This check sends a unique, anonymous instance ID.

If you prefer to disable this version check, set the environment variable CHECK_VERSION to false before starting the Unleash server.