Skip to content
Public template

About

Full-stack starter: Django/DRF backend + React/Vite SPA + ops (compose, nginx edge, CI), Kubernetes-ready

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Project Template

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.

Tech stack

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

Repository layout

├── 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.

Create a project from this template

  1. On GitHub: Use this template → create your repository → clone it.

  2. 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 or node_modules. Every project gets its own APP_PORT, so several projects from this template run on one machine side by side (make init also warns if the port is already taken).

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

Prerequisites

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

Quick start

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

Everyday commands

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-cache

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

How the pieces fit

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 API contract

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.yml fails if api/openapi.yaml is stale, frontend.yml fails if schema.d.ts is 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 fails npm run typecheck, not production.

Two teams, one repository

  • Ownership by directory. CODEOWNERS assigns backend/ and frontend/ 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.yml opens 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.yml runs make audit daily and on every dependency PR: uv audit over backend/uv.lock, npm audit over frontend/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.yml runs on changes under backend/**, frontend.yml under frontend/** (both also on api/openapi.yaml). Each builds and pushes its own image: ghcr.io/<owner>/<repo>/backend and /frontend.
  • Independent deploys. deploy.yml deploys only the component that was just built, pinned to its sha-<full-sha>; on the server, ops/scripts/deploy.sh --backend <image> updates one line in .env and docker compose up -d recreates only the services whose image changed. The other component keeps running.
  • Leaving the monorepo later is cheap: git subtree split --prefix=frontend yields a repository with history, and nothing inside frontend/ has to change.

Production

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 hand

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

CI/CD (GitHub Actions)

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

Kubernetes

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.

Troubleshooting

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.

Documentation index

About

Full-stack starter: Django/DRF backend + React/Vite SPA + ops (compose, nginx edge, CI), Kubernetes-ready

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages