Skip to content

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

Open
nmanovic wants to merge 5 commits intodevelopfrom
localdev
Open

Docker Debug Workflow: add dev/cvat-debug.sh, debug compose stack, and VS Code integration#10308
nmanovic wants to merge 5 commits intodevelopfrom
localdev

Conversation

@nmanovic
Copy link
Copy Markdown
Contributor

Summary

Introduce a complete Docker-first CVAT debug workflow with dedicated debug compose config, helper script, and VS Code integration.

What’s included

  • Added dev/cvat-debug.sh as the main local debug workflow entrypoint
  • Added dev/docker-compose.debug.yml for debug-specific overrides
  • Added dev/Dockerfile.server.debug for debug image layering on top of cvat/server:dev
  • Added dev/docker-debugging.md with from-scratch setup and troubleshooting
  • Updated .vscode/launch.json with Docker attach compound for backend debugging
  • Updated .vscode/tasks.json to bootstrap Docker debug workflow from VS Code
  • Reduced supervisord verbosity in supervisord/reusable/supervisord.conf (debug -> info)

Developer impact

  • Standardized command surface for build/start/restart/cleanup/debug
  • Faster iteration with in-container server fast restart and fallback to full restart
  • Cleaner logs and clearer runtime timing output from debug helper commands
  • Better onboarding with explicit docs and reproducible workflow
$ ./dev/cvat-debug.sh --help
Usage: ./dev/cvat-debug.sh <command> [args]

Commands:
  build-debug                     Build debug image (FROM prebuilt cvat/server:dev + debugpy)
  build-all                       Rebuild local cvat/server:dev and refresh debug image
  doctor                          Check required/optional local tooling
  up                              Start core stack
  up-workers                      Start worker profile services
  up-analytics                    Start analytics profile services
  createsuperuser                 Run Django createsuperuser in cvat_server
  vscode                          Start server+workers and open VS Code
  restart-server                  Fast restart of API process (uvicorn) inside cvat_server
  restart-server-full             Full container restart of cvat_server
  restart-worker <service>        Restart one worker service (e.g. cvat_worker_import)
  logs [service]                  Follow logs (default: cvat_server)
  ps                              Show compose services status
  clean                           Stop and remove containers
  distclean                       Stop and remove containers + volumes
  clobber                         Aggressive cleanup of leftover network/volumes/containers
  help                            Show this help

Most common workflow:
  1) First time setup:
       ./dev/cvat-debug.sh build-debug
       ./dev/cvat-debug.sh up-workers
       ./dev/cvat-debug.sh createsuperuser
  2) Daily start:
       ./dev/cvat-debug.sh up-workers
  3) Debug in VS Code:
       ./dev/cvat-debug.sh vscode
       # then run "docker: attach backend debug" launch config
  4) After backend code changes:
       ./dev/cvat-debug.sh restart-server
       # use restart-server-full when env/supervisord/nginx/image-level changes require full re-init
  5) Cleanup:
       ./dev/cvat-debug.sh clean
       ./dev/cvat-debug.sh distclean
       ./dev/cvat-debug.sh clobber   # only if resources remain in use
[cvat-debug][--help] elapsed real time: 0.033s

@codecov-commenter
Copy link
Copy Markdown

codecov-commenter commented Feb 23, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 75.94%. Comparing base (3d9b1b5) to head (d038e43).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files
@@             Coverage Diff             @@
##           develop   #10308      +/-   ##
===========================================
+ Coverage    75.52%   75.94%   +0.41%     
===========================================
  Files          482      431      -51     
  Lines        49726    46654    -3072     
  Branches      4220     4220              
===========================================
- Hits         37558    35432    -2126     
+ Misses       12168    11222     -946     
Components Coverage Δ
cvat-ui 77.71% <ø> (+0.02%) ⬆️
cvat-server 74.43% <ø> (+0.54%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nmanovic added 5 commits March 2, 2026 16:52
- preserve mainstream launch configs and add a dedicated Docker attach compound
- add VS Code tasks to bootstrap worker containers for debug sessions
- introduce dev/debug.sh helper for common debug stack commands
- move debug compose overrides to dev/docker-compose.debug.yml
- add a concise from-scratch guide at dev/docker-debugging.md
- rename dev/debug.sh to dev/cvat-debug.sh and update references
- add lightweight debug overlay image based on prebuilt cvat/server:dev
- move and use dev/docker-compose.debug.yml for debug-specific compose overrides
- add cleanup command set (clean/distclean/clobber) and usage guide
- wire VS Code tasks and docs to the updated script/commands
- send timing output to stderr with clear command-scoped labels
- add portable high-resolution timing fallback chain and doctor checks
- document updated debug workflow and cleanup guidance
- rename build commands to build-debug/build-all with backward-compatible aliases
- add rebuild path for local base image refresh and simplify compose function
- speed up server restart via supervisor fast path with full-restart fallback
- add command timing output to stderr with clear labels and update docs
- set supervisord loglevel to info to reduce debug log noise
- remove legacy command aliases and keep canonical command names only
- keep fast supervisor-based server restart with full-restart fallback
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants