Skip to content

About

Reusable Django backend template: Google + email auth (allauth), WebSockets (Channels), Celery tasks, feature-flagged signup with access codes, session revocation. Env-driven config, Docker-ready.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Django Backend Template

CI

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.

What is in it

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.

Quick start

uv sync
cp .env.example .env
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver

That 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.

Docker

For local parity with Postgres and Redis, or as a base for a real deployment:

cp .env.example .env
docker compose up --build

That 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).

Using it for a new project

git clone <this repo> my-new-backend
cd my-new-backend && rm -rf .git && git init
cp .env.example .env

Then 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.

Documentation

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.

A few decisions worth knowing up front

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.

Development

uv run pytest                              # tests
uv run ruff check . && uv run ruff format .
uv run python manage.py check --deploy     # config audit

With 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=info

Requirements

Python 3.12+, uv. Postgres and Redis in production only.

About

Reusable Django backend template: Google + email auth (allauth), WebSockets (Channels), Celery tasks, feature-flagged signup with access codes, session revocation. Env-driven config, Docker-ready.

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages