Install Label Studio Enterprise on-premises using Docker

Beta documentation: Label Studio Enterprise v2.0.0 is currently in Beta. As a result, this documentation might not reflect the current functionality of the product.

Install Label Studio Enterprise on-premises if you need to meet strong privacy regulations, legal requirements, or want to manage a custom installation on your own infrastructure using Docker or public cloud. To deploy Label Studio Enterprise on Amazon AWS in a Virtual Private Cloud (VPC), see Install Label Studio Enterprise on AWS Private Cloud.

You can run Label Studio Enterprise in an airgapped environment, and no data leaves your infrastructure. See Secure Label Studio for more details about security and hardening for Label Studio Enterprise.

To install Label Studio Community Edition, see Install and Upgrade Label Studio. This page is specific to the Enterprise version of Label Studio.

System requirements

You can install Label Studio on a Linux, Windows, or MacOSX machine running Python 3.6 or later.

Port requirements

Label Studio expects port 8080 to be open by default. To use a different port, specify it when starting Label Studio. See Start Label Studio.

Server requirements

Allocate disk space according to the amount of data you plan to label. As a benchmark, 1 million labeling tasks take up approximately 2.3GB on disk when using the SQLite database. 50GB of disk space is recommended for production instances.

Use a minimum of 8GB RAM, but 16GB RAM is recommended. for example, t3.large or t3.xlarge on Amazon AWS.

For more on using Label Studio at scale and labeling performance, see Start Label Studio.

Software requirements

PostgreSQL version 11.5 or SQLite version 3.35 or higher.

Install Label Studio Enterprise using Docker

  1. Pull the latest image
  2. Add the license file
  3. Start using Docker. To start the server in development mode, start using Docker Compose.


Make sure you have an authorization token to retrieve Docker images and a current license file. If you are a Label Studio Enterprise customer and do not have access, contact us to receive an authorization token and a copy of your license file.

Pull the latest image

You must be authorized to use Label Studio Enterprise images.

  1. Set up the Docker login to retrieve the latest Docker image:
    docker login --username heartexlabs

When prompted to enter the password, enter the token here. If Login Succeeded, a ~/.docker/config.json file is created with the authorization settings.
2. Pull the latest Label Studio Enterprise image:

docker pull heartexlabs/heartex:latest

Note: In some cases, you might need to use sudo to log in or pull images.

Add the license file

After you retrieve the latest Label Studio Enterprise image, add the license file. You can’t start the Docker image without a license file.

  1. Create a working directory called heartex and place the license file in it.

    mkdir -p heartex
    cd heartex
  2. Move the license file, license.txt, to the heartex directory.

Start using Docker

To run Label Studio Enterprise in production, start it using Docker. This configuration allows you to link Label Studio with external databases and services.

  1. Create a file, heartex/env.list with the required environmental variables:

    # The main server URL (must be a full path like protocol://host:port)
    # Auxiliary hostname URL: some platform functionality requires URIs generation with specified hostname, 
    # in case HEARTEX_HOSTNAME is not accessible from server side, use this variable to specify server host
    # PostgreSQL database name
    # PostgreSQL database user
    # PostgreSQL database password
    # PostgreSQL database host
    # PostgreSQL database port
    # PostgreSQL SSL mode
    # Specify Postgre SSL certificate
    # Redis location e.g. redis://[:password]@localhost:6379/1
    # Redis database
    # Redis password
    # Redis socket timeout
    # Use Redis SSL connection
    # Require certificate
    # Specify Redis SSL certificate
  2. After you set all the environment variables, run Docker exposing port 8080:

docker run -d \
-p 8080:8080 \
--env-file env.list \
-v `pwd`/license.txt:/heartex/web/htx/settings/license_docker.txt \
-v `pwd`/logs:/var/log/heartex \
-v `pwd`/postgre-ca-bundle.pem:/etc/ssl/certs/postgre-ca-bundle.pem \
-v `pwd`/redis-ca-bundle.pem:/etc/ssl/certs/redis-ca-bundle.pem \
--name heartex \

