Installation Guide (original) (raw)

A CVAT installation guide for different operating systems.

Quick installation guide

Before you can use CVAT, you’ll need to get it installed. The document below contains instructions for the most popular operating systems. If your system is not covered by the document it should be relatively straightforward to adapt the instructions below for other systems.

Probably you need to modify the instructions below in case you are behind a proxy server. Proxy is an advanced topic and it is not covered by the guide.

For access from China, read sources for users from China section.

Ubuntu 22.04/20.04 (x86_64/amd64)

sudo apt-get update  
sudo apt-get --no-install-recommends install -y \  
  apt-transport-https \  
  ca-certificates \  
  curl \  
  gnupg-agent \  
  software-properties-common  
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -  
sudo add-apt-repository \  
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \  
  $(lsb_release -cs) \  
  stable"  
sudo apt-get update  
sudo apt-get --no-install-recommends install -y \  
  docker-ce docker-ce-cli containerd.io docker-compose-plugin  
sudo groupadd docker  
sudo usermod -aG docker $USER

Log out and log back in (or reboot) so that your group membership is re-evaluated. You can type groups command in a terminal window after that and check if docker group is in its output.

git clone https://github.com/cvat-ai/cvat  
cd cvat

See alternatives if you want to download one of the release versions or use the wget or curl tools.

export CVAT_HOST=FQDN_or_YOUR-IP-ADDRESS  
CVAT_VERSION=dev docker compose up -d  
docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'

Choose a username and a password for your admin account. For more information please read Django documentation.

curl https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -  
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list'  
sudo apt-get update  
sudo apt-get --no-install-recommends install -y google-chrome-stable

Windows 10

git clone https://github.com/cvat-ai/cvat  
cd cvat

See alternatives if you want to download one of the release versions.

CVAT_VERSION=dev docker compose up -d  
sudo docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'

If you don’t have winpty installed or the above command does not work, you may also try the following: 

# enter docker image first  
docker exec -it cvat_server /bin/bash  
# then run  
python3 ~/manage.py createsuperuser

Choose a username and a password for your admin account. For more information please read Django documentation.

Mac OS Mojave

git clone https://github.com/cvat-ai/cvat  
cd cvat

See alternatives if you want to download one of the release versions or use the wget or curl tools.

CVAT_VERSION=dev docker compose up -d  
docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'

Choose a username and a password for your admin account. For more information please read Django documentation.

Advanced Topics

How to get CVAT source code

Git (Linux, Mac, Windows)

  1. Install Git on your system if it’s not already installed
    • Ubuntu:
sudo apt-get --no-install-recommends install -y git
  1. Clone CVAT source code from theGitHub repository.
    The command below will clone the default branch (develop):
git clone https://github.com/cvat-ai/cvat  
cd cvat

To clone specific tag, e.g. v2.1.0: 

git clone -b v2.1.0 https://github.com/cvat-ai/cvat  
cd cvat

Wget (Linux, Mac)

To download latest develop branch:

wget https://github.com/cvat-ai/cvat/archive/refs/heads/develop.zip
unzip develop.zip && mv cvat-develop cvat
cd cvat

To download specific tag:

wget https://github.com/cvat-ai/cvat/archive/refs/tags/v1.7.0.zip
unzip v1.7.0.zip && mv cvat-1.7.0 cvat
cd cvat

Curl (Linux, Mac)

To download the latest develop branch:

curl -LO https://github.com/cvat-ai/cvat/archive/refs/heads/develop.zip
unzip develop.zip && mv cvat-develop cvat
cd cvat

To download specific tag:

curl -LO https://github.com/cvat-ai/cvat/archive/refs/tags/v1.7.0.zip
unzip v1.7.0.zip && mv cvat-1.7.0 cvat
cd cvat

CVAT healthcheck command

The following command allows testing the CVAT container to make sure it works.

docker exec -t cvat_server python manage.py health_check

The expected output of a healthy CVAT container:

Cache backend: default   ... working
DatabaseBackend          ... working
DiskUsage                ... working
MemoryUsage              ... working
MigrationsHealthCheck    ... working
OPAHealthCheck           ... working

Deploying CVAT behind a proxy

If you deploy CVAT behind a proxy and do not plan to use any of serverless functionsfor automatic annotation, the exported environment variableshttp_proxy, https_proxy and no_proxy should be enough to build images. Otherwise please create or edit the file ~/.docker/config.json in the home directory of the user which starts containers and add JSON such as the following:

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy_server:port",
      "httpsProxy": "http://proxy_server:port",
      "noProxy": "*.test.example.com,.example2.com"
    }
  }
}

These environment variables are set automatically within any container. Please see the Docker documentation for more details.

Using the Traefik dashboard

If you are customizing the docker compose files and you come upon some unexpected issues, using the Traefik dashboard might be very useful to see if the problem is with Traefik configuration, or with some of the services.

You can enable the Traefik dashboard by uncommenting the following lines from docker-compose.yml

services:
  traefik:
    # Uncomment to get Traefik dashboard
    #   - "--entryPoints.dashboard.address=:8090"
    #   - "--api.dashboard=true"
    # labels:
    #   - traefik.enable=true
    #   - traefik.http.routers.dashboard.entrypoints=dashboard
    #   - traefik.http.routers.dashboard.service=api@internal
    #   - traefik.http.routers.dashboard.rule=Host(`${CVAT_HOST:-localhost}`)

and if you are using docker-compose.https.yml, also uncomment these lines

services:
  traefik:
    command:
      # Uncomment to get Traefik dashboard
      # - "--entryPoints.dashboard.address=:8090"
      # - "--api.dashboard=true"

Note that this “insecure” dashboard is not recommended in production (and if your instance is publicly available); if you want to keep the dashboard in production you should read Traefik’sdocumentation on how to properly secure it.

Additional components

Semi-automatic and automatic annotation

Please follow this guide.

Stop all containers

The command below stops and removes containers and networks created by up.

Use your own domain

If you want to access your instance of CVAT outside of your localhost (on another domain), you should specify the CVAT_HOST environment variable, like this:

export CVAT_HOST=<YOUR_DOMAIN>

You can use shared storage for uploading data when you create a task. To do that, you need to mount the shared storage to the CVAT docker container. Example of docker-compose.override.yml for this purpose:

services:
  cvat_server:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_import:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_export:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_annotation:
    volumes:
      - cvat_share:/home/django/share:ro
  cvat_worker_chunks:
    volumes:
      - cvat_share:/home/django/share:ro

volumes:
  cvat_share:
    driver_opts:
      type: none
      device: /mnt/share
      o: bind

You can change the share device path to your actual share.

You can mountyour cloud storage as a FUSE and use it later as a share.

Email verification

You can enable email verification for newly registered users. Specify these options in thesettings file to configure Django allauth to enable email verification (ACCOUNT_EMAIL_VERIFICATION = ‘mandatory’). Access is denied until the user’s email address is verified.

ACCOUNT_AUTHENTICATION_METHOD = 'username_email'
ACCOUNT_CONFIRM_EMAIL_ON_GET = True
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = 'mandatory'

# Email backend settings for Django
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'

Also, you need to configure the Django email backend to send emails. This depends on the email server you are using and is not covered in this tutorial, please seeDjango SMTP backend configurationfor details.

Deploy CVAT on the Scaleway public cloud

Please followthis tutorialto install and set up remote access to CVAT on a Scaleway cloud instance with data in a mounted object storage bucket.

Deploy secure CVAT instance with HTTPS

Using Traefik, you can automatically obtain a TLS certificate for your domain from Let’s Encrypt, enabling you to use HTTPS protocol to access your website.

To enable this, first set the CVAT_HOST (the domain of your website) and ACME_EMAIL(contact email for Let’s Encrypt) environment variables:

export CVAT_HOST=<YOUR_DOMAIN>
export ACME_EMAIL=<YOUR_EMAIL>

Then, use the docker-compose.https.yml file to override the base docker-compose.yml file:

docker compose -f docker-compose.yml -f docker-compose.https.yml up -d

In the firewall, ports 80 and 443 must be open for inbound connections from any

Then, the CVAT instance will be available at your domain on ports 443 (HTTPS) and 80 (HTTP, redirects to 443).

Deploy CVAT with an external database

By default, docker compose up will start a PostgreSQL database server, which will be used to store CVAT’s data. If you’d like to use your own PostgreSQL instance instead, you can do so as follows. Note that CVAT only supports the same major version of PostgreSQL as is used in docker-compose.yml.

First, define environment variables with database connection settings:

export CVAT_POSTGRES_HOST=<PostgreSQL hostname> # mandatory
export CVAT_POSTGRES_PORT=<PostgreSQL port> # defaults to 5432
export CVAT_POSTGRES_DBNAME=<PostgreSQL database name> # defaults to "cvat"
export CVAT_POSTGRES_USER=<PostgreSQL role name> # defaults to "root"
export CVAT_POSTGRES_PASSWORD=<PostgreSQL role password> # mandatory

Then, add the docker-compose.external_db.yml file to your docker compose up command:

docker compose -f docker-compose.yml -f docker-compose.external_db.yml up -d

How to pull/build/update CVAT images

docker pull cvat/server:v1.7.0  
docker tag cvat/server:v1.7.0 openvino/cvat_server:latest  
docker pull cvat/ui:v1.7.0  
docker tag cvat/ui:v1.7.0 openvino/cvat_ui:latest

For CVAT version more than v2.1.0 it’s possible to pull specific version of prebuilt images from DockerHub using CVAT_VERSION environment variable to specify the version (e.g. dev): 

CVAT_VERSION=dev docker compose pull  
docker compose -f docker-compose.yml -f docker-compose.dev.yml build  
CVAT_VERSION=dev docker compose pull

or 

CVAT_VERSION=latest docker compose pull

Troubleshooting

Sources for users from China

If you stay in China, for installation you need to override the following sources.

deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal main restricted universe multiverse  
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-updates main restricted universe multiverse  
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-backports main restricted universe multiverse  
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-security main restricted universe multiverse

Or source packages: 

deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal main restricted universe multiverse  
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-updates main restricted universe multiverse  
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-backports main restricted universe multiverse  
deb-src https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ focal-security main restricted universe multiverse  
{  
  "registry-mirrors": [  
    "http://f1361db2.m.daocloud.io",  
    "https://docker.mirrors.ustc.edu.cn",  
    "https://hub-mirror.c.163.com",  
    "https://mirror.ccs.tencentyun.com"  
  ]  
}  
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple  
npm config set registry https://registry.npm.taobao.org/  
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -  
sudo add-apt-repository \  
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \  
  $(lsb_release -cs) \  
curl https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -

HTTPS is not working because of a certificate

If you’re having trouble with an SSL connection, to find the cause, you’ll need to get the logs from traefik by running:

The logs will help you find out the problem.

If the error is related to a firewall, then:

After acme.json is removed, stop all cvat docker containers:

docker compose -f docker-compose.yml -f docker-compose.https.yml down

Make sure variables set (with your values):

export CVAT_HOST=<YOUR_DOMAIN>
export ACME_EMAIL=<YOUR_EMAIL>

and restart docker:

docker compose -f docker-compose.yml -f docker-compose.https.yml up -d