From ce016fb2212c49fc24ee77d49f14a091fd70c104 Mon Sep 17 00:00:00 2001 From: JakeBreath Date: Fri, 18 Sep 2026 00:53:31 -0500 Subject: [PATCH] AGENTS.md: how to run and restart the dev stack Ports, start/restart commands, the kill-by-PID gotcha and the test command so a fresh session can bring the environment back without guessing. --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 65f99b7..afb1f98 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,18 @@ Project constraints (do not regress): GIT_HASH baked in for the version pill). - Security/permission tests live in backend/apps/core/tests and need a one-time grant: GRANT ALL ON `test_j621`.* TO 'j621'@'%'; + +Dev environment (this machine): +- MariaDB/Redis run from the repo root: `docker compose up -d` (host ports + 3307 and 6380 — other local projects own 3305/6379/3406). +- Backend dev server: `backend/venv/bin/python manage.py runserver 0.0.0.0:8000`. + Django's system checks touch the database, so start MariaDB first; run it + from backend/ with the venv python. +- Frontend dev server: `npm run dev` in frontend/ — Vite listens on + [::1]:5173 (http://localhost:5173) and proxies /api to 127.0.0.1:8000. +- Restarting: kill dev servers by PID from `pgrep -af`; never + `pkill -f "manage.py runserver"` (the pattern matches its own shell). +- Suite: `backend/venv/bin/python manage.py test apps.core.tests` (~80 s). - Same-origin and cross-origin frontends both work, and the SPA can also run with no backend at all: a production build asks on first start (/setup) and stores the answer in localStorage — a URL, "" for same origin, or "none"