@django-stack/cli 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -93,7 +93,7 @@ export declare const STACK_OPTIONS: readonly [{
     readonly value: "umami";
     readonly label: "Umami";
     readonly hint: "built in, private, no cookies";
-    readonly generated: false;
+    readonly generated: true;
   }, {
     readonly value: "off";
     readonly label: "Off";
@@ -235,6 +235,8 @@ interface ScaffoldOptions {
   databaseUrl?: string;
   /** Store uploads in the local S3 service in development, like S3 in production. */
   localS3?: boolean;
+  /** Page analytics with the bundled Umami (the `analytics` profile). */
+  analytics?: boolean;
   /** A DjangoStack monorepo to take the packages from instead of the registries (for development). */
   link?: string;
   /** The time zone of the backend, such as Europe/Amsterdam. UTC by default. */

package/dist/index.js

@@ -1 +1 @@
-export { f as DEFAULT_STACK, t as FRONTENDS, p as NAMED_PRESETS, m as STACK_OPTIONS, d as VERSION, g as decodePreset, _ as encodePreset, C as generateProjectSecrets, w as generateSecret, i as normalizeDatabaseUrl, D as parseEnv, v as pendingChoices, x as productionEnv, y as resolvePreset, T as runDoctor, o as scaffold, O as setEnvValues, c as toProjectName, S as validateDomain, l as validateProjectName } from "./scaffold-DbgGYEsc.js";
+export { h as DEFAULT_STACK, r as FRONTENDS, g as NAMED_PRESETS, _ as STACK_OPTIONS, m as VERSION, y as decodePreset, b as encodePreset, w as generateProjectSecrets, T as generateSecret, o as normalizeDatabaseUrl, O as parseEnv, x as pendingChoices, t as productionEnv, S as resolvePreset, E as runDoctor, c as scaffold, k as setEnvValues, u as toProjectName, n as validateDomain, f as validateProjectName } from "./production-DIj9yRcg.js";

package/dist/{scaffold-DbgGYEsc.js → production-DIj9yRcg.js}

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { execFileSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 // src/env.ts
 /** Reads a .env file: KEY=value lines, comments and blank lines ignored. */
@@ -283,69 +283,9 @@ function generateProjectSecrets() {
 		api_read: generateSecret(32),
 		preview: generateSecret(32),
 		revalidate: generateSecret(32),
-		admin: generateSecret(12)
-	};
-}
-// src/production.ts
-function validateDomain(domain) {
-	if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i.test(domain)) return "Enter a domain name such as example.com, without https://.";
-}
-/**
-* The .env for a server, from a project's development .env: the prod
-* profile, HTTPS on the domain, and fresh secrets, so nothing from the
-* laptop works on the server.
-*/
-function productionEnv(devEnv, options) {
-	const domainError = validateDomain(options.domain);
-	if (domainError) throw new Error(domainError);
-	const current = parseEnv(devEnv);
-	const secrets = generateProjectSecrets();
-	const url = `https://${options.domain.toLowerCase()}`;
-	const todo = [];
-	const profiles = (current.COMPOSE_PROFILES ?? "dev,db").split(",").map((profile) => profile.trim()).filter((profile) => profile && profile !== "dev" && profile !== "s3");
-	profiles.unshift("prod");
-	const values = {
-		COMPOSE_PROFILES: [...new Set(profiles)].join(","),
-		SITE_URL: url,
-		BACKEND_URL: url,
-		DJANGO_DEBUG: "0",
-		DJANGO_SECRET_KEY: secrets.django ?? "",
-		API_SECRET_KEY: secrets.api ?? "",
-		API_READ_KEY: secrets.api_read ?? "",
-		PREVIEW_SECRET: secrets.preview ?? "",
-		REVALIDATE_SECRET: secrets.revalidate ?? "",
-		ADMIN_PASSWORD: secrets.admin ?? "",
-		DEFAULT_FROM_EMAIL: `${current.PROJECT_NAME ?? "site"} <noreply@${options.domain.toLowerCase()}>`
-	};
-	if (profiles.includes("db")) {
-		const user = current.POSTGRES_USER || "app";
-		const name = current.POSTGRES_DB || "app";
-		values.POSTGRES_PASSWORD = secrets.postgres ?? "";
-		values.DATABASE_URL = `postgres://${user}:${secrets.postgres}@db:5432/${name}`;
-	}
-	if (options.emailUrl) values.EMAIL_URL = options.emailUrl;
-	else if (!current.EMAIL_URL || current.EMAIL_URL.includes("mailpit")) {
-		values.EMAIL_URL = "smtp+tls://user:password@smtp.example.com:587";
-		todo.push("Set EMAIL_URL to your SMTP server, so password resets and notifications are sent.");
-	}
-	if ((current.S3_ENDPOINT_URL ?? "").includes("s3:8333")) {
-		Object.assign(values, {
-			S3_BUCKET: "",
-			S3_ENDPOINT_URL: "",
-			S3_REGION: "",
-			S3_ACCESS_KEY_ID: "",
-			S3_SECRET_ACCESS_KEY: "",
-			S3_PUBLIC_URL: "",
-			S3_CREATE_BUCKET: "0"
-		});
-		todo.push("Set the S3_* variables to your S3 service, or leave them empty to keep uploads on the server.");
-	}
-	if (!current.ADMIN_EMAIL || current.ADMIN_EMAIL.endsWith("@example.com")) todo.push("Set ADMIN_EMAIL to your address.");
-	if (current.SEED_DEMO_CONTENT === "1") todo.push("Set SEED_DEMO_CONTENT=0 unless the site should start with the demo pages and posts.");
-	return {
-		text: setEnvValues(devEnv, values),
-		adminPassword: values.ADMIN_PASSWORD ?? "",
-		todo
+		admin: generateSecret(12),
+		umami_app: generateSecret(32),
+		umami_admin: generateSecret(24)
 	};
 }
 // src/stack.ts
@@ -420,7 +360,7 @@ const STACK_OPTIONS = [
 			value: "umami",
 			label: "Umami",
 			hint: "built in, private, no cookies",
-			generated: false
+			generated: true
 		}, {
 			value: "off",
 			label: "Off",
@@ -642,6 +582,22 @@ const CLI_VERSION = createRequire(import.meta.url)("../package.json").version;
 // src/scaffold.ts
 /** The frontends this version of the CLI generates. */
 const FRONTENDS = stackOption("frontend").values.filter((value) => value.generated).map((value) => value.value);
+/** Umami's database URL: the project's database, with Umami's tables in the `umami` schema. */
+function umamiDatabaseUrl(databaseUrl) {
+	const url = new URL(databaseUrl);
+	url.searchParams.set("schema", "umami");
+	return url.toString();
+}
+/** The `.env` values of the bundled Umami, from the project's database URL and secrets. */
+function umamiEnv(databaseUrl, secrets) {
+	return {
+		UMAMI_URL: "http://umami:3000",
+		UMAMI_WEBSITE_ID: randomUUID(),
+		UMAMI_ADMIN_PASSWORD: secrets.umami_admin ?? "",
+		UMAMI_APP_SECRET: secrets.umami_app ?? "",
+		UMAMI_DATABASE_URL: umamiDatabaseUrl(databaseUrl)
+	};
+}
 /** The local S3 service of the `s3` profile. It accepts any credentials. */
 const LOCAL_S3 = {
 	S3_BUCKET: "media",
@@ -749,6 +705,10 @@ function scaffold(options) {
 		profiles.push("s3");
 		env = setEnvValues(env, LOCAL_S3);
 	}
+	if (options.analytics) {
+		profiles.push("analytics");
+		env = setEnvValues(env, umamiEnv(parseEnv(env).DATABASE_URL ?? "", secrets));
+	}
 	env = setEnvValues(env, { COMPOSE_PROFILES: profiles.join(",") });
 	if (!options.demoContent) env = setEnvValues(env, { SEED_DEMO_CONTENT: "0" });
 	writeFileSync(join(target, ".env"), env, { mode: 384 });
@@ -830,4 +790,71 @@ function relativeDirectory(directory) {
 	const path = relative(process.cwd(), directory) || ".";
 	return path.startsWith("..") ? directory : path;
 }
-export { generateProjectSecrets as C, parseEnv as D, checkTools as E, setEnvValues as O, validateDomain as S, runDoctor as T, encodePreset as _, relativeDirectory as a, stackOption as b, toProjectName as c, CLI_VERSION as d, DEFAULT_STACK as f, decodePreset as g, applies as h, normalizeDatabaseUrl as i, validateProjectName as l, STACK_OPTIONS as m, LOCAL_S3 as n, scaffold as o, NAMED_PRESETS as p, lockBackend as r, timeZones as s, FRONTENDS as t, validateTimeZone as u, pendingChoices as v, generateSecret as w, productionEnv as x, resolvePreset as y };
+// src/production.ts
+function validateDomain(domain) {
+	if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i.test(domain)) return "Enter a domain name such as example.com, without https://.";
+}
+/**
+* The .env for a server, from a project's development .env: the prod
+* profile, HTTPS on the domain, and fresh secrets, so nothing from the
+* laptop works on the server.
+*/
+function productionEnv(devEnv, options) {
+	const domainError = validateDomain(options.domain);
+	if (domainError) throw new Error(domainError);
+	const current = parseEnv(devEnv);
+	const secrets = generateProjectSecrets();
+	const url = `https://${options.domain.toLowerCase()}`;
+	const todo = [];
+	const profiles = (current.COMPOSE_PROFILES ?? "dev,db").split(",").map((profile) => profile.trim()).filter((profile) => profile && profile !== "dev" && profile !== "s3");
+	profiles.unshift("prod");
+	const values = {
+		COMPOSE_PROFILES: [...new Set(profiles)].join(","),
+		SITE_URL: url,
+		BACKEND_URL: url,
+		DJANGO_DEBUG: "0",
+		DJANGO_SECRET_KEY: secrets.django ?? "",
+		API_SECRET_KEY: secrets.api ?? "",
+		API_READ_KEY: secrets.api_read ?? "",
+		PREVIEW_SECRET: secrets.preview ?? "",
+		REVALIDATE_SECRET: secrets.revalidate ?? "",
+		ADMIN_PASSWORD: secrets.admin ?? "",
+		DEFAULT_FROM_EMAIL: `${current.PROJECT_NAME ?? "site"} <noreply@${options.domain.toLowerCase()}>`
+	};
+	if (profiles.includes("db")) {
+		const user = current.POSTGRES_USER || "app";
+		const name = current.POSTGRES_DB || "app";
+		values.POSTGRES_PASSWORD = secrets.postgres ?? "";
+		values.DATABASE_URL = `postgres://${user}:${secrets.postgres}@db:5432/${name}`;
+	}
+	if (current.UMAMI_URL) {
+		values.UMAMI_ADMIN_PASSWORD = secrets.umami_admin ?? "";
+		values.UMAMI_APP_SECRET = secrets.umami_app ?? "";
+		values.UMAMI_DATABASE_URL = umamiDatabaseUrl(values.DATABASE_URL ?? current.DATABASE_URL ?? "");
+	}
+	if (options.emailUrl) values.EMAIL_URL = options.emailUrl;
+	else if (!current.EMAIL_URL || current.EMAIL_URL.includes("mailpit")) {
+		values.EMAIL_URL = "smtp+tls://user:password@smtp.example.com:587";
+		todo.push("Set EMAIL_URL to your SMTP server, so password resets and notifications are sent.");
+	}
+	if ((current.S3_ENDPOINT_URL ?? "").includes("s3:8333")) {
+		Object.assign(values, {
+			S3_BUCKET: "",
+			S3_ENDPOINT_URL: "",
+			S3_REGION: "",
+			S3_ACCESS_KEY_ID: "",
+			S3_SECRET_ACCESS_KEY: "",
+			S3_PUBLIC_URL: "",
+			S3_CREATE_BUCKET: "0"
+		});
+		todo.push("Set the S3_* variables to your S3 service, or leave them empty to keep uploads on the server.");
+	}
+	if (!current.ADMIN_EMAIL || current.ADMIN_EMAIL.endsWith("@example.com")) todo.push("Set ADMIN_EMAIL to your address.");
+	if (current.SEED_DEMO_CONTENT === "1") todo.push("Set SEED_DEMO_CONTENT=0 unless the site should start with the demo pages and posts.");
+	return {
+		text: setEnvValues(devEnv, values),
+		adminPassword: values.ADMIN_PASSWORD ?? "",
+		todo
+	};
+}
+export { stackOption as C, checkTools as D, runDoctor as E, parseEnv as O, resolvePreset as S, generateSecret as T, STACK_OPTIONS as _, lockBackend as a, encodePreset as b, scaffold as c, umamiEnv as d, validateProjectName as f, NAMED_PRESETS as g, DEFAULT_STACK as h, LOCAL_S3 as i, setEnvValues as k, timeZones as l, CLI_VERSION as m, validateDomain as n, normalizeDatabaseUrl as o, validateTimeZone as p, FRONTENDS as r, relativeDirectory as s, productionEnv as t, toProjectName as u, applies as v, generateProjectSecrets as w, pendingChoices as x, decodePreset as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@django-stack/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "The production-ready Django, batteries included stack. Create and manage DjangoStack projects: a Django backend, a frontend, Postgres and Docker Compose in one command.",
   "license": "MIT",
   "author": "Leon van der Grient",

package/templates/backend/config/studio.py

@@ -5,9 +5,11 @@ https://djangocontentstudio.org/docs/extensions for the hooks and extensions.
 """
 
 from content_studio.admin import ContentStudioSite
+from content_studio.analytics import AnalyticsExtension, AnalyticsLink, AnalyticsPage
 from content_studio.contrib.huey import HueyAdapter
 from content_studio.dashboard.tasks import TaskDashboard
 from content_studio.extensions import UserMenuLink
+from django_stack.analytics import UmamiProvider
 
 
 class SiteStudio(ContentStudioSite):
@@ -16,5 +18,12 @@ class SiteStudio(ContentStudioSite):
         UserMenuLink(url="/tasks/", label="Tasks", icon="ph-bold ph-queue"),
     ]
 
+    # Page analytics from the bundled Umami when UMAMI_URL is set (see
+    # .env): an Analytics page in the main menu. content/admin.py shows the
+    # numbers of each page and post. See
+    # https://djangocontentstudio.org/docs/analytics.
+    if UmamiProvider.is_configured():
+        extensions += [AnalyticsExtension(provider=UmamiProvider()), AnalyticsPage(), AnalyticsLink()]
+
 
 admin_site = SiteStudio()

package/templates/backend/content/admin.py

@@ -5,6 +5,7 @@ The studios of the content models: how they look in Content Studio at
 
 from content_studio import register
 from content_studio.admin import ModelStudio
+from content_studio.analytics import Analytics
 from content_studio.form import ActivityLog, Field, FormSet
 from django_stack.studio import PreviewButton
 
@@ -15,6 +16,10 @@ PAGE_PREVIEW = PreviewButton(component_id="8d0f6a52-3c51-4a8e-9a2b-6f1f0c8f2a01"
 POST_PREVIEW = PreviewButton(component_id="8d0f6a52-3c51-4a8e-9a2b-6f1f0c8f2a02")
 PAGE_ACTIVITY = ActivityLog(component_id="8d0f6a52-3c51-4a8e-9a2b-6f1f0c8f2a03")
 POST_ACTIVITY = ActivityLog(component_id="8d0f6a52-3c51-4a8e-9a2b-6f1f0c8f2a04")
+# The visitors of the page or post, from the analytics (see config/studio.py).
+# Hidden while analytics are off.
+PAGE_ANALYTICS = Analytics(path_field="path", component_id="8d0f6a52-3c51-4a8e-9a2b-6f1f0c8f2a05")
+POST_ANALYTICS = Analytics(path_field="slug", path_prefix="/blog/", component_id="8d0f6a52-3c51-4a8e-9a2b-6f1f0c8f2a06")
 SEO = FormSet(
     title="Search and sharing",
     description="Leave empty to use the title and the site settings.",
@@ -37,7 +42,7 @@ class PageStudio(ModelStudio):
         FormSet(title="Body", fields=["body"]),
         SEO,
     ]
-    edit_sidebar = ["status", "published_at", PAGE_PREVIEW, "order", PAGE_ACTIVITY]
+    edit_sidebar = ["status", "published_at", PAGE_PREVIEW, "order", PAGE_ANALYTICS, PAGE_ACTIVITY]
 
 
 @register(Post)
@@ -55,7 +60,16 @@ class PostStudio(ModelStudio):
         FormSet(title="Body", fields=["body"]),
         SEO,
     ]
-    edit_sidebar = ["status", "published_at", POST_PREVIEW, "author", "categories", "tags", POST_ACTIVITY]
+    edit_sidebar = [
+        "status",
+        "published_at",
+        POST_PREVIEW,
+        "author",
+        "categories",
+        "tags",
+        POST_ANALYTICS,
+        POST_ACTIVITY,
+    ]
 
 
 @register(Category, Tag)

package/templates/backend/entrypoint.sh

@@ -5,7 +5,8 @@
 # first admin user and, with SEED_DEMO_CONTENT=1, add demo content to an
 # empty site. DJANGO_CHECK_DEPLOY=1 (production): stop when Django's deploy
 # checks find an error. S3_CREATE_BUCKET=1 (the development S3 service):
-# create the media bucket.
+# create the media bucket. UMAMI_URL set (the analytics profile): set up
+# Umami; when that fails the site still starts, without analytics.
 set -eu
 
 python manage.py wait_for_db
@@ -22,6 +23,9 @@ if [ "${DJANGO_MIGRATE:-0}" = "1" ]; then
   if [ "${SEED_DEMO_CONTENT:-0}" = "1" ]; then
     python manage.py seed_content --if-empty
   fi
+  if [ -n "${UMAMI_URL:-}" ]; then
+    python manage.py setup_umami || echo "Umami is not set up, so the admin shows no analytics. See the error above." >&2
+  fi
 fi
 
 exec "$@"

package/templates/backend/pyproject.toml

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

package/templates/base/AGENTS.md

@@ -41,7 +41,8 @@ Run them at the project root. They need Docker; Node is only needed for the `npm
 
 In production (`COMPOSE_PROFILES=prod,db`) the services are `backend-prod`,
 `worker-prod` (which also runs the daily backup), `frontend-prod` and
-`proxy`; their containers are
+`proxy`, with `umami` for page analytics when the `analytics` profile is on;
+their containers are
 read-only, so a change goes through the code and a new image, never an edit
 in a running container.
 

package/templates/base/Caddyfile

@@ -1,7 +1,8 @@
 # {{project_name}}: the reverse proxy of the prod profile.
 #
 # One domain: Django serves /admin, /api and /static; uploads on the server's
-# disk are served from /media; the frontend serves everything else. Caddy
+# disk are served from /media; Umami's tracker from /_a/; the frontend
+# serves everything else. Caddy
 # gets and renews the HTTPS certificate for SITE_URL by itself.
 #
 # Behind a platform's proxy (Coolify, Dokploy), CADDY_ADDRESS=:80 serves
@@ -35,6 +36,18 @@
 		file_server
 	}
 
+	# Page analytics: only Umami's tracker and its page views, never its
+	# interface or API. Without the analytics profile these answer 502.
+	handle_path /_a/* {
+		@tracker path /script.js /api/send
+		handle @tracker {
+			reverse_proxy umami:3000
+		}
+		handle {
+			respond 404
+		}
+	}
+
 	@django path /admin /admin/* /api /api/* /static/*
 	handle @django {
 		reverse_proxy backend:8000

package/templates/base/README.md

@@ -51,6 +51,15 @@ site with drafts shown, for an hour.
 When an editor saves, Django tells the frontend (`REVALIDATE_URL`), which
 empties its page cache, so the change shows on the next visit.
 
+## Analytics
+
+When `COMPOSE_PROFILES` in `.env` has `analytics`, the `umami` service
+counts page views without cookies, and the admin shows them under
+**Analytics**. Umami's own interface is not served: only its tracker and the
+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).
+
 ## Deploy
 
 On a server with Docker and a domain pointing at it:

package/templates/base/compose.yaml

@@ -6,7 +6,8 @@
 #   prod,db   `docker compose up -d` on a server: production images behind
 #             Caddy on ports 80 and 443, with automatic HTTPS and daily backups.
 #   Leave out `db` to use an external Postgres through DATABASE_URL, and add
-#   `s3` in development for a local S3 service (see .env).
+#   `s3` in development for a local S3 service (see .env). `analytics` runs
+#   Umami for page analytics.
 #
 # The frontend only receives the variables it needs: never the full-access
 # API key or the database password.
@@ -31,6 +32,9 @@ x-frontend-env: &frontend-env
   PREVIEW_SECRET: ${PREVIEW_SECRET}
   REVALIDATE_SECRET: ${REVALIDATE_SECRET}
   MEDIA_ORIGINS: ${S3_PUBLIC_URL:-${S3_ENDPOINT_URL:-}}
+  # Page analytics: the tracker loads from /_a/ on the site when set.
+  UMAMI_WEBSITE_ID: ${UMAMI_WEBSITE_ID:-}
+  UMAMI_URL: ${UMAMI_URL:-}
 
 x-backend-depends: &backend-depends
   db:
@@ -41,6 +45,10 @@ x-backend-depends: &backend-depends
   s3:
     condition: service_started
     required: false
+  # The backend sets Umami up on start; it waits for it by itself.
+  umami:
+    condition: service_started
+    required: false
 
 x-backend-health: &backend-health
   test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/readyz', timeout=4)"]
@@ -232,6 +240,36 @@ services:
 
   # Shared -----------------------------------------------------------------
 
+  # Page analytics (the analytics profile). Umami's interface and API stay on
+  # the internal network: Caddy, and the frontend's dev server, pass on only
+  # the tracker and the page views at /_a/, and the admin reads the numbers
+  # with UMAMI_ADMIN_PASSWORD. Its tables are in the umami schema of the
+  # database.
+  umami:
+    profiles: [analytics]
+    image: umamisoftware/umami:3.4
+    <<: *hardened
+    environment:
+      DATABASE_URL: ${UMAMI_DATABASE_URL:-}
+      APP_SECRET: ${UMAMI_APP_SECRET:-}
+      DISABLE_TELEMETRY: "1"
+      DISABLE_UPDATES: "1"
+    depends_on:
+      db:
+        condition: service_healthy
+        required: false
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://localhost:3000/api/heartbeat').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]
+      interval: 5s
+      timeout: 5s
+      start_period: 60s
+      retries: 30
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+    restart: unless-stopped
+
   db:
     profiles: [db]
     image: postgres:17-alpine

package/templates/base/env.example

@@ -8,7 +8,7 @@ PROJECT_NAME={{project_name}}
 #   dev,db   development on this machine
 #   prod,db  production on a server
 # Leave out `db` when DATABASE_URL points to an external Postgres; add `s3`
-# in development for the local S3 service.
+# in development for the local S3 service. `analytics` runs Umami.
 COMPOSE_PROFILES=dev,db
 
 # The public URL of the site. In development the frontend's dev server also
@@ -71,6 +71,20 @@ S3_ACCESS_KEY_ID=
 S3_SECRET_ACCESS_KEY=
 S3_PUBLIC_URL=
 
+# Page analytics: Umami, in the `analytics` profile. It runs on the internal
+# network only: its tracker and the page views pass through /_a/ on the
+# site, and the admin shows the numbers under Analytics. Umami keeps its
+# tables in the `umami` schema of the database (UMAMI_DATABASE_URL is
+# DATABASE_URL with ?schema=umami), so backups include them. The backend
+# replaces Umami's default admin password with UMAMI_ADMIN_PASSWORD and
+# creates the website UMAMI_WEBSITE_ID on start. To turn analytics off,
+# remove `analytics` from COMPOSE_PROFILES and empty UMAMI_URL.
+UMAMI_URL=
+UMAMI_WEBSITE_ID=
+UMAMI_ADMIN_PASSWORD=
+UMAMI_APP_SECRET=
+UMAMI_DATABASE_URL=
+
 # Backups (prod profile): a daily pg_dump at BACKUP_TIME (UTC) and, when
 # uploads are on disk (no S3_BUCKET) and BACKUP_MEDIA=1, an archive of the
 # media volume; the newest BACKUP_KEEP of each kept in the backups volume.

package/templates/frontend-astro/astro.config.mjs

@@ -4,6 +4,8 @@ import { defineConfig } from "astro/config";
 
 // The Django backend: the frontend container reaches it on the Compose network.
 const backend = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:8000";
+// Umami, for page analytics: only its tracker and page views, under /_a/.
+const umami = process.env.UMAMI_URL || "http://umami:3000";
 
 export default defineConfig({
   site: process.env.SITE_URL ?? "http://localhost:3000",
@@ -17,6 +19,8 @@ export default defineConfig({
   security: {
     csp: {
       directives: ["default-src 'self'", "base-uri 'self'", "form-action 'self'", "object-src 'none'"],
+      // Scripts from this site, such as the analytics tracker at /_a/script.js.
+      scriptDirective: { resources: ["'self'"] },
       // Inline style attributes, such as the focal point of an image.
       styleDirective: { resources: ["'self'", { resource: "'unsafe-inline'", kind: "attribute" }] },
     },
@@ -27,12 +31,15 @@ export default defineConfig({
       allowedHosts: ["frontend"],
       // In development, serve Django's paths from the same origin as the site,
       // like the reverse proxy does in production.
-      proxy: Object.fromEntries(
-        ["/admin", "/api", "/media", "/static"].map((path) => [
-          path,
-          { target: backend, changeOrigin: false },
-        ]),
-      ),
+      proxy: {
+        ...Object.fromEntries(
+          ["/admin", "/api", "/media", "/static"].map((path) => [
+            path,
+            { target: backend, changeOrigin: false },
+          ]),
+        ),
+        "^/_a/(script\\.js|api/send)$": { target: umami, rewrite: (path) => path.slice("/_a".length) },
+      },
     },
   },
 });

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.5.0",
+    "@django-stack/utils": "^0.6.0",
     "astro": "^7.4.5"
   },
   "devDependencies": {

package/templates/frontend-astro/src/layouts/Base.astro

@@ -20,6 +20,8 @@ const [settings, mainMenu, footerMenu] = await Promise.all([
 ]);
 const preview = Astro.cookies.has(PREVIEW_COOKIE);
 const path = Astro.url.pathname;
+// Page analytics: Umami's tracker, served from this site at /_a/.
+const analytics = process.env.UMAMI_WEBSITE_ID;
 ---
 
 <!doctype html>
@@ -30,6 +32,7 @@ const path = Astro.url.pathname;
     <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
     <link rel="alternate" type="application/rss+xml" title={settings?.site_name ?? "RSS"} href="/rss.xml" />
     <Seo page={page} settings={settings} type={type} />
+    {analytics && <script is:inline defer src="/_a/script.js" data-website-id={analytics} />}
   </head>
   <body>
     {

package/templates/frontend-next/package.json

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

package/templates/frontend-next/src/app/layout.tsx

@@ -2,6 +2,7 @@ import "./globals.css";
 import { Image, RichText } from "@django-stack/react";
 import { linkHref } from "@django-stack/utils";
 import type { Metadata } from "next";
+import Script from "next/script";
 import { NavLink } from "@/components/NavLink";
 import { getContent, previewToken, SITE_URL } from "@/lib/api";
 
@@ -64,6 +65,14 @@ export default async function RootLayout({ children }: { children: React.ReactNo
             </nav>
           </div>
         </footer>
+        {/* Page analytics: Umami's tracker, served from this site at /_a/. */}
+        {process.env.UMAMI_WEBSITE_ID ? (
+          <Script
+            src="/_a/script.js"
+            data-website-id={process.env.UMAMI_WEBSITE_ID}
+            strategy="afterInteractive"
+          />
+        ) : null}
       </body>
     </html>
   );

package/templates/frontend-next/src/proxy.ts

@@ -7,6 +7,9 @@ const dev = process.env.NODE_ENV === "development";
 // development, this proxy does, so the site and the admin share an origin.
 const BACKEND_PATHS = /^\/(admin|api|media|static)(\/|$)/;
 const backend = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:8000";
+// Umami's tracker and page views, for page analytics; Caddy passes them on in production.
+const TRACKER_PATHS = /^\/_a\/(script\.js|api\/send)$/;
+const umami = process.env.UMAMI_URL || "http://umami:3000";
 const media = mediaOrigins();
 
 export function proxy(request: NextRequest) {
@@ -14,6 +17,9 @@ export function proxy(request: NextRequest) {
   if (dev && BACKEND_PATHS.test(pathname)) {
     return NextResponse.rewrite(new URL(pathname + search, backend));
   }
+  if (dev && TRACKER_PATHS.test(pathname)) {
+    return NextResponse.rewrite(new URL(pathname.slice("/_a".length) + search, umami));
+  }
 
   // A fresh nonce for every page: Next adds it to the scripts it renders.
   const nonce = Buffer.from(crypto.randomUUID()).toString("base64");

package/templates/frontend-nuxt/nuxt.config.ts

@@ -1,5 +1,7 @@
 // The Django backend: the frontend container reaches it on the Compose network.
 const backend = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:8000";
+// Umami, for page analytics: only its tracker and page views, under /_a/.
+const umami = process.env.UMAMI_URL || "http://umami:3000";
 
 export default defineNuxtConfig({
   compatibilityDate: "2026-11-01",
@@ -26,12 +28,16 @@ export default defineNuxtConfig({
   // In development, serve Django's paths from the same origin as the site,
   // like the reverse proxy does in production.
   $development: {
-    routeRules: Object.fromEntries(
-      ["/admin", "/api", "/media", "/static"].map((path) => [
-        `${path}/**`,
-        { proxy: `${backend}${path}/**` },
-      ]),
-    ),
+    routeRules: {
+      ...Object.fromEntries(
+        ["/admin", "/api", "/media", "/static"].map((path) => [
+          `${path}/**`,
+          { proxy: `${backend}${path}/**` },
+        ]),
+      ),
+      "/_a/script.js": { proxy: `${umami}/script.js` },
+      "/_a/api/send": { proxy: `${umami}/api/send` },
+    },
   },
   // Security headers, with a Content-Security-Policy on every page in
   // production: scripts and styles only from this site, with a nonce for

package/templates/frontend-nuxt/package.json

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