Docker Compose Installation

Docker Compose is the simplest way to run CVAT. This guide covers installation from the latest release and running CVAT in production.

Prerequisites

System Requirements

Operating System: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+), macOS, Windows with WSL2
CPU: 2 cores minimum, 4+ recommended
RAM: 4GB minimum, 8GB+ recommended
Disk Space: 50GB minimum for application and data

Software Requirements

Install Docker Engine and Docker Compose:

# On Ubuntu/Debian
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version
docker compose version

Required versions:

Docker Engine: 20.10.0 or higher
Docker Compose: 2.0.0 or higher

Quick Start

1. Clone the Repository

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

2. Set Environment Variables

Set the hostname that CVAT will be accessible from:

export CVAT_HOST=localhost

For production, use your domain or public IP:

export CVAT_HOST=cvat.example.com
# or
export CVAT_HOST=203.0.113.10

3. Start CVAT

Pull the latest images and start all services:

docker compose pull
docker compose up -d

This command will:

Pull all required Docker images (~5-10 minutes depending on connection)
Create Docker volumes for persistent storage
Start all CVAT services in the background

4. Create a Superuser

After services start, create an admin account:

docker exec -it cvat_server bash -ic 'python manage.py createsuperuser'

You’ll be prompted for:

Username
Email address
Password (twice)

5. Access CVAT

Open your browser and navigate to:

http://localhost:8080

Or your configured hostname:

http://your-hostname:8080

Service Architecture

The default Docker Compose deployment includes these services:

Core Services

services:
  cvat_server:
    image: cvat/server:dev
    ports: [8080]
    depends_on:
      - cvat_db
      - cvat_redis_inmem
      - cvat_redis_ondisk
      - cvat_opa

cvat_server: Main API server (Django)
cvat_ui: Frontend React application
traefik: Reverse proxy and load balancer

Data Services

cvat_db: PostgreSQL 15 database
cvat_redis_inmem: Redis 7.2.11 for caching
cvat_redis_ondisk: Apache Kvrocks 2.12.1 for persistent cache
cvat_clickhouse: ClickHouse for analytics

Worker Services

cvat_worker_import: Dataset imports (NUMPROCS=2)
cvat_worker_export: Annotation exports (NUMPROCS=2)
cvat_worker_annotation: Annotation processing
cvat_worker_webhooks: Webhook delivery
cvat_worker_quality_reports: Quality metrics
cvat_worker_chunks: Media chunk processing (NUMPROCS=2)
cvat_worker_consensus: Consensus calculations
cvat_worker_utils: Notifications and cleanup

Analytics Services

cvat_vector: Log collection and forwarding
cvat_grafana: Analytics dashboards

Security

cvat_opa: Open Policy Agent for authorization

Configuration Options

Environment Variables

Create a .env file or export variables:

# Required
export CVAT_HOST=localhost

# Optional
export CVAT_VERSION=dev                    # Docker image tag
export CVAT_ANALYTICS=1                     # Enable analytics (default: 1)
export CVAT_ALLOW_STATIC_CACHE=yes          # Enable static file caching
export ALLOWED_HOSTS='*'                    # Django allowed hosts
export CVAT_BASE_URL=                       # Base URL if behind proxy
export ONE_RUNNING_JOB_IN_QUEUE_PER_USER=   # Job queue limits

Using Specific Versions

To use a specific CVAT version instead of dev:

export CVAT_VERSION=v2.10.0
docker compose pull
docker compose up -d

Scaling Workers

Edit docker-compose.yml to adjust worker processes:

cvat_worker_export:
  environment:
    NUMPROCS: 4  # Increase from default 2

Then restart:

docker compose up -d

Production Deployment

HTTPS Configuration

Use the HTTPS overlay for Let’s Encrypt SSL certificates:

export CVAT_HOST=cvat.example.com
export ACME_EMAIL=admin@example.com

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

This configuration:

Redirects HTTP (port 80) to HTTPS (port 443)
Automatically obtains SSL certificates from Let’s Encrypt
Renews certificates automatically

Ports exposed:

80: HTTP (redirects to HTTPS)
443: HTTPS

External Database

For production, consider using an external PostgreSQL database: Create docker-compose.external_db.yml:

services:
  cvat_server:
    environment:
      CVAT_POSTGRES_HOST: db.example.com
      CVAT_POSTGRES_PORT: 5432
      CVAT_POSTGRES_USER: cvat
      CVAT_POSTGRES_DBNAME: cvat
      CVAT_POSTGRES_PASSWORD: secure_password

Then deploy:

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

Persistent Storage

Docker volumes are created automatically:

