Docker Debug Workflow: add dev/cvat-debug.sh, debug compose stack, and VS Code integration

[nmanovic]

Summary

Introduce a Docker-based CVAT development workflow that lets contributors work on backend and frontend code without installing Python, Node.js, Yarn, Redis, PostgreSQL, OPA, ClickHouse, or other CVAT runtime dependencies on the host.

The workflow is centered on one helper entrypoint:

./dev/cvat-local.sh <command>

What's included

• Added dev/cvat-local.sh as the standard local development entrypoint for Docker-based workflows.
• Added dev/docker-compose.local.yml with local development overrides for bind-mounted source code, backend debug ports, and the containerized webpack dev server.
• Added dev/Dockerfile.server.debug to layer debugpy on top of cvat/server:<tag> images.
• Added dev/Dockerfile.local-ui for the containerized UI development server and Docker-volume backed Yarn dependencies.
• Added the Docker-based development environment contributor guide with setup, daily workflow, frontend debugging, backend debugging, UI checks, cleanup, and design tradeoffs.
• Updated VS Code launch/tasks so contributors see Docker: Frontend and Docker: Backend as the primary Docker debug profiles, while individual attach profiles stay hidden.
• Updated the native development guide to link to the Docker-based alternative.

Developer impact

• Contributors can start a reproducible local CVAT development environment with Docker as the only required runtime dependency.
• Backend debugging works through localhost-bound debugpy ports for the server and debug-enabled workers.
• Frontend debugging works through the containerized webpack dev server on http://localhost:3000, with source maps mapped back to the checkout.
• UI dependencies are installed into Docker named volumes instead of the host checkout, keeping the working tree cleaner and avoiding host Node/Yarn requirements.
• The helper keeps a small command surface and uses shell / exec as escape hatches for uncommon commands.

Common workflow

./dev/cvat-local.sh doctor
./dev/cvat-local.sh bootstrap
./dev/cvat-local.sh up-full
./dev/cvat-local.sh createsuperuser

Frontend development:

./dev/cvat-local.sh up-ui
./dev/cvat-local.sh logs cvat_ui_dev
# open http://localhost:3000
# use VS Code launch profile: Docker: Frontend

Backend development:

./dev/cvat-local.sh up-workers
./dev/cvat-local.sh logs cvat_server
./dev/cvat-local.sh restart server
# use VS Code launch profile: Docker: Backend

UI sanity checks:

./dev/cvat-local.sh check-ui

Validation

• bash -n dev/cvat-local.sh
• ./dev/cvat-local.sh compose-config
• ./dev/cvat-local.sh check-ui
• VS Code launch.json parsed and compound references checked
• git diff --check origin/develop..HEAD

Notes

• The old dev/cvat-debug.sh / dev/docker-compose.debug.yml approach was replaced by the broader dev/cvat-local.sh workflow.
• The Docker debug ports are bound to localhost where they are published to the host.
• The cvat_worker_utils container is intentionally not debug-enabled in this patch because it runs scheduler-related processes that need a separate, explicit treatment.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!