Docker Compose Installation

Step-by-step guide to install CVAT using Docker Compose for local and production deployments

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

Log in with the superuser credentials you created.

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=[e-mail]

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

1. Change default passwords: PostgreSQL, Redis, and ClickHouse
2. Use HTTPS in production: Always use SSL/TLS certificates
3. Configure ALLOWED_HOSTS: Restrict to your domain(s)
4. Enable firewall: Only expose ports 80 and 443
5. Regular updates: Keep images and dependencies updated
6. Backup regularly: Automate backups of volumes and database
7. 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

Next Steps

• Configure authentication
• Set up cloud storage
• Enable auto-annotation
• Kubernetes deployment