Configuration

Environment variables and configuration options for self-hosted CVAT

This guide covers the configuration options available for self-hosted CVAT deployments using Docker Compose.

Environment Variables

CVAT uses environment variables to configure various aspects of the application. These can be set in a .env file or directly in your docker-compose.override.yml.

Core Settings

Host and URL Configuration

CVAT_HOST=localhost
CVAT_BASE_URL=http://localhost:8080

• CVAT_HOST: The hostname where CVAT will be accessible (default: localhost)
• CVAT_BASE_URL: Full base URL for CVAT (default: http://{CVAT_HOST}:8080)
• CVAT_VERSION: Docker image version to use (default: dev)

Database Configuration

CVAT_POSTGRES_HOST=cvat_db
CVAT_POSTGRES_DBNAME=cvat
CVAT_POSTGRES_USER=root
CVAT_POSTGRES_PASSWORD=
CVAT_POSTGRES_PORT=5432
CVAT_POSTGRES_APPLICATION_NAME=cvat

For sensitive passwords, use the file-based approach:

CVAT_POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password

See cvat/settings/base.py:711 for the password file implementation.

Redis Configuration

CVAT uses two Redis instances:

In-Memory Redis (session data, caching)

CVAT_REDIS_INMEM_HOST=cvat_redis_inmem
CVAT_REDIS_INMEM_PORT=6379
CVAT_REDIS_INMEM_PASSWORD=

On-Disk Redis/Kvrocks (media cache)

CVAT_REDIS_ONDISK_HOST=cvat_redis_ondisk
CVAT_REDIS_ONDISK_PORT=6666
CVAT_REDIS_ONDISK_PASSWORD=

ClickHouse (Analytics Database)

CLICKHOUSE_HOST=clickhouse
CLICKHOUSE_PORT=8123
CLICKHOUSE_DB=cvat
CLICKHOUSE_USER=user
CLICKHOUSE_PASSWORD=user

See docker-compose.yml:31-36 and cvat/settings/base.py:701-709 for ClickHouse configuration.

Django Settings

Security

DJANGO_SECRET_KEY=
ALLOWED_HOSTS=*

• DJANGO_SECRET_KEY: Secret key for Django (auto-generated if not set)
• ALLOWED_HOSTS: Comma-separated list of allowed hostnames (default: localhost,127.0.0.1)

See cvat/settings/base.py:36-38 for ALLOWED_HOSTS configuration.

Logging

DJANGO_LOG_LEVEL=DEBUG
DJANGO_LOG_SERVER_HOST=vector
DJANGO_LOG_SERVER_PORT=8282
VECTOR_EVENT_HANDLER=AsynchronousLogstashHandler

See cvat/settings/base.py:481-553 for logging configuration.

Application Settings

Analytics

CVAT_ANALYTICS=1

Enables analytics features including Grafana dashboards and event tracking. See cvat/settings/base.py:177-180.

Worker Configuration

NUMPROCS=2

Number of worker processes for each worker type. Set in docker-compose.yml:98 for the server and various worker containers.

Feature Flags

ADAPTIVE_AUTO_ANNOTATION=false
ONE_RUNNING_JOB_IN_QUEUE_PER_USER=
CVAT_ALLOW_STATIC_CACHE=no

See docker-compose.yml:97-101 and cvat/settings/base.py:756 for feature flag configurations.

File Processing

CVAT_CONCURRENT_CHUNK_PROCESSING=1
CVAT_LOG_IMPORT_ERRORS=true

• CVAT_CONCURRENT_CHUNK_PROCESSING: Number of chunks processed simultaneously (default: 1)
• CVAT_LOG_IMPORT_ERRORS: Log import errors to file (default: false)

See cvat/settings/base.py:549 and cvat/settings/base.py:759.

Health Checks

CVAT_HEALTH_DISK_USAGE_MAX=90

Maximum disk usage percentage before health check fails. See cvat/settings/base.py:788.

Serverless Functions (Nuclio)

CVAT_NUCLIO_SCHEME=http
CVAT_NUCLIO_HOST=localhost
CVAT_NUCLIO_PORT=8070
CVAT_NUCLIO_DEFAULT_TIMEOUT=120
CVAT_NUCLIO_FUNCTION_NAMESPACE=nuclio
CVAT_NUCLIO_INVOKE_METHOD=dashboard

See cvat/settings/base.py:345-357 for Nuclio configuration.

Proxy Configuration

no_proxy=clickhouse,grafana,vector,nuclio,opa
SMOKESCREEN_OPTS=

See docker-compose.yml:18-19 for proxy settings.

Django Settings Files

CVAT uses multiple Django settings files located in cvat/settings/:

• base.py: Core settings (database, cache, authentication, logging)
• production.py: Production-specific settings
• development.py: Development settings
• email_settings.py: Email configuration
• testing.py: Test environment settings

Custom Settings Overlay

To customize Django settings without modifying core files:

1. Create a custom settings.py file:

# Import production settings
from cvat.settings.production import *

# Override specific settings
ALLOWED_HOSTS = ['your-domain.com']
DEBUG = False

2. Mount it in docker-compose.override.yml:

services:
  cvat_server:
    environment:
      DJANGO_SETTINGS_MODULE: settings
    volumes:
      - ./settings.py:/home/django/settings.py:ro

Docker Compose Configuration

Volume Mounts

CVAT uses several Docker volumes defined in docker-compose.yml:421-428:

• cvat_db: PostgreSQL database files
• cvat_data: Uploaded media and task data
• cvat_keys: Django secret key storage
• cvat_logs: Application logs
• cvat_inmem_db: Redis in-memory data
• cvat_events_db: ClickHouse analytics data
• cvat_cache_db: Kvrocks on-disk cache

Service Configuration

Key services defined in docker-compose.yml:

• cvat_server: Main Django application server
• cvat_ui: Frontend UI server
• cvat_db: PostgreSQL database
• cvat_redis_inmem: Redis for sessions/cache
• cvat_redis_ondisk: Kvrocks for media cache
• cvat_clickhouse: ClickHouse for analytics
• cvat_vector: Log aggregation
• cvat_grafana: Analytics dashboards
• cvat_opa: Open Policy Agent for authorization
• traefik: Reverse proxy

Worker services (handle background tasks):

• cvat_worker_import: Data import operations
• cvat_worker_export: Data export operations
• cvat_worker_annotation: Auto-annotation tasks
• cvat_worker_webhooks: Webhook delivery
• cvat_worker_quality_reports: Quality control reports
• cvat_worker_chunks: Video chunk processing
• cvat_worker_consensus: Consensus calculations
• cvat_worker_utils: Notifications and cleanup

See docker-compose.yml:38-248 for detailed service configurations.

Override Configuration

Create a docker-compose.override.yml to customize your deployment:

services:
  cvat_server:
    environment:
      ALLOWED_HOSTS: your-domain.com
      CVAT_ANALYTICS: 1
    volumes:
      - /your/custom/path:/home/django/data

Cache Configuration

Cache timeouts defined in cvat/settings/base.py:566-580:

CVAT_CHUNK_CACHE_TTL = 3600 * 24  # 1 day
CVAT_PREVIEW_CACHE_TTL = 3600 * 24 * 7  # 7 days

Time Zone

TZ=Etc/UTC

Set the timezone for the application. See cvat/settings/base.py:417.

Additional Resources

• Django Settings Documentation
• Docker Compose File Reference
• Source code: cvat/settings/base.py, docker-compose.yml