@django-stack/cli 0.9.0 → 0.11.0

package/templates/backend/content/tests/test_api.py

@@ -1,12 +1,13 @@
 """
 Smoke tests of the content API: every exposed model answers the read-only
 key, drafts stay hidden, and the contact form takes submissions.
-Run them with `pnpm test` at the project root.
+Run them with `{{pm_run}} test` at the project root.
 """
 
 import pytest
 from django.apps import apps
 from django.conf import settings
+from django_stack.contrib.captcha.testing import captcha_token
 from rest_framework.test import APIClient
 
 from content.models import FormSubmission, Page, Post
@@ -63,13 +64,24 @@ def test_post_by_slug(reader, seeded):
 def test_contact_form(seeded):
     response = APIClient().post(
         "/api/content.formsubmission",
-        {"name": "Ada", "email": "ada@example.com", "message": "Hello"},
+        {"name": "Ada", "email": "ada@example.com", "message": "Hello", "captcha": captcha_token()},
         format="json",
     )
     assert response.status_code == 201
     assert FormSubmission.objects.filter(email="ada@example.com").exists()
 
 
+@pytest.mark.skipif(not settings.DJANGO_STACK["CAPTCHA"], reason="the captcha is off")
+def test_contact_form_needs_a_captcha(seeded):
+    response = APIClient().post(
+        "/api/content.formsubmission",
+        {"name": "Ada", "email": "ada@example.com", "message": "Hello"},
+        format="json",
+    )
+    assert response.status_code == 400
+    assert "captcha" in response.json()
+
+
 @pytest.mark.skipif(not apps.is_installed("content_studio.notifications"), reason="notifications are off")
 def test_contact_form_notifies_the_editors(seeded, django_capture_on_commit_callbacks):
     from content_studio.notifications.models import Notification
