django-postfix-dovecot-api/AGENTS.md

AGENTS.md

REST API (Django + django-ninja) for managing the virtual domains, users and aliases that Postfix and Dovecot read from the database. Deployed as mxapi.neuf.no.

Setup and commands

Tools are managed by mise (Python, uv, prek) and Python deps by uv.

mise install            # Python, uv, prek
uv sync                 # deps + dev tools
prek install            # git hooks
uv run pytest           # tests, must keep 100% coverage
prek run --all-files    # ruff check, ruff format and file hygiene hooks

Rules

• Use Conventional Commits for commit messages, e.g. feat: add alias search, fix(api): reject unknown domains, chore(deps): bump django.
• Postfix and Dovecot query the dpdapi_domain, dpdapi_alias and dpdapi_user tables directly. Never rename tables or columns, or change how values are stored (addresses are lowercased, passwords are SHA-512 crypt). tests/test_schema.py guards this.
• Django stays on 5.2 LTS (and Python 3.14) until lynx has MySQL 8.4, which Django 6 requires.
• mailadmin is the main API client. Don't change URLs, status codes or response fields it relies on; tests/test_mailadmin_contract.py replays its calls.
• Test the API through HTTP in tests/, using pytest and the fixtures in tests/conftest.py.
• Keep coverage at 100%; pytest fails below it.
• Production-only deps (gunicorn, mysqlclient) live in the prod dependency group. Production settings come from the environment (dpdapisite/settings_prod.py).