@django-stack/cli 0.10.0 → 0.11.0

package/templates/base/AGENTS.md

@@ -1,9 +1,23 @@
 # {{project_name}}: guide for AI agents
 
+<!-- @if frontend -->
 A website built with DjangoStack: a Django backend (Django Headless serves
 the content API, Django Content Studio is the admin) and a frontend built
 with {{frontend_label}} that renders the content, run with Docker Compose.
 `frontend/AGENTS.md` describes the frontend.
+<!-- @end -->
+<!-- @if headless -->
+A headless project built with DjangoStack: a Django backend (Django Headless
+serves the content API, Django Content Studio is the admin), run with Docker
+Compose. It has no frontend; other apps read the API with the read-only key.
+<!-- @end -->
+<!-- @if templates -->
+A website built with DjangoStack: a Django backend (Django Headless serves
+the content API, Django Content Studio is the admin) that also renders the
+site with Django templates, in the `website` app, run with Docker Compose.
+There is no Node and no frontend service: the pages read the content with
+the ORM.
+<!-- @end -->
 
 ## Layout
 
@@ -16,8 +30,18 @@ backend/                 Django project
   content/admin.py       how each model looks in the admin (studios)
   content/seed.py        demo content
   content/tests/         pytest tests of the API
+<!-- @if templates -->
+  website/views.py       the site's pages; they read content with published(), which hides drafts outside preview
+  website/urls.py        the site's routes, included last in config/urls.py
+  website/templates/website/  base.html (the layout), the pages, includes/ and blocks/ (one template per block type)
+  website/static/website/global.css  the site's stylesheet
+  website/forms.py       the contact form, with the captcha
+  website/tests/         pytest tests of the pages
+<!-- @end -->
+<!-- @if frontend -->
 frontend/                the {{frontend_label}} site; frontend/AGENTS.md lists its files
   src/lib/headless.ts    generated API types; do not edit, run `{{pm_run}} generate:types`
+<!-- @end -->
 compose.yaml             every service; COMPOSE_PROFILES in .env picks dev or prod
 Caddyfile                the prod profile's reverse proxy and HTTPS
 .github/workflows/deploy.yml  optional deploy to a server over SSH
