env-backend

name	env-backend
description	Recipe for filling state/reference/ENV.md when the project is a backend service (API, worker, daemon). Use when the project ships a server but no UI; covers compose-based DB/cache, pytest/jest test runners, and container log capture. Adjust language ecosystem (Python/Node/Go/etc.) accordingly.
tools	["Read","Write","Bash"]

env-backend — recipe for state/reference/ENV.md

Below is a Python + FastAPI + Postgres flavor. Translate to your stack but keep the section structure.

Profile

Profile: backend

Bring up

• uv sync # or pip install -e .[dev], poetry install, pnpm install for Node
• docker compose up -d db redis # whatever stateful deps you have
• Wait for db: docker compose exec -T db pg_isready -t 30
• Apply migrations: uv run alembic upgrade head

Smoke (< 30s)

• uv run python -c "from myapp import app; print(app.title)"
• docker compose ps --status running | Select-String db

Verify (canonical green-light)

• uv run pytest -q -x --maxfail=1
• For richer green-light: uv run ruff check . && uv run mypy . && uv run pytest -q

E2E / instrumentation

• uv run pytest -m e2e --maxfail=1 # marker-gated slow tests
• For full app under test: spin the app with uv run uvicorn myapp:app --port 8001 &, hit it with httpx, capture in tests

Capture logs

• Application logs (containerized):

  docker compose logs --tail 200 api
  docker compose logs --tail 200 db
  

• Application logs (host process): Get-Content app.log -Tail 200
• Test logs: pytest writes the last failures to .pytest_cache/v/cache/lastfailed; full output via uv run pytest -v 2>&1 | Tee-Object .test.log
• DB query log (debugging): docker compose exec -T db psql -U postgres -c "SELECT query, state FROM pg_stat_activity"
• Where logs land: .test.log, docker compose logs (ephemeral — capture before tear down)

Tear down

• docker compose down -v # -v wipes volumes; only between fresh test runs
• For a softer reset (keep data): docker compose restart

Devices / external services

• Postgres 16 via compose (service name db, port 5432)
• Redis 7 via compose (service name redis, port 6379)
• Any external API mocks: list endpoint + how to stub (e.g. respx)

Known fragility

• Migrations against a non-empty dev DB can clash — always docker compose down -v between schema-change PRs
• Compose on Windows + WSL2 can lose localhost mapping; use 127.0.0.1 explicitly
• pytest plugin import order (e.g. pytest-asyncio) — pin in pyproject.toml