Menu
Development workflow and Docker commands for Nudge. Use when setting up the environment, debugging containers, running Django management commands, or installing dependencies. Triggers when the user asks about development setup, Docker, or environment issues.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Backend architecture patterns and conventions for Nudge. Use when creating or modifying Django models, views, serializers, URLs, or Celery tasks. Triggers when working on backend code or when the user asks about backend conventions.
Django admin customization patterns for Nudge. Use when modifying the admin panel, adding models to admin, or changing admin branding/styling. Triggers when the user asks about Django admin, admin panel, or model registration.
Frontend architecture patterns and conventions for Nudge. Use when creating or modifying React components, pages, API calls, i18n, or CSS modules. Triggers when working on frontend code or when the user asks about frontend conventions.
Testing discipline for Nudge — write strict tests, fail hard when they reveal bugs, diagnose and fix the root cause (code, infra, or test), then re-run until green. Use whenever writing or running tests (unit, integration, E2E), debugging a failing test, or tempted to reach for `test.skip` / weakened assertions / `expect.anything()` / "known pre-existing failure" labels.
Git commit message conventions and branch naming standards for Nudge. Use when creating commits, branches, or preparing code for version control. Triggers on commit creation, branch creation, or when user asks about git workflow conventions.
| name | dev-workflow |
| description | Development workflow and Docker commands for Nudge. Use when setting up the environment, debugging containers, running Django management commands, or installing dependencies. Triggers when the user asks about development setup, Docker, or environment issues. |
NEVER run Python, Node, or npm directly on the host.
Always use dev/docker-compose.yml — it uses bind mounts so local file changes
are reflected instantly without rebuilding.
The root docker-compose.yml is for production (uses COPY, not bind mounts).
docker compose -f dev/docker-compose.yml --env-file .env up -d # Start all services
docker compose -f dev/docker-compose.yml --env-file .env down # Stop all
docker compose -f dev/docker-compose.yml --env-file .env restart frontend # Restart one service
| Service | Port | Purpose |
|---|---|---|
backend | 8000 | Django dev server |
frontend | 5173 | Vite dev server (proxies /api) |
db | 5432 | PostgreSQL |
redis | 6379 | Celery broker |
celery | — | Celery worker + beat |
# Django
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py shell
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py makemigrations
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py migrate
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py createsuperuser
# Tests — backend
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py test # full suite
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py test apps.users # one app
docker compose -f dev/docker-compose.yml --env-file .env exec backend python manage.py test apps.users.tests.AdminAccessTest # one class
# Tests — frontend
docker compose -f dev/docker-compose.yml --env-file .env exec frontend npx vitest run # full suite
docker compose -f dev/docker-compose.yml --env-file .env exec frontend npx vitest run src/pages/__tests__/SettingsPage.test.jsx # one file
# Frontend
docker compose -f dev/docker-compose.yml --env-file .env exec frontend npm install
docker compose -f dev/docker-compose.yml --env-file .env exec frontend npm run build
# Formatting (needed before commits)
docker compose -f dev/docker-compose.yml --env-file .env exec backend ruff format .
docker compose -f dev/docker-compose.yml --env-file .env exec frontend npm run format
# Logs
docker compose -f dev/docker-compose.yml --env-file .env logs backend --tail=50
docker compose -f dev/docker-compose.yml --env-file .env logs celery --tail=50
The frontend Vite dev server proxies API calls to the backend inside Docker:
proxy: {
'/api': { target: 'http://backend:8000' },
'/admin': { target: 'http://backend:8000' },
'/django-static': { target: 'http://backend:8000' },
}
backend resolves within the Docker network. From the host browser,
access everything through http://localhost:5173.
To test that endpoints respond correctly from the host:
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/health/ # 200
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/routines/ # 401
curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/auth/token/ # 405 (GET on POST-only)
VitePWA is configured with devOptions.enabled: true so the SW registers in dev.
This is needed for push notification testing. The dev SW is served at
/dev-sw.js?dev-sw (different from production's /sw.js).
After changing vite.config.js, restart the frontend container.
Playwright runs in its own Docker image (e2e/Dockerfile). Use --network host so
the container can reach localhost:5173 (frontend) and localhost:8000 (backend).
Requires the full dev stack running first.
Build image (only once, or after changing e2e/package.json):
docker build -f e2e/Dockerfile -t nudge-e2e ./e2e
Run all tests:
docker run --rm --network host \
-e E2E_USERNAME=admin \
-e E2E_PASSWORD=<password> \
-e BASE_URL=http://localhost:5173 \
nudge-e2e npx playwright test
The password is in .env as ADMIN_PASSWORD.
npx playwright test calls POST /api/internal/seed/ via
globalSetup (e2e/global-setup.js). Wipes the DB (except admin) and
rebuilds the unified deterministic fixture:
cibran / maria / laura (mutual contacts).requires_lot_selection
multi-lot stock (Ebastine) for FEFO modal coverage.Required env vars:
E2E_SEED_ALLOWED=true (or DJANGO_DEBUG=True)DEMO_USERS_PASSWORD (default change-me) — applied to all 3 demo
users.E2E_USERNAME=admin + E2E_PASSWORD=<admin password> for specs
that log in as admin.All test users and canonical names are exported from
e2e/tests/helpers/constants.js as the SEED constant. Import from
there, never hardcode.
e2e/tests/helpers.js (via helpers/offline.js) exposes helpers for
offline / reachability / conflict flows:
goOffline(page, context) / goOnline(page, context) — toggle the
network and force the reachability flag so the OfflineBanner
reacts immediately (poll interval shortened to 500 ms).waitForServiceWorkerReady(page) — block until
navigator.serviceWorker.controller is set.expectOfflineBanner(page, { visible }) / expectPendingBadge(page, { count }) —
asserts by data-testid + data-count.waitForSyncDrain(page, { timeout }) — waits for the pending badge
to disappear (queue drained).mockApiRoute(page, { method, urlPattern, status, body, times }) —
page.route() wrapper with a "respond N times then fall through"
mode, used for 412 / 429 / 5xx simulations. Returns an async
cleanup function.openConflictOnRoutineRename(page, routineId) — leaves the test
with the ConflictModal open via a mocked 412 on PATCH. Returns
the mock cleanup so the caller can replay the mutation against the
real backend.The components OfflineBanner, PendingBadge, SyncStatusBadge and
ConflictModal expose stable data-testid / data-count /
data-state attributes. Prefer these selectors over i18n text or CSS
class matches.
In dev mode, window.__NUDGE_REACHABILITY_SET__ and
window.__NUDGE_REACHABILITY_POLL_MS__ are exposed so specs can drive
reachability directly without relying on fetch side effects. They
are stripped by the production build (import.meta.env.DEV guard),
but the frontend-preview service opts back in via VITE_E2E_MODE=true.
The Vite dev server does NOT precache JS modules in the Service Worker
(__WB_MANIFEST is empty in dev), so offline reloads can't load the
React app against :5173. Offline specs (offline-*.spec.js) run
against a production preview build served by the frontend-preview
service on port 4173.
Bring it up before running offline tests:
docker compose -f dev/docker-compose.yml --env-file .env \
--profile preview up -d frontend-preview
# First boot runs `npm run build` (~30 s). Subsequent boots are fast.
playwright.config.js has two projects that Playwright runs together:
chromium-dev at localhost:5173 — runs every spec except
offline-*.spec.js.chromium-preview at localhost:4173 — runs only offline-*.spec.js.Run subsets:
npx playwright test --project=chromium-dev — dev specs only.npx playwright test --project=chromium-preview — offline specs only.npx playwright test — all, dispatched to the right project automatically.chromium-dev runs 73
(auth, admin, dashboard, inventory, routines, settings, history,
sharing, unshare, contacts, i18n, routine-completion, stock-expiry,
stock-share-grouped-bug, scheduled-push, push-realtime, helpers
smoke) and chromium-preview runs 11 (offline-read,
offline-mutations, offline-sync).workers: 1, fullyParallel: false) — dev y
preview comparten el mismo backend y en paralelo pisan datos.playwright.config.js; los validation
runs usan --retries=0. Cualquier flake bajo --retries=0
cuenta como fallo real y hay que diagnosticar en origen.docker compose -f dev/docker-compose.yml --env-file .env up -d
(backend, celery, frontend) más --profile preview up -d frontend-preview
si vas a correr offline specs.globalSetup; BD y PushSubscription.objects
se resetean entre specs con await resetSeed(context) en beforeEach
cuando el spec muta datos globales.Subsets rápidos:
# Auth + admin (sanity)
npx playwright test auth admin
# Solo offline (requiere frontend-preview arriba)
npx playwright test --project=chromium-preview
# Un spec aislado, sin retries (para reproducir un flake)
npx playwright test tests/push-realtime.spec.js --retries=0
# Full suite
npx playwright test
If another container already binds port 8000, use run --rm instead of exec — it starts a one-off container without binding host ports:
docker compose -f dev/docker-compose.yml --env-file .env run --rm backend python manage.py migrate
docker compose -f dev/docker-compose.yml --env-file .env run --rm backend python manage.py shell
All env vars are in .env at the project root. Key ones:
ADMIN_PASSWORD — password for the admin user (auto-created on startup)VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY — for Web PushDJANGO_SECRET_KEY, POSTGRES_*, etc.