Development Environment Setup

Set up your local development environment for CVAT

This guide will help you set up a local development environment for CVAT, enabling you to run the application, make changes, and test your contributions.

Prerequisites

Before setting up CVAT for development, ensure you have:

• Docker (20.10.0 or higher) and Docker Compose (1.29.0 or higher)
• Git for version control
• Python 3.10+ (for SDK/CLI development)
• Node.js 16+ and Yarn (for frontend development)
• At least 8GB of RAM and 20GB of disk space
• Linux, macOS, or Windows with WSL2

Add User to Docker Group (Linux/WSL)

On Debian/Ubuntu systems, add your user to the docker group:

sudo usermod -aG docker $USER

Log out and back in for the changes to take effect.

Cloning the Repository

Clone the CVAT repository and navigate to it:

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

Running CVAT for Development

CVAT provides a special Docker Compose configuration for development that includes debugging capabilities and hot-reload support.

Start Development Environment

The development environment uses docker-compose.dev.yml which extends the base configuration:

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

This configuration:

• Exposes debug ports for backend services (9090-9096)
• Enables hot-reload for frontend changes
• Mounts source code directories for live editing
• Exposes database ports for direct access (PostgreSQL: 5432, Redis: 6379, ClickHouse: 8123)

Accessing the Application

Once the containers are running:

• Web UI: http://localhost:8080
• API Documentation: http://localhost:8080/api/docs
• Admin Panel: http://localhost:8080/admin

Default credentials:

• Username: admin1
• Password: See the logs or documentation

Development Ports

The development configuration exposes these debug ports:

• 9090: Backend server (cvat_server)
• 9091: Annotation worker
• 9092: Export worker
• 9093: Import worker
• 9094: Quality reports worker
• 9096: Consensus worker

Database Access

Direct database access is available on:

• PostgreSQL: localhost:5432
• Redis (in-memory): localhost:6379
• Redis (on-disk): localhost:6666
• ClickHouse: localhost:8123
• OPA: localhost:8181
• Vector: localhost:8282

Debugging

Backend Debugging

To enable debugging for the backend:

1. Set the environment variable:

   export CVAT_DEBUG_ENABLED=yes
   

2. Optionally, make the server wait for debugger connection:

   export CVAT_DEBUG_WAIT_CLIENT=yes
   

3. Restart the services:

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

4. Connect your debugger to the appropriate port (default: 9090)

Frontend Development

For frontend development with hot-reload:

1. Navigate to the UI directory:

   cd cvat-ui
   

2. Install dependencies:

   yarn install
   

3. Start the development server:

   yarn start
   

Changes to frontend code will automatically reload in the browser.

Working with Specific Components

Backend (Django)

The backend code is in the cvat/ directory. To run Django management commands:

docker exec -it cvat_server bash
python manage.py <command>

Common commands:

• python manage.py migrate - Run database migrations
• python manage.py makemigrations - Create new migrations
• python manage.py shell - Open Django shell
• python manage.py test - Run Django tests

Frontend (React + TypeScript)

The frontend is organized into several packages:

• cvat-ui: Main UI application
• cvat-core: Core business logic and API client
• cvat-canvas: 2D annotation canvas
• cvat-canvas3d: 3D annotation canvas
• cvat-data: Data handling utilities

SDK and CLI

For Python SDK and CLI development:

1. Install SDK in editable mode:

   cd cvat-sdk
   pip install -e .
   

2. Install CLI in editable mode:

   cd cvat-cli
   pip install -e .
   

Running Tests Locally

See the Testing Guide for detailed information on running tests.

Quick test commands:

# Python/Backend tests
pytest tests/python/

# Frontend tests
cd cvat-ui && yarn test

# E2E tests
cd tests && yarn run cypress:run

Stopping the Development Environment

To stop all containers:

docker compose -f docker-compose.yml -f docker-compose.dev.yml down

To also remove volumes (database data):

docker compose -f docker-compose.yml -f docker-compose.dev.yml down -v

Troubleshooting

Port Conflicts

If you get port binding errors, ensure no other CVAT instances or services are using the required ports:

docker ps -a
docker stop $(docker ps -a -q)

Permission Issues

If you encounter permission issues with Docker, verify your user is in the docker group and try restarting your session.

Database Issues

If the database becomes corrupted:

docker compose down -v  # Remove volumes
docker compose up -d     # Recreate from scratch

Fresh Start

For a completely fresh start:

docker compose down -v
docker system prune -a
git clean -fdx  # WARNING: This removes all untracked files
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

Additional Resources

• Docker Installation Guide
• CVAT Installation Documentation
• Architecture Overview
• Testing Guide

Next Steps

Now that your development environment is set up:

1. Review the code style guidelines
2. Learn about writing tests
3. Explore the system architecture
4. Create your first pull request