docker-dev-workflow.mdc
| 1 | --- |
| 2 | description: MuseHub development, testing, and QA must happen inside the Docker container, not via the host Python. |
| 3 | alwaysApply: true |
| 4 | --- |
| 5 | |
| 6 | # Docker-First Development (MuseHub) |
| 7 | |
| 8 | MuseHub targets Linux (production) and its dependencies are only installed inside the container. **For this project, always exec into the container to run Python, pytest, or any app command** — not the host Mac's Python. |
| 9 | |
| 10 | ## The Workflow |
| 11 | |
| 12 | ``` |
| 13 | ┌─ Write code (host Mac, any editor) |
| 14 | │ |
| 15 | ├─ Run / test (Docker container only) |
| 16 | │ docker compose exec musehub pytest ... |
| 17 | │ docker compose exec musehub alembic upgrade head |
| 18 | │ docker compose exec musehub python scripts/seed_musehub.py |
| 19 | │ |
| 20 | └─ Commit + push only after tests pass in the container |
| 21 | ``` |
| 22 | |
| 23 | ## Before Every Commit |
| 24 | |
| 25 | ```bash |
| 26 | # 1. Run the full relevant test suite inside the container |
| 27 | docker compose exec musehub pytest tests/test_mcp_dispatcher.py \ |
| 28 | tests/test_mcp_musehub.py tests/test_mcp_elicitation.py -q |
| 29 | |
| 30 | # 2. Confirm exit code 0, then commit |
| 31 | git add -A && git commit -m "..." |
| 32 | git push origin dev |
| 33 | ``` |
| 34 | |
| 35 | ## ❌ Don't Do This for MuseHub |
| 36 | |
| 37 | ```bash |
| 38 | pytest tests/ # host Python — missing deps (slowapi, asyncpg, etc.) |
| 39 | python musehub/... # host Python — wrong environment for this project |
| 40 | pip install ... # host pip — install inside the container instead |
| 41 | ``` |
| 42 | |
| 43 | ## ✅ Always Do This |
| 44 | |
| 45 | ```bash |
| 46 | docker compose exec musehub pytest tests/ -q |
| 47 | docker compose exec musehub pip install <pkg> # then add to pyproject.toml |
| 48 | docker compose logs musehub # check app logs |
| 49 | ``` |
| 50 | |
| 51 | ## Why |
| 52 | |
| 53 | - Production runs Linux; the container matches it exactly. |
| 54 | - All dependencies (`slowapi`, `asyncpg`, etc.) are only installed inside the container. |
| 55 | - Tests that pass on the host may fail in CI (and vice versa). Container = CI parity. |