> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/cvat-ai/cvat/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
# 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

```bash theme={null}
git clone https://github.com/cvat-ai/cvat
cd cvat
```

### 2. Set Environment Variables

Set the hostname that CVAT will be accessible from:

```bash theme={null}
export CVAT_HOST=localhost
```

For production, use your domain or public IP:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```yaml theme={null}
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:

```bash theme={null}
# 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`:

```bash theme={null}
export CVAT_VERSION=v2.10.0
docker compose pull
docker compose up -d
```

### Scaling Workers

Edit `docker-compose.yml` to adjust worker processes:

```yaml theme={null}
cvat_worker_export:
  environment:
    NUMPROCS: 4  # Increase from default 2
```

Then restart:

```bash theme={null}
docker compose up -d
```

## Production Deployment

### HTTPS Configuration

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

```bash theme={null}
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`:

```yaml theme={null}
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:

```bash theme={null}
docker compose -f docker-compose.yml -f docker-compose.external_db.yml up -d
```

### Persistent Storage

Docker volumes are created automatically:

```yaml theme={null}
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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
docker compose restart cvat_server
```

### Check Service Status

```bash theme={null}
docker compose ps
```

### Execute Commands in Containers

```bash theme={null}
# 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**:

```bash theme={null}
docker compose logs cvat_server
```

**Verify all containers are running**:

```bash theme={null}
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**:

```bash theme={null}
docker compose logs cvat_db
```

The database takes 10-30 seconds to initialize on first start.

**Reset database** (warning: deletes all data):

```bash theme={null}
docker compose down -v
docker volume rm cvat_db
docker compose up -d
```

### Worker Process Issues

**Check worker status**:

```bash theme={null}
docker compose ps | grep worker
```

**View worker logs**:

```bash theme={null}
docker compose logs cvat_worker_export
```

**Restart workers**:

```bash theme={null}
docker compose restart cvat_worker_export cvat_worker_import
```

### Out of Disk Space

**Check volume sizes**:

```bash theme={null}
docker system df -v
```

**Clean up unused resources**:

```bash theme={null}
# 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:

```yaml theme={null}
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**:

```bash theme={null}
docker compose logs traefik
```

**Verify port binding**:

```bash theme={null}
docker compose ps traefik
```

**Test directly**:

```bash theme={null}
curl http://localhost:8080
```

## Development Setup

For development with hot-reload and debugging:

```bash theme={null}
# 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](/administration/authentication)
* [Set up cloud storage](/administration/cloud-storage)
* [Enable auto-annotation](/administration/serverless)
* [Kubernetes deployment](/self-hosted/installation/kubernetes)