Note: If you expose port 80, you must start Docker with sudo.

Start using Docker Compose

To run Label Studio Enterprise in development mode, start Label Studio using Docker Compose and local PostgreSQL and Redis servers to store data and configurations.

Follow these instructions only if you plan to use Label Studio Enterprise in development mode. Otherwise, see Start Using Docker on this page.


Make sure Docker Compose is installed on your system.

Start Label Studio Enterprise in development mode

  1. Create a configuration file heartex/config.yml with the following content:
version: '3'

    image: postgres:11.5
    hostname: db
    restart: always
      - ./postgres-data:/var/lib/postgresql/data
      - ./logs:/var/log/heartex
      - 5432:5432
    image: heartexlabs/heartex:latest
    container_name: heartex
      - ./license.txt:/heartex/web/htx/settings/license_docker.txt
      - HEARTEX_HOSTNAME=http://localhost:8080
      - POSTGRE_NAME=postgres
      - POSTGRE_USER=postgres
      - POSTGRE_PORT=5432
      - POSTGRE_HOST=db
      - REDIS_LOCATION=redis:6379
    command: ["./deploy/wait-for-postgres.sh", "db", "supervisord"]
      - 8080:8080
      - redis
      - db
      - redis
    image: redis:5.0.6-alpine
    hostname: redis
      - "./redis-data:/data"
      - 6379:6379

If you have existing services running on ports 5432, 6379, or 8080, update the config.yml file to use different ports.
2. Start all servers using docker-compose:

docker-compose -f config.yml up
  1. Open http://localhost:8080 in a browser and start using Label Studio Enterprise in development mode.

Data persistence

When the Label Studio Enterprise server runs with docker-compose, all essential data is stored inside the container. The following local file storage directories are linked to the container volumes to make sure data persists:

The integrity of these folders ensures that your data is not lost even if you completely stop and remove all running containers and images. The ./postgres-data files are specific to the PostgreSQL version. The current supported PostgreSQL version is 11.5.

Update Label Studio Enterprise

  1. Back up your existing container.
  2. Pull the latest image
  3. Update the container

Get the Docker image version

To check the version of the Label Studio Enterprise Docker image, run docker ps on the host.

Run the following command as root or using sudo and review the output:

$ docker ps
CONTAINER ID        IMAGE                        COMMAND                  CREATED             STATUS              PORTS                    NAMES
b1dd57a685fb        heartexlabs/heartex:latest   "./deploy/start.sh"      36 minutes ago      Up 36 minutes>8000/tcp   heartex

The image column displays the Docker image and version number. The image heartexlabs/heartex:latest is using the version latest.

Back up Label Studio Enterprise

Back up your Label Studio Enterprise Docker container before you upgrade your version and for disaster recovery purposes.

  1. From the command line, run Docker stop to stop the currently running container with Label Studio Enterprise:

    docker stop heartex
  2. Rename the existing container to avoid name conflicts when updating to the latest version:

    docker rename heartex heartex-backup

You can then treat the heartex-backup image as a backup.

Pull a new image

After backing up your existing container, pull the latest image of Label Studio Enterprise from the Docker registry.

docker pull heartexlabs/heartex:latest

Update the container

After you pull the latest image, update your Label Studio Enterprise container:

docker run -d \
-p $EXPOSE_PORT:8080 \
-v `pwd`/license.txt:/heartex/web/htx/settings/license_docker.txt \
-v `pwd`/logs:/var/log/heartex \
-v `pwd`/postgre-ca-bundle.pem:/etc/ssl/certs/postgre-ca-bundle.pem \
-v `pwd`/redis-ca-bundle.pem:/etc/ssl/certs/redis-ca-bundle.pem \
--name heartex \

Restore from a backed up container

If you decide to roll back to the previously backed up version of Label Studio Enterprise, stop and remove the new container and replace it with the backup.

  1. From the command line, stop the latest running container and remove it:

    docker stop heartex && docker rm heartex
  2. Rename the backup container:

    docker rename heartex-backup heartex
  3. Start the backup container:

    docker start heartex