@@ -79,7 +91,7 @@ def test_contact_form_notifies_the_editors(seeded, django_capture_on_commit_call
     with django_capture_on_commit_callbacks(execute=True):
         APIClient().post(
             "/api/content.formsubmission",
-            {"name": "Ada", "email": "ada@example.com", "message": "100% sure"},
+            {"name": "Ada", "email": "ada@example.com", "message": "100% sure", "captcha": captcha_token()},
             format="json",
         )
     notification = Notification.objects.get(recipient=editor, event="site.form_submitted")

package/templates/backend/pyproject.toml

@@ -5,7 +5,7 @@ description = "The Django backend of {{project_name}}."
 requires-python = ">=3.12"
 dependencies = [
     "Django>=6.1,<6.2",
-    "django-stack[server,s3]>=0.9.0",
+    "django-stack[server,s3]>=0.11.0",
     "django-headless[schema]>=1.1.1",
     "django-content-studio[images,huey]>=1.11.0",
 ]

package/templates/base/.github/workflows/deploy.yml

@@ -24,7 +24,9 @@ permissions:
 
 env:
   BACKEND_IMAGE: ghcr.io/${{ github.repository }}-backend:${{ github.sha }}
+  # @if frontend
   FRONTEND_IMAGE: ghcr.io/${{ github.repository }}-frontend:${{ github.sha }}
+  # @end
 
 jobs:
   deploy:
@@ -38,9 +40,11 @@ jobs:
       - name: Build and push the images
         run: |
           docker build --target prod --tag "${BACKEND_IMAGE,,}" backend
-          docker build --target prod --tag "${FRONTEND_IMAGE,,}" frontend
           docker push "${BACKEND_IMAGE,,}"
+          # @if frontend
+          docker build --target prod --tag "${FRONTEND_IMAGE,,}" frontend
           docker push "${FRONTEND_IMAGE,,}"
+          # @end
 
       - name: Set up SSH
         run: |
@@ -63,7 +67,12 @@ jobs:
             set -e
             cd '$DEPLOY_PATH'
             echo '$REGISTRY_TOKEN' | docker login ghcr.io --username '${{ github.actor }}' --password-stdin
+            # @if frontend
             export BACKEND_IMAGE='${BACKEND_IMAGE,,}' FRONTEND_IMAGE='${FRONTEND_IMAGE,,}'
+            # @end
+            # @if !frontend
+            export BACKEND_IMAGE='${BACKEND_IMAGE,,}'
+            # @end
             docker compose pull --quiet --ignore-buildable
             docker compose up -d --no-build --remove-orphans
             docker logout ghcr.io

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 `npm run generate:types`
+  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
@@ -26,23 +50,45 @@ Caddyfile                the prod profile's reverse proxy and HTTPS
 
 ## Commands
 
-Run them at the project root. They need Docker; Node is only needed for the `npm run` shortcuts.
+Run them at the project root. They need Docker; Node is only needed for the `{{pm_run}}` shortcuts.
 
 | Task | Command |
 |------|---------|
-| Start everything | `docker compose up --build` (or `npm run dev`) |
-| Run a manage.py command | `docker compose exec backend python manage.py <command>` (or `npm run backend -- <command>`) |
+| 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` |
-| Regenerate the API types after a model change | `npm run generate:types` |
-| Run the tests | `npm test` |
-| Lint and type-check | `npm run lint` |
+<!-- @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`.
-4. Run `npm run generate:types`, then read it in the frontend as
+<!-- @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,21 +49,43 @@ 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` |
-| Regenerate the API types | `npm run generate:types` |
-| Run the tests | `npm test` |
-| Check the setup | `npm run doctor` |
+<!-- @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` |
 
 With the `dstack` command installed (`npm i -g @django-stack/cli`),
 `dstack dev`, `dstack check`, `dstack manage <command>` and `dstack types` do
@@ -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
@@ -45,6 +48,14 @@ x-frontend-env: &frontend-env
   # Page analytics: the tracker loads from /_a/ on the site when set.
   UMAMI_WEBSITE_ID: ${UMAMI_WEBSITE_ID:-}
   UMAMI_URL: ${UMAMI_URL:-}
+  # The captcha widget of the contact form, unless CAPTCHA=off.
+  CAPTCHA: ${CAPTCHA:-on}
+  # Server errors to Sentry with ERRORS=sentry, as the backend's.
+  ERRORS: ${ERRORS:-email}
+  SENTRY_DSN: ${SENTRY_DSN:-}
+  SENTRY_ENVIRONMENT: ${SENTRY_ENVIRONMENT:-production}
+  SENTRY_RELEASE: ${SENTRY_RELEASE:-}
+# @end
 
 x-backend-depends: &backend-depends
   db:
@@ -91,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
@@ -117,6 +134,7 @@ services:
     logging: *logging
     restart: unless-stopped
 
+  # @if frontend
   frontend:
     profiles: [dev]
     build:
@@ -133,6 +151,7 @@ services:
         condition: service_healthy
     logging: *logging
     restart: unless-stopped
+  # @end
 
   mailpit:
     profiles: [dev]
@@ -217,6 +236,7 @@ services:
     logging: *logging
     restart: unless-stopped
 
+  # @if frontend
   frontend-prod:
     profiles: [prod]
     image: ${FRONTEND_IMAGE:-{{project_name}}-frontend}
@@ -237,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.
@@ -262,8 +283,10 @@ services:
     depends_on:
       backend-prod:
         condition: service_healthy
+      # @if frontend
       frontend-prod:
         condition: service_healthy
+      # @end
     deploy:
       resources:
         limits:
@@ -306,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
@@ -353,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
@@ -118,12 +143,24 @@ BACKUP_S3_BUCKET=
 # an Uptime Kuma push monitor, which alerts you when the pings stop.
 BACKUP_PING_URL=
 
+# The captcha of the contact form: a proof of work the visitor's browser
+# solves, served by Django at /api/cap/, with no third party. CAPTCHA=off
+# turns it off for the backend and the frontend.
+CAPTCHA=on
+
 # Error reports (with DJANGO_DEBUG=0): each new error of the backend, the
 # worker or a backup is mailed to ERROR_EMAIL (comma separated) or, when it
 # is empty, to the superusers, and shows in the admin's notifications. The
 # same error is mailed once an hour at most. ERRORS=off turns it off.
 ERRORS=email
 ERROR_EMAIL=
+# ERRORS=sentry sends the errors of the backend, the worker and the
+# frontend's server to Sentry instead: create a Django project on sentry.io
+# and paste its DSN here. SENTRY_TRACES_SAMPLE_RATE (0 to 1) also sends that
+# share of the backend's requests as performance traces.
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=production
+SENTRY_TRACES_SAMPLE_RATE=0
 
 # Logs: one JSON object per line in production, plain text in development
 # (LOG_FORMAT=json or plain). LOG_ACCESS=0 turns off Django's access log.

package/templates/frontend-astro/AGENTS.md

@@ -12,7 +12,7 @@ src/layouts/Base.astro the page shell: head, menus, footer, preview banner
 src/components/        Blocks.astro maps block types to components in components/blocks/
 src/lib/api.ts         getContent(): content helpers with the read-only key, drafts in preview
 src/lib/cache.ts       the in-memory page cache that /revalidate empties
-src/lib/headless.ts    generated API types; do not edit, run `npm run generate:types`
+src/lib/headless.ts    generated API types; do not edit, run `{{pm_run}} generate:types`
 src/middleware.ts      page cache, editor-managed redirects, security headers
 astro.config.mjs       server output, Content-Security-Policy, the dev proxy to Django
 ```
@@ -39,5 +39,5 @@ Run them in the `frontend` container (`docker compose exec frontend <command>`):
 
 | Task | Command |
 |------|---------|
-| Type-check | `npm run check` |
-| Test | `npm test` |
+| Type-check | `{{pm_run}} check` |
+| Test | `{{pm_run}} test` |

package/templates/frontend-astro/Dockerfile

@@ -7,10 +7,13 @@ WORKDIR /app
 ENV ASTRO_TELEMETRY_DISABLED=1
 
 FROM base AS deps
-COPY package.json package-lock.json* ./
+{{pm_setup}}
+COPY {{pm_manifests}} ./
 COPY vendor/ vendor/
 # No BuildKit cache mounts: Railway rejects them, and the layer is cached anyway.
-RUN if [ -f package-lock.json ]; then npm ci; else npm install; fi
+RUN {{pm_install}}
+# The package manager only installs: npm, which comes with Node.js, runs
+# the scripts of package.json below.
 
 FROM deps AS dev
 EXPOSE 3000
@@ -21,7 +24,7 @@ CMD ["sh", "-c", "rm -f .astro/dev.json && exec npm run dev"]
 
 FROM deps AS build
 COPY . .
-RUN npm run build && npm prune --omit=dev
+RUN npm run build && {{pm_prune}}
 
 FROM base AS prod
 ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000