Full-stack starter for one product built by two teams: a Django + DRF backend, a React + Vite SPA frontend, and an ops layer that composes them, with Kubernetes-ready images from day one.
- New here? Repository layout → Prerequisites → Quick start.
- Starting a project? Create a project from this template, then docs/adapting.md.
- Backend details? backend/README.md. Frontend details (incl. Next.js)? frontend/README.md.
- Going to a server? docs/deploy.md. Going to Kubernetes? ops/k8s/README.md.
| Layer | What |
|---|---|
| Backend | Python 3.13 · Django 5.2 · DRF · drf-spectacular · Celery (+ django-celery-beat) · PostgreSQL 17 · Redis 8 · S3/MinIO for static+media · uv · Ruff · pytest · structlog |
| Frontend | React 19 · Vite 8 · TypeScript · openapi-fetch (typed client from the OpenAPI contract) · Vitest · ESLint · nginx-unprivileged image |
| Ops | Docker Compose (dev / local prod-like / pull-only prod / test) · nginx edge · GitHub Actions → GHCR · per-component path-filtered CI · SSH deploy |
├── backend/ # Django app. SELF-CONTAINED: own Dockerfile (context = backend/), uv, ruff, pytest
│ ├── apps/ config/ tests/ locale/ scripts/{entrypoint,release}.sh
│ ├── Dockerfile · Dockerfile.dev · .dockerignore · pyproject.toml · uv.lock
│ └── README.md
├── frontend/ # React SPA. SELF-CONTAINED: own Dockerfile (context = frontend/), npm
│ ├── src/ public/ nginx/default.conf.template
│ ├── Dockerfile · .dockerignore · package.json · vite.config.ts
│ └── README.md # also: how to run a Next.js frontend in this layout
├── api/
│ └── openapi.yaml # THE CONTRACT: generated by the backend, consumed by the frontend (make api-schema)
├── ops/ # everything that composes the two — no application code
│ ├── compose/ # docker-compose.yml (local, builds) · .dev.yml · .prod.yml (pull-only) · .test.yml
│ ├── nginx/ # the edge: nginx.conf (prod) · nginx.dev.conf
│ ├── scripts/ # init_env · ensure_minio · deploy · audit · dump_all · restore_all
│ ├── minio/policies/ # bucket/user policies for the shared local MinIO
│ └── k8s/README.md # Kubernetes contract + compose→k8s mapping
├── .github/workflows/ # backend.yml · frontend.yml · deploy.yml · audit.yml
├── scripts/new_project.sh # turn a copy of the template into your project (one command)
├── docs/ # adapting · deploy · backup · uv · stdimage
├── Makefile # the single entry point: `make help`
├── .env.example · CODEOWNERS · CLAUDE.md
The one rule. backend/ and frontend/ never reach outside their own directory:
each has its own Dockerfile with its own directory as build context, its own tooling and
its own CI job. ops/ is the only place that knows both exist. Images are
environment-agnostic (configuration is read at runtime), so one image goes to every
environment, and either directory can later be moved into its own repository with
git subtree split and nothing else changes.
-
On GitHub: Use this template → create your repository → clone it.
-
One command rewrites every template identifier (Compose project name, database and bucket names, image names, app title) consistently across the whole repo, deriving the names from your git remote:
scripts/new_project.sh # from git@github.com:acme/acme-shop.git → # owner acme · slug acme-shop · db acme_shop · title AcmeShop # APP_PORT: a stable hash of the slug in 8100-8999 (never 8050) # or explicitly: scripts/new_project.sh --slug acme-shop --owner acme --name "Acme Shop" --port 8120 git diff && git commit -am "[INIT] start acme-shop from project-template"
The script is idempotent and never touches
.env,.git, lockfiles ornode_modules. Every project gets its ownAPP_PORT, so several projects from this template run on one machine side by side (make initalso warns if the port is already taken). -
make init(below), then go through docs/adapting.md once: it lists the decisions that are not mechanical (time zone, languages, API auth, user activation, CODEOWNERS teams, deploy secrets).
Want template fixes to flow into existing projects later? The identifiers are isolated enough that this template can be wrapped in copier (
copier update) without restructuring; that is a deliberate second step, not a prerequisite.
| Tool | Needed for | Notes |
|---|---|---|
| Docker with the Compose plugin | everything | Docker Desktop on macOS/Windows; Docker Engine ≥ 20.10 on Linux (host.docker.internal is mapped via extra_hosts) |
| make, openssl | all commands; make init generates secrets |
preinstalled on macOS/Linux |
| Node 24+ / npm | frontend dev server, lint, tests | the frontend runs on the host, not in a container (fast HMR) |
| uv (optional) | host virtualenv for the editor, backend tests without Docker | curl -LsSf https://astral.sh/uv/install.sh | sh |
| ruff + pre-commit (optional) | git hooks: ruff for backend/, prettier + eslint for frontend/ (from frontend/node_modules) |
uv tool install ruff pre-commit, then pre-commit install |
Free host ports: 8050 (the stack, APP_PORT), 5173 (Vite), 9000/9001 (shared MinIO).
make init # ~3-5 min the first time: .env + secrets, MinIO bucket, dev stack,
# migrate, collectstatic, npm ci
make dev createsuperuser # your admin account
make dev run # Django dev server (autoreload) → API + admin at :8050
make fe-dev # Vite dev server (in another shell) → SPA at :5173 (and at :8050)| URL | What |
|---|---|
http://localhost:5173/ |
the SPA (Vite, HMR); /api/… etc. are proxied to the backend, same origin |
http://localhost:8050/ |
the same SPA through the nginx edge (proxied to Vite); 502 if Vite is not running |
http://localhost:8050/api/v1/meta/ |
first endpoint: name, version, environment, languages |
http://localhost:8050/api/docs/ |
Swagger UI (admin login required) · /api/schema/ raw schema |
http://localhost:8050/en/admin/ |
Django admin (language-prefixed; /admin/ redirects) |
http://localhost:8050/healthz/ · /readyz/ |
liveness · readiness (db + cache) |
http://localhost:9001 |
MinIO console (minioadmin / minioadmin, shared local MinIO) |
make init is idempotent. It creates .env from .env.example with every CHANGE_ME
replaced by a generated secret (never overwrites an existing .env), starts the single
shared host MinIO and provisions this project's bucket, builds and starts the dev
stack (Postgres, Redis, nginx, an idle backend container with backend/ bind-mounted),
migrates, uploads static files to the bucket, and runs npm ci in frontend/.
make help # the full list
make dev up / down / down-v # start / stop / stop and DROP volumes (database!)
make dev run # Django dev server (foreground)
make dev worker / dev beat # Celery worker / beat (foreground; the dev stack starts none by itself)
make dev bash / shell # shell in the backend container / Django shell
make dev test / lint / format
make dev makemigrations / migrate / createsuperuser / collectstatic / makemessages / compilemessages
make dev logs backend # tail a service
make fe-dev / fe-lint / fe-typecheck / fe-test / fe-build / fe-format / fe-check
make api-schema # backend → api/openapi.yaml → frontend/src/shared/api/schema.d.ts
make audit # known-vulnerability audit of both lockfiles (uv audit + npm audit)
make up / down # local PRODUCTION-LIKE stack: both images built from source, release step, gunicorn
make prod deploy # SERVER: pull the pinned images and (re)start — never builds
make minio / dump / restore / flush-cachemake dev <target> runs against the dev compose; make prod <target> against the
pull-only prod compose; no prefix = the local production-like compose. fe-* targets
run npm on the host. A typo in a target name fails loudly.
One origin. The SPA and the API are served under the same host; the edge routes by path prefix. No CORS, no API base URL to configure, cookies and CSRF just work.
| Path | Goes to |
|---|---|
/api/…, /admin/… (also /en/…, /ru/…), /rosetta/…, /__debug__/…, /healthz/, /readyz/ |
backend (gunicorn :8000) |
| everything else | frontend (static SPA, history fallback) |
That prefix list lives in three places that must stay in sync:
backend/config/urls.py, ops/nginx/nginx.conf
(+ nginx.dev.conf), and frontend/vite.config.ts. In
Kubernetes the same two rules become the Ingress.
Topologies.
dev (make dev up + make fe-dev) |
local prod-like (make up) |
prod (make prod deploy) |
|
|---|---|---|---|
| backend | runserver in the dev container, backend/ bind-mounted |
gunicorn from the built image | gunicorn from the pulled image |
| frontend | Vite on the host (:5173), proxied by the edge | nginx-unprivileged image built from frontend/ |
pulled image |
| release step | make dev migrate by hand |
release one-shot service before backend |
same |
| config | .env |
.env |
server's .env (pins BACKEND_IMAGE / FRONTEND_IMAGE) |
Images are environment-agnostic. The backend reads everything from env vars; the
frontend reads /config.js, which its nginx renders from APP_* env vars at container
start. Build arguments carry build identity only (APP_VERSION, VITE_APP_VERSION =
the git sha or tag, shown at /api/v1/meta/ and in the SPA).
Release step ≠ web process. backend/scripts/release.sh (migrate, collectstatic,
first superuser) runs once per deploy; scripts/entrypoint.sh only starts gunicorn.
N replicas can start concurrently without racing on migrations — the Kubernetes Job
model, mirrored in Compose by the release service.
The backend is the source of truth; the frontend never guesses shapes.
DRF view / serializer ──make api-schema──▶ api/openapi.yaml ──npm run api:types──▶ frontend/src/shared/api/schema.d.ts
(committed) (committed)
- After changing an endpoint:
make api-schema, commit both generated files with the change. The schema is rendered from the test image with no.env, so the output is byte-for-byte reproducible. - CI enforces it from both sides:
backend.ymlfails ifapi/openapi.yamlis stale,frontend.ymlfails ifschema.d.tsis stale. A PR that changes the contract shows the diff to both teams (CODEOWNERS). - In the SPA, call the API only through the typed client
(
frontend/src/shared/api/client.ts): a breaking backend change failsnpm run typecheck, not production.
- Ownership by directory.
CODEOWNERSassignsbackend/andfrontend/to their teams;api/,ops/and.github/need a reviewer from each. Replace the@OWNER/...placeholders with real teams. - Dependencies stay current by themselves.
.github/dependabot.ymlopens weekly PRs per ecosystem (uv, npm, Docker images, compose images, Actions), minor+patch grouped; security advisories open PRs immediately. Python and npm releases are proposed only once they are 7 days old (cooldown), which keeps a hijacked or broken release out of the lockfiles; security updates are not delayed. Django majors, Postgres majors and TypeScript majors are excluded on purpose: those are decisions, not updates. - Known vulnerabilities are checked on a clock.
audit.ymlrunsmake auditdaily and on every dependency PR:uv auditoverbackend/uv.lock,npm auditoverfrontend/package-lock.json(anything in runtime dependencies fails; in the dev toolchain, high and critical). It covers what Dependabot cannot: a fix held back by a version cap never arrives as a PR, but it does turn this job red. - Independent pipelines.
backend.ymlruns on changes underbackend/**,frontend.ymlunderfrontend/**(both also onapi/openapi.yaml). Each builds and pushes its own image:ghcr.io/<owner>/<repo>/backendand/frontend. - Independent deploys.
deploy.ymldeploys only the component that was just built, pinned to itssha-<full-sha>; on the server,ops/scripts/deploy.sh --backend <image>updates one line in.envanddocker compose up -drecreates only the services whose image changed. The other component keeps running. - Leaving the monorepo later is cheap:
git subtree split --prefix=frontendyields a repository with history, and nothing insidefrontend/has to change.
CI builds and pushes two images; the server only pulls (ops/compose/docker-compose.prod.yml
has no build:). The server holds a git checkout (compose files, nginx edge config,
scripts), its own .env, and a Docker login to GHCR.
# on the server, after docs/deploy.md step-by-step setup:
make prod deploy # pull what .env pins, up -d
ops/scripts/deploy.sh --backend ghcr.io/<owner>/<repo>/backend:sha-<sha> # pin + deploy one component
ops/scripts/deploy.sh --frontend ghcr.io/<owner>/<repo>/frontend:v1.4.0
make prod release # re-run migrations/collectstatic by handThe stack always runs behind an external reverse proxy that terminates TLS and sets
X-Forwarded-Proto; the in-stack nginx must not re-set it (details in
backend/README.md). Static and media are served
from S3/MinIO, not from nginx.
| Workflow | Trigger | Does |
|---|---|---|
backend.yml |
backend/**, api/openapi.yaml, test compose; v* tags |
pytest in Docker, schema freshness check, build+push …/backend (latest, sha-<sha>, vX.Y.Z) |
frontend.yml |
frontend/**, api/openapi.yaml; v* tags |
npm ci, types freshness, lint, typecheck, vitest, build, build+push …/frontend |
deploy.yml |
after either workflow succeeds on master (only if repo variable AUTO_DEPLOY=true), or manually with per-component tags |
SSH to the server, ops/scripts/deploy.sh |
Pull requests run the checks but never push images. A git tag vX.Y.Z push builds both
images with the version tag and does not auto-deploy. Secrets and environments:
docs/deploy.md. GitLab CI is not shipped yet; the model maps 1:1
(rules: changes: per component, GitLab Container Registry, Deploy Token for pulls).
Nothing here requires Kubernetes, but every image already honours the contract a
cluster needs: env-only configuration, stateless containers (static/media in S3, schedule
in the DB), liveness vs readiness probes that bypass ALLOWED_HOSTS, non-root users,
a separate release Job, JSON logs on stdout, one beat replica. The service-by-service
mapping, probe settings, Secret/ConfigMap split and Ingress rules are in
ops/k8s/README.md. Write the manifests when the cluster exists;
the contract is what keeps them trivial.
| Symptom | Cause → fix |
|---|---|
http://localhost:8050/ is a 502 in dev |
Expected until Vite runs: make fe-dev. The API works regardless. |
| Admin loads without CSS | Static is served from the bucket; make dev collectstatic (make init does it). |
| Images/static 404 while uploads succeed | DJANGO_MINIO_CUSTOM_URL wrong or containing the bucket path — see backend/README.md. |
make up: backend never becomes healthy |
The release service failed first: make logs release. Missing bucket (make minio), placeholder DJANGO_SUPERUSER_PASSWORD, weak secret, Postgres not ready. |
readyz returns 503 |
Database or Redis unreachable; the JSON body names the failing check. healthz stays 200 on purpose. |
| CI: "api/openapi.yaml is stale" / "Generated types are stale" | make api-schema, commit both files. |
| Frontend calls hit CORS or a wrong host | Something set APP_API_BASE_URL; leave it empty for the same-origin topology. In dev, use :5173 or :8050, both are proxied. |
ImproperlyConfigured: ENVIRONMENT must be one of … |
Only dev / test / stage / prod are accepted. |
uv sync --frozen fails in the image build |
pyproject.toml changed without re-locking — cd backend && uv lock, commit uv.lock. |
Files created by make dev makemigrations are owned by root (Linux) |
The dev container runs as root and backend/ is bind-mounted: sudo chown -R "$USER" backend/. |
| Port already allocated | Another stack uses 8050/5173/9000 — change APP_PORT / VITE_PORT / MINIO_PORT. Two clones with the same PROJECT_NAME share volumes. |
- backend/README.md — settings, storage, logging, tests, i18n, release vs entrypoint, health probes
- frontend/README.md — runtime config, typed client, tests, image, running Next.js instead
- docs/adapting.md — the non-mechanical decisions after
scripts/new_project.sh - docs/deploy.md — zero → first deploy → CI deploy on a Compose host
- docs/backup.md — dumps, restores, scheduled DB backups
- docs/uv.md, docs/stdimage.md
- ops/k8s/README.md — Kubernetes contract and mapping
- CLAUDE.md — invariants for AI coding agents working in this repo
- DEVIATIONS.md — every deviation from django-template, one row each, for selective review