volumes:
  cvat_db:           # Database files
  cvat_data:         # Media and datasets
  cvat_keys:         # Auth keys
  cvat_logs:         # Application logs
  cvat_inmem_db:     # Redis persistence
  cvat_cache_db:     # Kvrocks cache
  cvat_events_db:    # ClickHouse analytics

To backup volumes:

# Backup data volume
docker run --rm -v cvat_data:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/cvat_data_backup.tar.gz /data

# Backup database
docker exec cvat_db pg_dumpall -U root > cvat_db_backup.sql

Common Operations

Start/Stop Services

# Start all services
docker compose up -d

# Stop all services
docker compose stop

# Stop and remove containers
docker compose down

# Stop and remove containers and volumes
docker compose down -v

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f cvat_server

# Last 100 lines
docker compose logs --tail=100 cvat_server

Update CVAT

# Pull latest code
git pull

# Pull new images
docker compose pull

# Restart services
docker compose up -d

# Run migrations if needed
docker exec cvat_server python manage.py migrate

Restart a Single Service

docker compose restart cvat_server

Check Service Status

docker compose ps

Execute Commands in Containers

# Open shell in server
docker exec -it cvat_server bash

# Run Django management commands
docker exec cvat_server python manage.py <command>

# Examples
docker exec cvat_server python manage.py migrate
docker exec cvat_server python manage.py collectstatic

Troubleshooting

Services Won’t Start

Check logs:

docker compose logs cvat_server

Verify all containers are running:

docker compose ps

Common issues:

Port 8080 already in use: Change port or stop conflicting service
Insufficient memory: Increase Docker memory limit
Permission errors: Check file ownership and Docker socket access

Database Connection Errors

Wait for database initialization:

docker compose logs cvat_db

The database takes 10-30 seconds to initialize on first start. Reset database (warning: deletes all data):

docker compose down -v
docker volume rm cvat_db
docker compose up -d

Worker Process Issues

Check worker status:

docker compose ps | grep worker

View worker logs:

docker compose logs cvat_worker_export

Restart workers:

docker compose restart cvat_worker_export cvat_worker_import

Out of Disk Space

Check volume sizes:

docker system df -v

Clean up unused resources:

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove all unused data
docker system prune -a --volumes

Performance Issues

Increase worker processes: Edit docker-compose.yml and increase NUMPROCS for workers:

cvat_worker_chunks:
  environment:
    NUMPROCS: 4  # Increase based on CPU cores

Allocate more resources: Increase Docker Desktop resource limits (CPU and RAM).

Cannot Access UI

Check Traefik:

docker compose logs traefik

Verify port binding:

docker compose ps traefik

Test directly:

curl http://localhost:8080

Development Setup

For development with hot-reload and debugging:

# Use development overlay
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

This configuration:

Builds images from local source
Enables debug ports
Exposes service ports for direct access
Mounts source code for development

Security Considerations

Change default passwords: PostgreSQL, Redis, and ClickHouse
Use HTTPS in production: Always use SSL/TLS certificates
Configure ALLOWED_HOSTS: Restrict to your domain(s)
Enable firewall: Only expose ports 80 and 443
Regular updates: Keep images and dependencies updated
Backup regularly: Automate backups of volumes and database
Monitor logs: Set up log aggregation and alerts

Resource Requirements

Minimum Configuration

2 CPU cores
4GB RAM
50GB disk space
Suitable for 1-5 users, small datasets

Recommended Configuration

4+ CPU cores
8GB+ RAM
100GB+ SSD storage
Suitable for 5-20 users, medium datasets

Production Configuration

8+ CPU cores
16GB+ RAM
500GB+ SSD storage
External PostgreSQL with replication
Shared network storage for media
Suitable for 20+ users, large datasets

Installation

Administration

Serverless Functions

​Prerequisites

​System Requirements

​Software Requirements

​Quick Start

​1. Clone the Repository

​2. Set Environment Variables

​3. Start CVAT

​4. Create a Superuser

​5. Access CVAT

​Service Architecture

​Core Services

​Data Services

​Worker Services

​Analytics Services

​Security

​Configuration Options

​Environment Variables

​Using Specific Versions

​Scaling Workers

​Production Deployment

​HTTPS Configuration

​External Database

​Persistent Storage

​Common Operations

​Start/Stop Services

​View Logs

​Update CVAT

​Restart a Single Service

​Check Service Status

​Execute Commands in Containers

​Troubleshooting

​Services Won’t Start

​Database Connection Errors

​Worker Process Issues

​Out of Disk Space

​Performance Issues

​Cannot Access UI

​Development Setup

​Security Considerations

​Resource Requirements

​Minimum Configuration

​Recommended Configuration

​Production Configuration

​Next Steps

Build docs developers (and LLMs) love