logofirst
logofirst

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 in the cloud, you can use Kubernetes and Helm. See Deploy Label Studio Enterprise on Kubernetes.

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 the server using Docker Compose.

Prerequisites

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.

Make sure Docker Compose is installed on your system.

After you install Label Studio Enterprise, the app is automatically connected to the following running services:

Pull the latest image

You must be authorized to access 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. If login succeeds, a ~/.docker/config.json file is created with the authorization settings.

If you have default registries specified when logging into Docker, you might need to explicitly specify the registry: docker login --username heartexlabs docker.io.

  1. Pull the latest Label Studio Enterprise image:
    docker pull heartexlabs/label-studio-enterprise:latest

    Note: 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 label-studio-enterprise and place the license file in it.
    mkdir -p label-studio-enterprise
    cd label-studio-enterprise
  2. Move the license file, license.txt, to the label-studio-enterprise directory.

Start using Docker Compose

To run Label Studio Enterprise in production, start it using Docker compose. This configuration lets you connect Label Studio to external databases and services.

  1. Create a file, label-studio-enterprise/env.list with the required environmental variables:

    # Specify the path to the license file. 
    # Alternatively, it can be a URL like LICENSE=https://lic.heartex.ai/db/20210203-1234-ab123456.lic
    LICENSE=/label-studio-enterprise/license.txt
    
    # Database engine (PostgreSQL by default)
    DJANGO_DB=default
    
    # Default configuration
    DJANGO_SETTINGS_MODULE=htx.settings.label_studio
    
    # PostgreSQL database name
    POSTGRE_NAME=postgres
    
    # PostgreSQL database user
    POSTGRE_USER=postgres
    
    # PostgreSQL database password
    POSTGRE_PASSWORD=
    
    # PostgreSQL database host
    POSTGRE_HOST=db
    
    # PostgreSQL database port
    POSTGRE_PORT=5432
    
    # Optional: PostgreSQL SSL mode
    POSTGRE_SSL_MODE=require
    
    # Optional: Specify Postgre SSL certificate
    POSTGRE_SSLROOTCERT=postgre-ca-bundle.pem
    
    # Redis location e.g. redis://[:password]@localhost:6379/1
    REDIS_LOCATION=localhost:6379
    
    # Optional: Redis database
    REDIS_DB=1
    
    # Optional: Redis password
    REDIS_PASSWORD=12345
    
    # Optional: Redis socket timeout
    REDIS_SOCKET_TIMEOUT=3600
    
    # Optional: Use Redis SSL connection
    REDIS_SSL=1
    
    # Optional: Require certificate
    REDIS_SSL_CERTS_REQS=required
    
    # Optional: Specify Redis SSL certificate
    REDIS_SSL_CA_CERTS=redis-ca-bundle.pem
    
    # Optional: Specify SSL termination certificate & key
    # Files should be placed in the directory "certs" at the same directory as docker-compose.yml file
    NGINX_SSL_CERT=/certs/cert.pem
    NGINX_SSL_CERT_KEY=/certs/cert.key
  2. After you set all the environment variables, create the following docker-compose.yml:

version: '3.3'

services:
  app:
    stdin_open: true
    tty: true
    image: heartexlabs/label-studio-enterprise:latest
    ports:
      - 80:8085
      - 443:8086
    expose:
      - "80"
      - "443"
    env_file:
      - env.list
    volumes:
      - ./license.txt:/label_studio_enterprise/license.txt:ro
      - ./mydata:/label-studio/data:rw
      - ./certs:/certs:ro
    working_dir: /label-studio-enterprise

  rqworkers:
    image: heartexlabs/label-studio-enterprise:latest
    env_file:
      - env.list
    volumes:
      - ./license.txt:/label_studio_enterprise/license.txt
      - ./mydata:/label-studio/data:rw
    working_dir: /label-studio-enterprise
    command: [ "python3", "/label-studio-enterprise/label_studio_enterprise/manage.py", "rqworker", "default" ]

volumes:
  static: {}
  1. Run Docker Compose:
docker-compose up

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

  1. If you’re starting Docker for the first time, you must run the database migrations to make sure that the postgres database already exists:
docker-compose run app python3 label_studio_enterprise/manage.py migrate

Get the Docker image version

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

From the command line, run the following as root or using sudo and review the output:

$ docker ps
03b88eebdb65   heartexlabs/label-studio-enterprise:latest   "uwsgi --ini deploy/…"   36 hours ago   Up 36 hours   0.0.0.0:80->8000/tcp   label-studio-enterprise_app_1

In this example output, the image column displays the Docker image and version number. The image heartexlabs/label-studio-enterprise:latest is using the version latest.