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

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

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

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

```bash theme={null}
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](http://localhost:8080)
* **API Documentation**: [http://localhost:8080/api/docs](http://localhost:8080/api/docs)
* **Admin Panel**: [http://localhost:8080/admin](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:
   ```bash theme={null}
   export CVAT_DEBUG_ENABLED=yes
   ```

2. Optionally, make the server wait for debugger connection:
   ```bash theme={null}
   export CVAT_DEBUG_WAIT_CLIENT=yes
   ```

3. Restart the services:
   ```bash theme={null}
   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:
   ```bash theme={null}
   cd cvat-ui
   ```

2. Install dependencies:
   ```bash theme={null}
   yarn install
   ```

3. Start the development server:
   ```bash theme={null}
   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:

```bash theme={null}
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:
   ```bash theme={null}
   cd cvat-sdk
   pip install -e .
   ```

2. Install CLI in editable mode:
   ```bash theme={null}
   cd cvat-cli
   pip install -e .
   ```

## Running Tests Locally

See the [Testing Guide](/contributing/testing) for detailed information on running tests.

Quick test commands:

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

```bash theme={null}
docker compose -f docker-compose.yml -f docker-compose.dev.yml down
```

To also remove volumes (database data):

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

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

```bash theme={null}
docker compose down -v  # Remove volumes
docker compose up -d     # Recreate from scratch
```

### Fresh Start

For a completely fresh start:

```bash theme={null}
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](https://docs.docker.com/get-docker/)
* [CVAT Installation Documentation](https://docs.cvat.ai/docs/administration/basics/installation/)
* [Architecture Overview](/contributing/architecture)
* [Testing Guide](/contributing/testing)

## Next Steps

Now that your development environment is set up:

1. Review the [code style guidelines](/contributing/code-style)
2. Learn about [writing tests](/contributing/testing)
3. Explore the [system architecture](/contributing/architecture)
4. Create your first [pull request](/contributing/pull-requests)