@@ -33,16 +57,38 @@ Run them at the project root. They need Docker; Node is only needed for the `{{p
 | Start everything | `docker compose up --build` (or `{{pm_run}} dev`) |
 | Run a manage.py command | `docker compose exec backend python manage.py <command>` (or `{{pm_backend}} <command>`) |
 | Make migrations after a model change | `docker compose exec backend python manage.py makemigrations` |
+<!-- @if frontend -->
 | Regenerate the API types after a model change | `{{pm_run}} generate:types` |
+<!-- @end -->
+<!-- @if !frontend -->
+| Write the OpenAPI schema to `backend/openapi.json` | `{{pm_run}} generate:types` |
+<!-- @end -->
 | Run the tests | `{{pm_run}} test` |
+<!-- @if frontend -->
 | Lint and type-check | `{{pm_run}} lint` |
+<!-- @end -->
+<!-- @if !frontend -->
+| Lint | `{{pm_run}} lint` |
+<!-- @end -->
 | Logs | `docker compose logs --follow backend` |
 | Production settings for a server | `npx @django-stack/cli production --domain example.com` |
 
+<!-- @if frontend -->
 In production (`COMPOSE_PROFILES=prod,db`) the services are `backend-prod`,
 `worker-prod` (which also runs the daily backup), `frontend-prod` and
 `proxy`, with `umami` for page analytics when the `analytics` profile is on;
 their containers are
+<!-- @end -->
+<!-- @if headless -->
+In production (`COMPOSE_PROFILES=prod,db`) the services are `backend-prod`,
+`worker-prod` (which also runs the daily backup) and `proxy`; their
+containers are
+<!-- @end -->
+<!-- @if templates -->
+In production (`COMPOSE_PROFILES=prod,db`) the services are `backend-prod`,
+`worker-prod` (which also runs the daily backup) and `proxy`, with `umami`
+for page analytics when the `analytics` profile is on; their containers are
+<!-- @end -->
 read-only, so a change goes through the code and a new image, never an edit
 in a running container.
 
@@ -54,23 +100,55 @@ in a running container.
    `ModelStudio`.
 3. Run `makemigrations`; the backend migrates on its next start, or run
    `migrate`.
+<!-- @if frontend -->
 4. Run `{{pm_run}} generate:types`, then read it in the frontend as
    `frontend/AGENTS.md` shows.
+<!-- @end -->
+<!-- @if headless -->
+4. Its routes are under `/api/`; `/api/schema` describes them.
+<!-- @end -->
+<!-- @if templates -->
+4. Show it on the site: a view in `backend/website/views.py` that reads it
+   with `published(Model.objects.all(), request)` when it has a status, a
+   route in `website/urls.py` and a template in `website/templates/website/`.
+   Decorate the view with `@site_page`, which caches the page until content
+   changes and sets the Content-Security-Policy.
+<!-- @end -->
 5. Add an API smoke test to `backend/content/tests/test_api.py`.
 
 ## How to add a block type
 
 1. Add a `Block` subclass in `backend/content/blocks.py` and add it to
    `BODY_BLOCKS`. Blocks need no migration.
+<!-- @if frontend -->
 2. Render it in the frontend as `frontend/AGENTS.md` shows.
+<!-- @end -->
+<!-- @if templates -->
+2. Add `backend/website/templates/website/blocks/<type>.html`; it gets the
+   block's fields as `value`. `{% blocks page.body %}` renders nothing for
+   a type without a template.
+<!-- @end -->
 
 ## Rules
 
 - Never edit `.env` values you were not asked to change, and never print secrets.
 - Never write migrations by hand; use `makemigrations`.
+<!-- @if !templates -->
 - The frontend only ever holds `API_READ_KEY`. Never give it `API_SECRET_KEY`.
+<!-- @end -->
 - API routes are closed by default. Opening a model to anonymous writes goes
   through `DJANGO_STACK["PUBLIC_CREATE"]` in `config/settings.py`, and is
   rate limited.
+<!-- @if frontend -->
 - Django owns `/admin`, `/api`, `/media` and `/static`; frontend routes must
   not use these prefixes.
+<!-- @end -->
+<!-- @if templates -->
+- `/admin`, `/api`, `/media`, `/static` and `/_a` are taken; site routes
+  must not use these prefixes.
+- The site's pages use no inline scripts or styles: the
+  Content-Security-Policy of `@site_page` blocks them. Add files to
+  `website/static/website/` instead.
+- HTML from an `HTMLField` (`|safe`) is sanitized when it is saved; never
+  mark other text safe.
+<!-- @end -->

package/templates/base/Caddyfile

@@ -1,8 +1,19 @@
 # {{project_name}}: the reverse proxy of the prod profile.
 #
+# @if frontend
 # One domain: Django serves /admin, /api and /static; uploads on the server's
 # disk are served from /media; Umami's tracker from /_a/; the frontend
 # serves everything else. Caddy
+# @end
+# @if headless
+# One domain: Django serves everything (the API, the admin, /static and a
+# start page); uploads on the server's disk are served from /media. Caddy
+# @end
+# @if templates
+# One domain: Django serves everything (the pages, the API, the admin and
+# /static); uploads on the server's disk are served from /media; Umami's
+# tracker from /_a/. Caddy
+# @end
 # gets and renews the HTTPS certificate for SITE_URL by itself.
 #
 # Behind a platform's proxy (Coolify, Dokploy), CADDY_ADDRESS=:80 serves
@@ -54,6 +65,7 @@
 		}
 	}
 
+	# @if frontend
 	@django path /admin /admin/* /api /api/* /static/*
 	handle @django {
 		reverse_proxy backend:8000
@@ -62,6 +74,18 @@
 	handle {
 		reverse_proxy frontend:3000
 	}
+	# @end
+	# @if !frontend
+	# The health checks are for Docker and the platforms, not the public.
+	@health path /healthz /readyz /statusz
+	handle @health {
+		respond 404
+	}
+
+	handle {
+		reverse_proxy backend:8000
+	}
+	# @end
 
 	log {
 		output stdout

package/templates/base/README.md

@@ -1,11 +1,29 @@
 # {{project_name}}
 
+<!-- @if frontend -->
 A website with a Django backend and a frontend built with {{frontend_label}}, created with
 [DjangoStack](https://github.com/dwarsbit/django-stack).
+<!-- @end -->
+<!-- @if headless -->
+A content API and an admin with Django, created with
+[DjangoStack](https://github.com/dwarsbit/django-stack). It has no frontend:
+build your own against the API, with the read-only key.
+<!-- @end -->
+<!-- @if templates -->
+A website with Django, created with
+[DjangoStack](https://github.com/dwarsbit/django-stack): Django renders the
+pages with its templates, from the content the API also serves.
+<!-- @end -->
 
 - [Django Headless](https://djangoheadless.org) serves the content API.
 - [Django Content Studio](https://djangocontentstudio.org) is the admin.
+<!-- @if frontend -->
 - [{{frontend_label}}]({{frontend_url}}) renders the site.
+<!-- @end -->
+<!-- @if templates -->
+- [Django templates]({{frontend_url}}) render the site: the `website` app
+  in `backend/website/`.
+<!-- @end -->
 - Postgres stores the content, and by default also the cache and the task
   queue (`CACHE_URL` and `TASKS_URL` in `.env`); Valkey can take those over
   with the `valkey` profile.
@@ -18,7 +36,12 @@ You need Docker.
 docker compose up --build
 ```
 
