A reusable Django backend to clone into new projects. Google + email auth,
WebSockets, background tasks, and feature-flagged signup — configured entirely
through environment variables, so starting a new project means editing .env,
not renaming Python modules.
Pairs with next-js-template,
the matching Next.js frontend: login and signup pages, CSRF-aware fetch, and a
WebSocket helper already wired to this API. The two are meant to be used
together.
| Auth | django-allauth headless. Google OAuth + email/password, session cookies, password reset, email verification. |
| Signup control | SIGNUP_ENABLED and SIGNUP_REQUIRES_ACCESS_CODE, enforced on every path into the user table. |
| Access codes | Revocable, expiring, use-limited invite codes with a redemption audit trail. |
| Realtime | Channels over ASGI, authenticated by the same cookie as the REST API. |
| Tasks | Celery with django-celery-beat for database-editable schedules. |
| API contract | OpenAPI schema at /api/schema/, so the frontend generates a typed client. |
| Revocation | Per-device session management, ban, sign-out-everywhere — including closing live WebSockets. |
Postgres and Redis in production; SQLite and in-process everything in development.
uv sync
cp .env.example .env
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserverThat is the whole setup. No Docker, no Redis, no Postgres required — with
DATABASE_URL and REDIS_URL unset you get SQLite, an in-memory channel layer,
inline Celery tasks, and email printed to your terminal. Setting those variables
switches each service over with no code change.
curl http://localhost:8000/api/health/
curl http://localhost:8000/api/config/| URL | |
|---|---|
/admin/ |
Django admin |
/api/docs/ |
API reference |
/api/schema/ |
OpenAPI schema |
/_allauth/openapi.html |
Auth endpoint reference |
To log in through a UI, run
next-js-template alongside. It
expects this API at http://localhost:8000 and serves on
http://localhost:3000, which is already this project's default
FRONTEND_URL, so the two line up with no extra configuration.
For local parity with Postgres and Redis, or as a base for a real deployment:
cp .env.example .env
docker compose up --buildThat builds the image and starts Postgres, Redis, the web server, a Celery
worker, and beat — docker-compose.yml, Dockerfile, and
docker/entrypoint.sh are all included. See
docs/DEPLOYMENT.md for the production checklist (TLS,
DEBUG=False, the rest of the environment variables).
git clone <this repo> my-new-backend
cd my-new-backend && rm -rf .git && git init
cp .env.example .envThen edit three lines:
PROJECT_NAME="Acme"
PROJECT_SLUG=acme
PROJECT_DESCRIPTION="Backend API for Acme"
The Django package stays config forever, so there is nothing to find and
replace. Full walkthrough in docs/NEW_PROJECT.md.
| NEW_PROJECT.md | Clone-to-running checklist. |
| ARCHITECTURE.md | Layout and the two decisions that shape it. |
| AUTHENTICATION.md | Sessions vs JWT, both login flows, account collisions, revocation. |
| FEATURE_FLAGS.md | Signup flags and access codes. |
| CONFIGURATION.md | Every environment variable. |
| WEBSOCKETS.md | Channels, consumers, closing revoked sockets. |
| BACKGROUND_TASKS.md | Celery, eager mode, Windows workers. |
| FRONTEND.md | The contract for the Next.js repo. |
| DEPLOYMENT.md | Production checklist, Docker included. |
| CONTRIBUTING.md | Dev setup and what to check before a PR. |
| SECURITY.md | Reporting a vulnerability. |
Session cookies, not JWT. The frontend and API are expected to be siblings
under one parent domain (app.example.com / api.example.com) — the same
site, so the cookie is simply sent. That makes WebSocket auth free and makes
revocation real: a session can be deleted, a JWT cannot be recalled.
One email address, one authentication method. A Google login for an address that already has a password account is refused rather than silently linked, and the error names the method the account actually uses so the frontend can point the user at the right door. Auto-linking is an account-takeover vector.
Signup flags close every path. There are three ways an account gets created — email signup, Google-as-new-user, and Google-hitting-an-existing-address — and all three are gated. The failure mode this guards against is a "signup disabled" deployment that still lets people in through Google.
Account enumeration is a setting. Helpful errors like "this email uses
Google" tell anonymous callers that an address is registered. That is on by
default because the alternative UX is bad; AUTH_DISCLOSE_ACCOUNT_EXISTENCE=False
turns it off. See the caveat in
AUTHENTICATION.md.
uv run pytest # tests
uv run ruff check . && uv run ruff format .
uv run python manage.py check --deploy # config auditWith Redis running, for the real thing:
uv run celery -A config worker --loglevel=info --pool=solo # --pool=solo on Windows
uv run celery -A config beat --loglevel=infoPython 3.12+, uv. Postgres and Redis in production only.