+<!-- @if site -->
 - Site: http://localhost:{{site_port}}
+<!-- @end -->
+<!-- @if headless -->
+- API: http://localhost:{{site_port}}/api/ (with the `X-Secret-Key` header set to `API_READ_KEY` in `.env`), its OpenAPI schema at `/api/schema`
+<!-- @end -->
 - Admin: http://localhost:{{site_port}}/admin/ (user `admin`, password `ADMIN_PASSWORD` in `.env`)
 - Outgoing mail: http://localhost:{{mail_port}}
 
@@ -26,19 +49,41 @@ The ports are `SITE_PORT` and `MAIL_PORT` in `.env`. When you change
 `SITE_PORT`, change `SITE_URL` and `BACKEND_URL` with it.
 
 The first start migrates the database, creates the admin user and adds demo
+<!-- @if site -->
 content. Edit a page in the admin, publish, and reload the site.
+<!-- @end -->
+<!-- @if headless -->
+content. Edit a page in the admin, publish, and read it from the API.
+<!-- @end -->
 
 ## Develop
 
+<!-- @if frontend -->
 Both sides reload on save: the backend runs Django's development server and
 the frontend {{frontend_label}}'s, with the source mounted from `backend/` and
 `frontend/`. `AGENTS.md` lists the layout and the commands.
+<!-- @end -->
+<!-- @if headless -->
+The backend reloads on save: it runs Django's development server, with the
+source mounted from `backend/`. `AGENTS.md` lists the layout and the commands.
+<!-- @end -->
+<!-- @if templates -->
+The site reloads on save, templates and CSS included: the backend runs
+Django's development server, with the source mounted from `backend/`. The
+pages are in `backend/website/`; `AGENTS.md` lists the layout and the
+commands.
+<!-- @end -->
 
 | Task | Command |
 |------|---------|
 | Run a manage.py command | `docker compose exec backend python manage.py <command>` |
 | Make migrations | `docker compose exec backend python manage.py makemigrations` |
+<!-- @if frontend -->
 | Regenerate the API types | `{{pm_run}} generate:types` |
+<!-- @end -->
+<!-- @if !frontend -->
+| Write the OpenAPI schema to `backend/openapi.json` | `{{pm_run}} generate:types` |
+<!-- @end -->
 | Run the tests | `{{pm_run}} test` |
 | Check the setup | `{{pm_run}} doctor` |
 
@@ -53,9 +98,23 @@ Pages and posts have a status. Drafts and posts with a future publish date
 are not served by the API. The **Preview** button in the admin opens the
 site with drafts shown, for an hour.
 
+<!-- @if frontend -->
 When an editor saves, Django tells the frontend (`REVALIDATE_URL`), which
 empties its page cache, so the change shows on the next visit.
-
+<!-- @end -->
+<!-- @if headless -->
+The button opens `/preview` on `SITE_URL`, which your frontend serves; set
+`REVALIDATE_URL` to the endpoint where your frontend empties its page cache,
+and Django calls it when an editor saves. See
+[Preview and revalidation](https://dwarsbit.github.io/django-stack/docs/preview-revalidation).
+<!-- @end -->
+<!-- @if templates -->
+The site keeps each page in Django's cache, and empties it when an editor
+saves, so the change shows on the next visit. In preview the cache is
+skipped.
+<!-- @end -->
+
+<!-- @if site -->
 ## Analytics
 
 When `COMPOSE_PROFILES` in `.env` has `analytics`, the `umami` service
@@ -64,6 +123,7 @@ counts page views without cookies, and the admin shows them under
 page views pass through the site at `/_a/`. To turn it off, remove
 `analytics` from `COMPOSE_PROFILES` and empty `UMAMI_URL`. See
 [Page analytics](https://dwarsbit.github.io/django-stack/docs/analytics).
+<!-- @end -->
 
 ## Deploy
 
@@ -91,9 +151,17 @@ has every step.
 
 ## Security
 
+<!-- @if !templates -->
 - The API answers only requests with a key. The frontend holds the
-  read-only key (`API_READ_KEY`) and uses it on the server only.
-- `API_SECRET_KEY` can write: keep it for scripts and never give it to the
+  read-only key (`API_READ_KEY`) and uses it on the server only, never in
+  the browser.
+<!-- @end -->
+<!-- @if templates -->
+- The API answers only requests with a key. The site reads the content
+  in Django and needs none; the read-only key (`API_READ_KEY`) is for other
+  apps, on their server, never in a browser.
+<!-- @end -->
+- `API_SECRET_KEY` can write: keep it for scripts and never give it to a
   frontend.
 - `.env` holds every secret. It is generated with random values and is not
   committed.

package/templates/base/SECURITY.md

@@ -9,4 +9,6 @@ Problems in the packages it is built on go to their projects:
 - Django Headless: https://github.com/dwarsbit/django-headless/security
 - Django Content Studio: https://github.com/dwarsbit/django-content-studio/security
 - Django: https://www.djangoproject.com/security/
+<!-- @if frontend -->
 - {{frontend_label}}: {{frontend_security}}
+<!-- @end -->

package/templates/base/compose.yaml

@@ -10,9 +10,11 @@
 #   `s3` in development for a local S3 service (see .env). `analytics` runs
 #   Umami for page analytics, `valkey` the Valkey service for CACHE_URL or
 #   TASKS_URL.
+# @if frontend
 #
 # The frontend only receives the variables it needs: never the full-access
 # API key or the database password.
+# @end
 
 name: {{project_name}}
 
@@ -34,6 +36,7 @@ x-logging: &logging
     max-size: 10m
     max-file: "5"
 
+# @if frontend
 x-frontend-env: &frontend-env
   SITE_URL: ${SITE_URL}
   API_URL: http://backend:8000/api
@@ -52,6 +55,7 @@ x-frontend-env: &frontend-env
   SENTRY_DSN: ${SENTRY_DSN:-}
   SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT:-production}
   SENTRY_RELEASE: ${SENTRY_RELEASE:-}
+# @end
 
 x-backend-depends: &backend-depends
   db:
@@ -98,7 +102,13 @@ services:
       - ./backend:/app
       - media:/app/media
     ports:
+      # @if frontend
       - "127.0.0.1:${BACKEND_PORT:-8000}:8000"
+      # @end
+      # @if !frontend
+      # The site is the backend: the API, the admin and the pages.
+      - "127.0.0.1:${SITE_PORT:-3000}:8000"
+      # @end
     depends_on: *backend-depends
     healthcheck: *backend-health
     logging: *logging
@@ -124,6 +134,7 @@ services:
     logging: *logging
     restart: unless-stopped
 
+  # @if frontend
   frontend:
     profiles: [dev]
     build:
@@ -140,6 +151,7 @@ services:
         condition: service_healthy
     logging: *logging
     restart: unless-stopped
+  # @end
 
   mailpit:
     profiles: [dev]
@@ -224,6 +236,7 @@ services:
     logging: *logging
     restart: unless-stopped
 
+  # @if frontend
   frontend-prod:
     profiles: [prod]
     image: ${FRONTEND_IMAGE:-{{project_name}}-frontend}
@@ -244,6 +257,7 @@ services:
           memory: 512M
     logging: *logging
     restart: unless-stopped
+  # @end
 
   # The only service with public ports: HTTPS for SITE_URL with a
   # certificate from Let's Encrypt, routing to Django and the frontend.
@@ -269,8 +283,10 @@ services:
     depends_on:
       backend-prod:
         condition: service_healthy
+      # @if frontend
       frontend-prod:
         condition: service_healthy
+      # @end
     deploy:
       resources:
         limits:
@@ -313,13 +329,14 @@ services:
 
   db:
     profiles: [db]
-    image: postgres:17-alpine
+    image: postgres:{{postgres_version}}-alpine
     environment:
       POSTGRES_DB: ${POSTGRES_DB:-app}
       POSTGRES_USER: ${POSTGRES_USER:-app}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
     volumes:
-      - pgdata:/var/lib/postgresql/data
+      # A new major version needs a dump and a restore: see the backups docs.
+      - pgdata:{{postgres_data}}
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
       interval: 3s
@@ -360,6 +377,8 @@ volumes:
   media:
   backups:
   s3data:
+  # @if frontend
   frontend_node_modules:
+  # @end
   caddy_data:
   caddy_config:

package/templates/base/env.example

@@ -12,9 +12,20 @@ PROJECT_NAME={{project_name}}
 # the Valkey service.
 COMPOSE_PROFILES=dev,db
 
+# @if frontend
 # The public URL of the site. In development the frontend's dev server also
 # serves /admin, /api and /media, so both URLs are the frontend's. In
 # production set both to https://your-domain: Caddy gets the certificate.
+# @end
+# @if headless
+# The public URL of the API and the admin. In production set both to
+# https://your-domain: Caddy gets the certificate.
+# @end
+# @if templates
+# The public URL of the site, which Django renders with the API and the
+# admin. In production set both to https://your-domain: Caddy gets the
+# certificate.
+# @end
 SITE_URL=http://localhost:3000
 BACKEND_URL=http://localhost:3000
 
@@ -42,6 +53,10 @@ POSTGRES_DB=app
 POSTGRES_USER=app
 POSTGRES_PASSWORD={{secret:postgres}}
 DATABASE_URL=postgres://app:{{secret:postgres}}@db:5432/app
+# Production only: an external Postgres for the server, such as a managed
+# one. `dstack production` makes it DATABASE_URL in .env.production and
+# leaves out `db`; development keeps the bundled Postgres above.
+PRODUCTION_DATABASE_URL=
 
 # Cache and task queue: db:// keeps them in tables in the database, so
 # nothing else runs. For the Valkey service add `valkey` to COMPOSE_PROFILES
@@ -66,7 +81,17 @@ API_READ_KEY={{secret:api_read}}
 # Shared between Django and the frontend: preview links and revalidation.
 PREVIEW_SECRET={{secret:preview}}
 REVALIDATE_SECRET={{secret:revalidate}}
+# @if frontend
 REVALIDATE_URL=http://frontend:3000/revalidate
+# @end
+# @if headless
+# Your frontend's endpoint that empties its page cache when content changes.
+REVALIDATE_URL=
+# @end
+# @if templates
+# Empty: Django renders the site and empties its own page cache.
+REVALIDATE_URL=
+# @end
 
 # The first admin user, created on the first start.
 ADMIN_USERNAME=admin

package/templates/frontend-astro/package.json

@@ -16,7 +16,7 @@
     "@astrojs/node": "^11.1.9",
     "@astrojs/rss": "^4.0.19",
     "@django-headless/client": "^1.1.1",
-    "@django-stack/utils": "^0.10.0",
+    "@django-stack/utils": "^0.11.0",
     "astro": "^7.4.5"
   },
   "devDependencies": {

package/templates/frontend-next/package.json

@@ -13,9 +13,9 @@
   },
   "dependencies": {
     "@django-headless/client": "^1.1.1",
-    "@django-stack/next": "^0.10.0",
-    "@django-stack/react": "^0.10.0",
-    "@django-stack/utils": "^0.10.0",
+    "@django-stack/next": "^0.11.0",
+    "@django-stack/react": "^0.11.0",
+    "@django-stack/utils": "^0.11.0",
     "next": "^16.4.4",
     "react": "^19.3.1",
     "react-dom": "^19.3.1",

package/templates/frontend-nuxt/package.json

@@ -15,8 +15,8 @@
   },
   "dependencies": {
     "@django-headless/client": "^1.1.1",
-    "@django-stack/utils": "^0.10.0",
-    "@django-stack/vue": "^0.10.0",
+    "@django-stack/utils": "^0.11.0",
+    "@django-stack/vue": "^0.11.0",
     "nuxt": "^4.6.3",
     "nuxt-security": "^2.7.0",
     "vue": "^3.5.44",

package/templates/frontend-sveltekit/package.json

@@ -19,8 +19,8 @@
   },
   "dependencies": {
     "@django-headless/client": "^1.1.1",
-    "@django-stack/svelte": "^0.10.0",
-    "@django-stack/utils": "^0.10.0"
+    "@django-stack/svelte": "^0.11.0",
+    "@django-stack/utils": "^0.11.0"
   },
   "devDependencies": {
     "@sveltejs/adapter-node": "^6.0.1",

package/templates/frontend-templates/template.json

@@ -0,0 +1,5 @@
+{
+  "label": "Django templates",
+  "url": "https://docs.djangoproject.com/en/6.1/topics/templates/",
+  "security": "https://www.djangoproject.com/security/"
+}

package/templates/frontend-templates/website/apps.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class WebsiteConfig(AppConfig):
+    name = "website"
+    verbose_name = "Website"

package/templates/frontend-templates/website/context_processors.py

@@ -0,0 +1,16 @@
+from django.utils.functional import SimpleLazyObject
+
+from content.models import Menu, SiteSettings
+
+
+def menu(slug):
+    return Menu.objects.filter(slug=slug).first()
+
+
+def site(request):
+    """The site settings and the menus, for base.html; read only when a template uses them."""
+    return {
+        "site": SimpleLazyObject(lambda: SiteSettings.objects.select_related("home_page").first()),
+        "main_menu": SimpleLazyObject(lambda: menu("main")),
+        "footer_menu": SimpleLazyObject(lambda: menu("footer")),
+    }

package/templates/frontend-templates/website/forms.py

@@ -0,0 +1,20 @@
+from django import forms
+from django_stack.contrib.captcha.forms import CaptchaField
+
+from content.models import FormSubmission
+
+
+class ContactForm(forms.ModelForm):
+    """The contact form; submissions appear in the admin under Form submissions."""
+
+    # The widget of the captcha; CAPTCHA=off leaves it out.
+    captcha = CaptchaField(label="")
+
+    class Meta:
+        model = FormSubmission
+        fields = ["name", "email", "message"]
+        widgets = {
+            "name": forms.TextInput(attrs={"autocomplete": "name"}),
+            "email": forms.EmailInput(attrs={"autocomplete": "email"}),
+            "message": forms.Textarea(attrs={"rows": 6}),
+        }

package/templates/frontend-templates/website/static/website/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#0c4b33"/><path d="M8 9h10a6 6 0 0 1 0 12h-4v3H8z" fill="#44b78b"/><path d="M14 13h4a2 2 0 0 1 0 4h-4z" fill="#0c4b33"/></svg>