@django-stack/cli 0.11.0 → 0.12.1

package/README.md

@@ -1,6 +1,6 @@
 # @django-stack/cli
 
-The production-ready Django, batteries included stack. Create and manage DjangoStack projects: a Django backend, a frontend, Postgres and Docker Compose in one command.
+The production-ready batteries included Django stack. Create and manage DjangoStack projects: a Django backend, a frontend, Postgres and Docker Compose in one command.
 
 ```bash
 npx @django-stack/cli init my-site
@@ -27,7 +27,7 @@ Run `dstack help <command>` for the options of a command. Each command
 checks for a newer version once a day; turn that off with
 `--no-update-check` or `DJANGO_STACK_NO_UPDATE_CHECK=1`.
 
-Read the [documentation](https://github.com/dwarsbit/django-stack/tree/main/website/docs) of
+Read the [documentation](https://djangostack.org/) of
 [DjangoStack](https://github.com/dwarsbit/django-stack).
 
 ## License

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as envPorts, A as compose, B as NAMED_PRESETS, C as PACKAGE_NAME, D as RUN_DOMAIN, E as CAPTCHA_APP, F as projectUrls, H as PROMPT_ORDER, I as readLocalRun, J as resolvePreset, K as encodePreset, L as readProject, M as findProjectDirectory, N as parseProfiles, O as RUN_ENV, P as projectStack, Q as describeMove, R as runningServices, S as CLI_VERSION, T as generateSecret, U as STACK_OPTIONS, V as NODE_FRONTENDS, W as applies, X as DEV_PORTS, Y as stackOption, Z as chooseFreePorts, _ as umamiEnv, a as LOCAL_S3, at as isDockerDown, b as validateProjectName, c as localS3, ct as setEnvValues, et as portValues, f as relativeDirectory, g as toProjectName, h as timeZones, it as dockerRunning, j as composeOutput, k as activeProject, l as lockBackend, m as setNotificationsApp, n as productionEnv$1, nt as checkTools, o as cacheEnv, ot as parseEnv, p as scaffold, q as pendingChoices, r as validateDomain, rt as dockerNotRunning, s as frontendPackageManager, st as quoteEnvValue, t as missingS3, tt as runDoctor, u as lockFrontend, v as updateFrontendLock, w as generateProjectSecrets, x as validateTimeZone, y as usesValkey, z as DEFAULT_STACK } from "./production-WThC1aS2.js";
+import { $ as describeMove, A as activeProject, B as DEFAULT_STACK, C as CLI_VERSION, D as CAPTCHA_APP, E as generateSecret, F as projectStack, G as applies, H as NODE_FRONTENDS, I as projectUrls, J as pendingChoices, L as readLocalRun, M as composeOutput, N as findProjectDirectory, O as RUN_DOMAIN, P as parseProfiles, Q as chooseFreePorts, R as readProject, S as validateTimeZone, T as generateProjectSecrets, U as PROMPT_ORDER, V as NAMED_PRESETS, W as STACK_OPTIONS, X as stackOption, Y as resolvePreset, Z as DEV_PORTS, _ as toProjectName, at as dockerRunning, b as usesValkey, c as frontendPackageManager, ct as removeLeftovers, d as lockFrontend, dt as setEnvValues, et as envPorts, f as normalizeDatabaseUrl, g as timeZones, h as setNotificationsApp, i as validateDomain, it as dockerNotRunning, j as compose, k as RUN_ENV, l as localS3, lt as parseEnv, m as scaffold, n as postgresUrl, nt as runDoctor, o as LOCAL_S3, ot as isDockerDown, p as relativeDirectory, q as encodePreset, r as productionEnv$1, rt as checkTools, s as cacheEnv, st as leftoverVolumes, t as missingS3, tt as portValues, u as lockBackend, ut as quoteEnvValue, v as umamiEnv, w as PACKAGE_NAME, x as validateProjectName, y as updateFrontendLock, z as runningServices } from "./production-lgZRSpyw.js";
 import { createRequire } from "node:module";
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { basename, delimiter, dirname, join, posix, relative, resolve, sep } from "node:path";
@@ -3929,11 +3929,9 @@ function choices(key, stack = {}) {
 }
 /**
 * The stack from, in order of precedence, the flags, the preset, the prompts
-* and the defaults. `askDatabase` asks for the Postgres version together with
-* the external database choice; it returns the version, and the URL for
-* production when there is one.
+* and the defaults.
 */
-async function chooseStack(options, interactive, askDatabase) {
+async function chooseStack(options, interactive) {
 	let preset;
 	if (options.preset) try {
 		preset = resolvePreset(options.preset);
@@ -3941,18 +3939,13 @@ async function chooseStack(options, interactive, askDatabase) {
 		fail(error.message);
 	}
 	const stack = { ...DEFAULT_STACK };
-	let databaseUrl;
 	for (const key of PROMPT_ORDER) {
 		const option = stackOption(key);
 		if (options.fromCli(key)) stack[key] = options[key];
 		else if (key === "storage" && options.fromCli("localS3") && options.localS3) stack[key] = "s3";
 		else if (preset) stack[key] = preset[key];
 		else if (!interactive || !applies(key, stack)) continue;
-		else if (key === "postgres" && askDatabase && !options.databaseUrl) {
-			const answer = await askDatabase(stack[key]);
-			if (answer.databaseUrl) databaseUrl = answer.databaseUrl;
-			stack[key] = answer.postgres;
-		} else {
+		else {
 			const initialValue = key === "storage" && stack.media === "s3" ? "s3" : stack[key];
 			stack[key] = unwrap(await p.select({
 				message: option.message,
@@ -3961,10 +3954,7 @@ async function chooseStack(options, interactive, askDatabase) {
 			}));
 		}
 	}
-	return {
-		stack,
-		databaseUrl
-	};
+	return stack;
 }
 function systemTimeZone() {
 	try {
@@ -3988,6 +3978,24 @@ function checkComputer(checks = checkTools()) {
 	});
 	return !checks.some((check) => !check.ok && !check.warning);
 }
+/**
+* Docker keeps the volumes of a deleted project. A new project with the same
+* name would start on the old database, whose password is not the new one in
+* .env: "password authentication failed for user app". Offers to remove them.
+*/
+async function handleLeftovers(name, interactive) {
+	const volumes = leftoverVolumes(name);
+	if (!volumes.length) return;
+	const removeCommand = command("docker compose down --volumes");
+	p.log.warn(`Docker still has the data of an earlier project named ${pc.bold(name)} (${volumes.join(", ")}). The new project gets a new database password, so it cannot start on that database.`);
+	if (interactive && unwrap(await p.confirm({
+		message: `Remove the data of the earlier ${name}? Its database and uploads are deleted for good.`,
+		initialValue: false
+	}))) {
+		if (removeLeftovers(name, volumes)) p.log.success(`Removed the data of the earlier ${name}.`);
+		else fail("Could not remove it. Stop what uses it, or choose another --name.");
+	} else p.log.warn(`Run ${removeCommand} in the new project before you start it, or choose another --name.`);
+}
 async function init(directoryArgument, options) {
 	const interactive = isInteractive(options.yes);
 	intro("Create a project");
@@ -4009,36 +4017,8 @@ async function init(directoryArgument, options) {
 			validate: (value) => validateProjectName(value ?? "")
 		}));
 	}
-	const chosen = await chooseStack(options, interactive, async (initial) => {
-		const choice = unwrap(await p.select({
-			message: "Database",
-			initialValue: initial,
-			options: [...choices("postgres").map((value) => ({
-				...value,
-				label: `Bundled Postgres, ${value.label.toLowerCase()}`
-			})), {
-				value: "external",
-				label: "External Postgres in production",
-				hint: "a URL to your server; development runs the bundled one"
-			}]
-		}));
-		if (choice !== "external") return { postgres: choice };
-		const databaseUrl = unwrap(await p.text({
-			message: "Postgres URL for production",
-			placeholder: "postgres://user:password@host:5432/name",
-			validate: (value) => value?.startsWith("postgres") ? void 0 : "Enter a postgres:// URL."
-		}));
-		return {
-			postgres: unwrap(await p.select({
-				message: "Its Postgres version",
-				initialValue: initial,
-				options: choices("postgres")
-			})),
-			databaseUrl
-		};
-	});
-	const stack = chosen.stack;
-	const databaseUrl = options.databaseUrl ?? chosen.databaseUrl;
+	if (dockerReady) await handleLeftovers(name, interactive);
+	const stack = await chooseStack(options, interactive);
 	if (!applies("analytics", stack) && stack.analytics !== "off") {
 		if (options.fromCli("analytics")) fail("--analytics umami needs a frontend: a headless project has no pages to count.");
 		stack.analytics = "off";
@@ -4077,7 +4057,7 @@ async function init(directoryArgument, options) {
 			name,
 			frontend: stack.frontend,
 			demoContent,
-			databaseUrl,
+			databaseUrl: options.databaseUrl,
 			postgres: stack.postgres,
 			localS3: stack.storage === "s3",
 			analytics: stack.analytics === "umami",
@@ -4179,7 +4159,7 @@ async function preset(code, options) {
 		p.outro(`Use it with ${command(`${selfCommand()} init --preset ${code in NAMED_PRESETS ? code : encodePreset(stack)}`)}`);
 		return;
 	}
-	const { stack } = await chooseStack(options, isInteractive(options.yes));
+	const stack = await chooseStack(options, isInteractive(options.yes));
 	const encoded = encodePreset(stack);
 	p.outro(`Create this stack with ${command(`${selfCommand()} init --preset ${encoded}`)}`);
 }
@@ -4198,7 +4178,7 @@ function validateUrl(value) {
 	if (!value) return void 0;
 	return /^https?:\/\/[^\s/]+/.test(value) ? void 0 : "Enter a URL that starts with https://.";
 }
-const required = (label) => (value) => value.trim() ? void 0 : `Enter the ${label}.`;
+const required$1 = (label) => (value) => value.trim() ? void 0 : `Enter the ${label}.`;
 /**
 * An SMTP URL for EMAIL_URL: smtps:// on port 465, smtp:// on 25, otherwise
 * smtp+tls:// (STARTTLS), with the user name and password URL-encoded.
@@ -4294,7 +4274,7 @@ const SETTING_GROUPS = [
 				name: "S3_BUCKET",
 				message: "S3 bucket",
 				placeholder: "example-media",
-				validate: required("bucket")
+				validate: required$1("bucket")
 			},
 			{
 				name: "S3_ENDPOINT_URL",
@@ -4307,18 +4287,18 @@ const SETTING_GROUPS = [
 				name: "S3_REGION",
 				message: "S3 region",
 				placeholder: "eu-central-1",
-				validate: required("region")
+				validate: required$1("region")
 			},
 			{
 				name: "S3_ACCESS_KEY_ID",
 				message: "S3 access key ID",
-				validate: required("access key ID")
+				validate: required$1("access key ID")
 			},
 			{
 				name: "S3_SECRET_ACCESS_KEY",
 				message: "S3 secret access key",
 				secret: true,
-				validate: required("secret access key")
+				validate: required$1("secret access key")
 			},
 			{
 				name: "S3_PUBLIC_URL",
@@ -4473,6 +4453,86 @@ async function settings(options) {
 	else p.outro(pc.green("Done"));
 }
 // src/commands/production.ts
+const required = (label) => (value) => value?.trim() ? void 0 : `Enter the ${label}.`;
+/**
+* Asks for the server's database: the bundled Postgres, or your own as a URL
+* or as separate values. Returns the URL of your own, or undefined.
+*/
+async function askDatabase() {
+	if (unwrap(await p.select({
+		message: "Database on the server",
+		initialValue: "bundled",
+		options: [{
+			value: "bundled",
+			label: "Bundled Postgres",
+			hint: "a container next to the backend"
+		}, {
+			value: "external",
+			label: "Your own Postgres",
+			hint: "a managed database or another server"
+		}]
+	})) === "bundled") return void 0;
+	if (unwrap(await p.select({
+		message: "How do you want to enter it?",
+		initialValue: "parts",
+		options: [{
+			value: "parts",
+			label: "Host, port, name, user and password",
+			hint: "any password works"
+		}, {
+			value: "url",
+			label: "A postgres:// URL",
+			hint: "special characters in the password URL-encoded"
+		}]
+	})) === "url") {
+		const value = unwrap(await p.text({
+			message: "Postgres URL",
+			placeholder: "postgres://user:password@db.example.com:5432/app",
+			validate: (value) => {
+				try {
+					normalizeDatabaseUrl((value ?? "").trim());
+					return;
+				} catch (error) {
+					return error.message;
+				}
+			}
+		}));
+		return normalizeDatabaseUrl(value.trim());
+	}
+	const host = unwrap(await p.text({
+		message: "Host",
+		placeholder: "db.example.com",
+		validate: required("host")
+	}));
+	const port = unwrap(await p.text({
+		message: "Port",
+		placeholder: "5432",
+		defaultValue: "5432",
+		validate: (value) => {
+			if (!value) return void 0;
+			const port = Number(value);
+			return Number.isInteger(port) && port > 0 && port < 65536 ? void 0 : "Enter a port, such as 5432.";
+		}
+	}));
+	const name = unwrap(await p.text({
+		message: "Database name",
+		placeholder: "app",
+		validate: required("name")
+	}));
+	const user = unwrap(await p.text({
+		message: "User",
+		placeholder: "app",
+		validate: required("user")
+	}));
+	const password = unwrap(await p.password({ message: "Password" }));
+	return postgresUrl({
+		host: host.trim(),
+		port: port.trim(),
+		name: name.trim(),
+		user: user.trim(),
+		password
+	});
+}
 async function production(directoryArgument, options) {
 	const interactive = isInteractive(options.yes);
 	const directory = resolve(directoryArgument ?? ".");
@@ -4490,12 +4550,21 @@ async function production(directoryArgument, options) {
 			validate: (v) => validateDomain(v ?? "")
 		}));
 	}
+	const devEnv = readFileSync(envPath, "utf8");
+	let databaseUrl = options.databaseUrl;
+	if (databaseUrl) try {
+		normalizeDatabaseUrl(databaseUrl);
+	} catch (error) {
+		fail(error.message);
+	}
+	else if (interactive && !parseEnv(devEnv).PRODUCTION_DATABASE_URL) databaseUrl = await askDatabase();
 	const context = projectContext(directory);
 	let result;
 	try {
-		result = productionEnv$1(readFileSync(envPath, "utf8"), {
+		result = productionEnv$1(devEnv, {
 			domain,
 			emailUrl: options.emailUrl,
+			databaseUrl,
 			media: context.media
 		});
 	} catch (error) {
@@ -5016,6 +5085,12 @@ function nodeModulesVolume(project) {
 		return;
 	}
 }
+/** The backend packages `dstack update` upgrades without `--all`. */
+const BACKEND_PACKAGES = [
+	"django-stack",
+	"django-headless",
+	"django-content-studio"
+];
 /** `dstack update`: newer images, newer DjangoStack packages, and a restart of what was running. */
 async function update(options) {
 	const project = open(options);
@@ -5024,16 +5099,12 @@ async function update(options) {
 	const running = targets.filter((target) => runningServices(target).length > 0);
 	const lock = join(project.directory, "backend", "uv.lock");
 	if (existsSync(lock) && has("uv")) {
-		const args = options.all ? ["lock", "--upgrade"] : [
-			"lock",
-			"--upgrade-package",
-			"django-stack"
-		];
+		const args = options.all ? ["lock", "--upgrade"] : ["lock", ...BACKEND_PACKAGES.flatMap((name) => ["--upgrade-package", name])];
 		if (spawnSync("uv", args, {
 			cwd: join(project.directory, "backend"),
 			stdio: "inherit"
 		}).status !== 0) fail("uv could not update backend/uv.lock.");
-		p.log.success(options.all ? "Updated backend/uv.lock" : "Updated django-stack in backend/uv.lock");
+		p.log.success(options.all ? "Updated backend/uv.lock" : `Updated ${BACKEND_PACKAGES.join(", ")} in backend/uv.lock`);
 	} else if (existsSync(lock)) p.log.warn("uv is not installed, so backend/uv.lock stays as it is: https://docs.astral.sh/uv/");
 	if (frontendPackageManager(project.directory)) {
 		const lockfile = updateFrontendLock(project.directory, options.all);
@@ -5379,7 +5450,7 @@ function createProgram() {
 		fromCli: (option) => cmd.getOptionValueSource(option) === "cli"
 	}));
 	for (const flag of stackFlags()) presetCommand.addOption(flag);
-	program.command("production").description("Write .env.production for a server").argument("[directory]", "The project directory", ".").option("--domain <domain>", "The domain of the site, such as example.com").option("--email-url <url>", "The SMTP server, such as smtp+tls://user:pass@host:587").option("--force", "Overwrite an existing .env.production").option("-y, --yes", "Don't ask; fail when --domain is missing").action(production);
+	program.command("production").description("Write .env.production for a server").argument("[directory]", "The project directory", ".").option("--domain <domain>", "The domain of the site, such as example.com").option("--email-url <url>", "The SMTP server, such as smtp+tls://user:pass@host:587").option("--database-url <url>", "Your own Postgres for the server instead of the bundled one").option("--force", "Overwrite an existing .env.production").option("-y, --yes", "Don't ask; fail when --domain is missing").action(production);
 	program.command("settings").description("Ask for the missing production settings and credentials, and save them").addOption(dirOption()).option("--file <file>", "The file to change (default: .env.production, or .env on a server)").option("--set <NAME=value>", "Set a value without asking, such as --set ADMIN_EMAIL=you@example.com", (value, previous = []) => [...previous, value]).option("--all", "Ask for every setting, also the ones that are set").option("-y, --yes", "Don't ask; fail when a setting is still missing").action(settings);
 	program.command("doctor").description("Check a project and its services").argument("[directory]", "The project directory", ".").action(doctor);
 	program.command("self-update").description(`Update ${BIN} to the latest version on npm`).action(selfUpdate);

package/dist/index.d.ts

@@ -22,6 +22,8 @@ interface ProductionOptions {
   media?: string;
   /** Keep the bundled database even with PRODUCTION_DATABASE_URL: the local run on this machine. */
   bundledDatabase?: boolean;
+  /** An external Postgres for the server; it takes the place of PRODUCTION_DATABASE_URL. */
+  databaseUrl?: string;
 }
 interface ProductionEnv {
   text: string;

package/dist/index.js

@@ -1 +1 @@
-export { z as DEFAULT_STACK, i as FRONTENDS, B as NAMED_PRESETS, U as STACK_OPTIONS, S as VERSION, o as cacheEnv, G as decodePreset, K as encodePreset, w as generateProjectSecrets, T as generateSecret, d as normalizeDatabaseUrl, ot as parseEnv, q as pendingChoices, n as productionEnv, J as resolvePreset, tt as runDoctor, p as scaffold, ct as setEnvValues, m as setNotificationsApp, g as toProjectName, y as usesValkey, r as validateDomain, b as validateProjectName } from "./production-WThC1aS2.js";
+export { B as DEFAULT_STACK, a as FRONTENDS, V as NAMED_PRESETS, W as STACK_OPTIONS, C as VERSION, s as cacheEnv, K as decodePreset, q as encodePreset, T as generateProjectSecrets, E as generateSecret, f as normalizeDatabaseUrl, lt as parseEnv, J as pendingChoices, r as productionEnv, Y as resolvePreset, nt as runDoctor, m as scaffold, dt as setEnvValues, h as setNotificationsApp, _ as toProjectName, b as usesValkey, i as validateDomain, x as validateProjectName } from "./production-lgZRSpyw.js";

package/dist/{production-WThC1aS2.js → production-lgZRSpyw.js}

@@ -117,6 +117,40 @@ function dockerRunning(runCommand = run) {
 		"{{.Server.Version}}"
 	]));
 }
+/**
+* The Docker volumes of an earlier Compose project with this name, such as
+* `<name>_pgdata`. A new project with the same name would reuse them, and
+* Postgres keeps the password of the data it was created with.
+*/
+function leftoverVolumes(name, runCommand = run) {
+	return (runCommand("docker", [
+		"volume",
+		"ls",
+		"--quiet",
+		"--filter",
+		`label=com.docker.compose.project=${name}`
+	]) ?? "").split("\n").filter(Boolean);
+}
+/** Removes the containers and volumes of the Compose project with this name. Returns whether it worked. */
+function removeLeftovers(name, volumes, runCommand = run) {
+	const containers = (runCommand("docker", [
+		"ps",
+		"--all",
+		"--quiet",
+		"--filter",
+		`label=com.docker.compose.project=${name}`
+	]) ?? "").split("\n").filter(Boolean);
+	if (containers.length && runCommand("docker", [
+		"rm",
+		"--force",
+		...containers
+	]) === void 0) return false;
+	return runCommand("docker", [
+		"volume",
+		"rm",
+		...volumes
+	]) !== void 0;
+}
 /** Docker and Docker Compose, which run the project. */
 function checkDocker({ run: runCommand = run, platform = process.platform } = {}) {
 	const client = parseVersion(runCommand("docker", ["--version"]));
@@ -1655,6 +1689,16 @@ function relativeDirectory(directory) {
 	return path.startsWith("..") ? directory : path;
 }
 // src/production.ts
+/**
+* A Postgres URL from its parts, with the user name, password and database
+* name URL-encoded, so a password with `@`, `:`, `/` or `#` still works.
+* Hosts other than this machine get `sslmode=require`.
+*/
+function postgresUrl(parts) {
+	const host = parts.host.includes(":") && !parts.host.startsWith("[") ? `[${parts.host}]` : parts.host;
+	const password = parts.password ? `:${encodeURIComponent(parts.password)}` : "";
+	return normalizeDatabaseUrl(`postgres://${encodeURIComponent(parts.user)}${password}@${host}:${parts.port || "5432"}/${encodeURIComponent(parts.name)}`);
+}
 /** The S3 settings that uploads to S3 need and that are empty. */
 function missingS3(env) {
 	return [
@@ -1694,7 +1738,7 @@ function productionEnv(devEnv, options) {
 		ADMIN_PASSWORD: secrets.admin ?? "",
 		DEFAULT_FROM_EMAIL: `${current.PROJECT_NAME ?? "site"} <noreply@${options.domain.toLowerCase()}>`
 	};
-	const external = options.bundledDatabase ? "" : current.PRODUCTION_DATABASE_URL ?? "";
+	const external = options.bundledDatabase ? "" : options.databaseUrl ? normalizeDatabaseUrl(options.databaseUrl) : current.PRODUCTION_DATABASE_URL ?? "";
 	if (external) {
 		values.DATABASE_URL = external;
 		values.POSTGRES_PASSWORD = "";
@@ -1736,4 +1780,4 @@ function productionEnv(devEnv, options) {
 		todo
 	};
 }
-export { envPorts as $, compose as A, NAMED_PRESETS as B, PACKAGE_NAME as C, RUN_DOMAIN as D, CAPTCHA_APP as E, projectUrls as F, decodePreset as G, PROMPT_ORDER as H, readLocalRun as I, resolvePreset as J, encodePreset as K, readProject as L, findProjectDirectory as M, parseProfiles as N, RUN_ENV as O, projectStack as P, describeMove as Q, runningServices as R, CLI_VERSION as S, generateSecret as T, STACK_OPTIONS as U, NODE_FRONTENDS as V, applies as W, DEV_PORTS as X, stackOption as Y, chooseFreePorts as Z, umamiEnv as _, LOCAL_S3 as a, isDockerDown as at, validateProjectName as b, localS3 as c, setEnvValues as ct, normalizeDatabaseUrl as d, portValues as et, relativeDirectory as f, toProjectName as g, timeZones as h, FRONTENDS as i, dockerRunning as it, composeOutput as j, activeProject as k, lockBackend as l, setNotificationsApp as m, productionEnv as n, checkTools as nt, cacheEnv as o, parseEnv as ot, scaffold as p, pendingChoices as q, validateDomain as r, dockerNotRunning as rt, frontendPackageManager as s, quoteEnvValue as st, missingS3 as t, runDoctor as tt, lockFrontend as u, updateFrontendLock as v, generateProjectSecrets as w, validateTimeZone as x, usesValkey as y, DEFAULT_STACK as z };
+export { describeMove as $, activeProject as A, DEFAULT_STACK as B, CLI_VERSION as C, CAPTCHA_APP as D, generateSecret as E, projectStack as F, applies as G, NODE_FRONTENDS as H, projectUrls as I, pendingChoices as J, decodePreset as K, readLocalRun as L, composeOutput as M, findProjectDirectory as N, RUN_DOMAIN as O, parseProfiles as P, chooseFreePorts as Q, readProject as R, validateTimeZone as S, generateProjectSecrets as T, PROMPT_ORDER as U, NAMED_PRESETS as V, STACK_OPTIONS as W, stackOption as X, resolvePreset as Y, DEV_PORTS as Z, toProjectName as _, FRONTENDS as a, dockerRunning as at, usesValkey as b, frontendPackageManager as c, removeLeftovers as ct, lockFrontend as d, setEnvValues as dt, envPorts as et, normalizeDatabaseUrl as f, timeZones as g, setNotificationsApp as h, validateDomain as i, dockerNotRunning as it, compose as j, RUN_ENV as k, localS3 as l, parseEnv as lt, scaffold as m, postgresUrl as n, runDoctor as nt, LOCAL_S3 as o, isDockerDown as ot, relativeDirectory as p, encodePreset as q, productionEnv as r, checkTools as rt, cacheEnv as s, leftoverVolumes as st, missingS3 as t, portValues as tt, lockBackend as u, quoteEnvValue as ut, umamiEnv as v, PACKAGE_NAME as w, validateProjectName as x, updateFrontendLock as y, runningServices as z };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@django-stack/cli",
-  "version": "0.11.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.",
+  "version": "0.12.1",
+  "description": "The production-ready batteries included Django 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",
-  "homepage": "https://github.com/dwarsbit/django-stack/tree/main/packages/cli#readme",
+  "homepage": "https://djangostack.org/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dwarsbit/django-stack.git",

package/templates/backend/config/studio.py

@@ -5,17 +5,30 @@ 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.analytics import (
+    AnalyticsExtension,
+    AnalyticsLink,
+    AnalyticsPage,
+    AnalyticsStatisticWidget,
+    AnalyticsTopPagesWidget,
+)
 from content_studio.contrib.huey import HueyAdapter
-from content_studio.dashboard.tasks import TaskDashboard
+from content_studio.dashboard import Dashboard
+from content_studio.dashboard.activity_log import ActivityLogWidget
+from content_studio.dashboard.tasks import TaskDashboard, TaskStatisticWidget
 from content_studio.extensions import UserMenuLink
 from django_stack.analytics import UmamiProvider
 from django_stack.studio import SystemLink, SystemPage
 
+from content.dashboard import PublishedCountWidget, RecentSubmissionsWidget, SubmissionCountWidget
+from content.models import Page, Post
+
+TASKS = HueyAdapter()
+
 
 class SiteStudio(ContentStudioSite):
     extensions = [
-        TaskDashboard(adapter=HueyAdapter()),
+        TaskDashboard(adapter=TASKS),
         UserMenuLink(url="/tasks/", label="Tasks", icon="ph-bold ph-queue"),
         # Superusers only: the health checks and the latest error reports.
         SystemPage(),
@@ -29,5 +42,24 @@ class SiteStudio(ContentStudioSite):
     if UmamiProvider.is_configured():
         extensions += [AnalyticsExtension(provider=UmamiProvider()), AnalyticsPage(), AnalyticsLink()]
 
+    # The dashboard at /admin/: what the site has, what came in, what
+    # changed and how the worker is doing. The counters and the form
+    # submissions are in content/dashboard.py; change or remove them there.
+    dashboard = Dashboard(
+        widgets=[
+            PublishedCountWidget(Page, "Published pages", icon="ph-bold ph-file-text"),
+            PublishedCountWidget(Post, "Published posts", icon="ph-bold ph-article"),
+            SubmissionCountWidget(),
+            # Visitors and the most visited pages, with analytics on.
+            *([AnalyticsStatisticWidget("visitors", "30d")] if UmamiProvider.is_configured() else []),
+            RecentSubmissionsWidget(),
+            ActivityLogWidget(),
+            *([AnalyticsTopPagesWidget("30d")] if UmamiProvider.is_configured() else []),
+            # The task counts; the tasks themselves are on the Tasks page.
+            TaskStatisticWidget(TASKS, "queued"),
+            TaskStatisticWidget(TASKS, "failed"),
+        ]
+    )
+
 
 admin_site = SiteStudio()

package/templates/backend/content/admin.py

@@ -124,7 +124,15 @@ class RedirectStudio(ModelStudio):
 
 @register(FormSubmission)
 class FormSubmissionStudio(ModelStudio):
+    """Submissions come from the site's form: editors read and delete them, never create or edit."""
+
     icon = "ph-bold ph-envelope"
     table_display = ["name", "email", "created_at"]
     search_fields = ["name", "email", "message"]
     ordering = ["-created_at"]
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False

package/templates/backend/content/dashboard.py

@@ -0,0 +1,112 @@
+"""
+The widgets of the dashboard at /admin/: config/studio.py lists them. See
+https://djangocontentstudio.org/docs/dashboard for the widget types.
+"""
+
+from datetime import timedelta
+
+from content_studio.dashboard.content_list import ContentListWidget
+from content_studio.dashboard.statistic import StatisticWidget
+from content_studio.settings import cs_settings
+from django.db.models import Count
+from django.db.models.functions import TruncDate
+from django.utils import timezone
+from django.utils.text import Truncator
+from rest_framework.exceptions import PermissionDenied
+
+from .models import FormSubmission
+
+
+def check_view_permission(request, model):
+    """Widgets show only what the editor may view in the model's own list."""
+    studio = cs_settings.ADMIN_SITE._registry.get(model)
+    if studio is None or not studio.has_view_permission(request):
+        raise PermissionDenied()
+
+
+class PublishedCountWidget(StatisticWidget):
+    """The number of published objects of a model, with its drafts in the footnote."""
+
+    name = "PublishedCount"
+    refresh_interval = 300
+
+    def __init__(self, model, title: str, icon: str = "", widget_id=None):
+        self.model = model
+        self.title = title
+        self.icon = icon
+        super().__init__(widget_id)
+
+    def get_id_parts(self):
+        return (self.name, self.model._meta.label)
+
+    def get_data(self, request):
+        check_view_permission(request, self.model)
+        published = self.model.objects.published().count()
+        drafts = self.model.objects.filter(status=self.model.Status.DRAFT).count()
+        return {
+            "title": self.title,
+            "value": published,
+            "number_format": "full",
+            "icon": self.icon,
+            "footnote": f"{drafts} draft{'' if drafts == 1 else 's'}",
+        }
+
+
+class SubmissionCountWidget(StatisticWidget):
+    """The contact form submissions of the last 30 days, with one bar a day."""
+
+    name = "SubmissionCount"
+    refresh_interval = 300
+    days = 30
+
+    def get_data(self, request):
+        check_view_permission(request, FormSubmission)
+        today = timezone.localdate()
+        first = today - timedelta(days=self.days - 1)
+        per_day = dict(
+            FormSubmission.objects.filter(created_at__date__gte=first)
+            .annotate(day=TruncDate("created_at"))
+            .values("day")
+            .annotate(count=Count("pk"))
+            .values_list("day", "count")
+        )
+        series = [per_day.get(first + timedelta(days=offset), 0) for offset in range(self.days)]
+        return {
+            "title": "Form submissions",
+            "value": sum(series),
+            "number_format": "full",
+            "icon": "ph-bold ph-envelope-simple",
+            "footnote": f"Last {self.days} days",
+            "series": series,
+        }
+
+
+class RecentSubmissionsWidget(ContentListWidget):
+    """The latest contact form submissions, each linking to its page in the admin."""
+
+    name = "RecentSubmissions"
+    refresh_interval = 60
+    limit = 5
+
+    def get_data(self, request):
+        check_view_permission(request, FormSubmission)
+        latest = list(FormSubmission.objects.order_by("-created_at")[: self.limit])
+        return {
+            "title": "Recent form submissions",
+            "description": (
+                "The latest messages from the contact form."
+                if latest
+                else "No messages yet. Submissions from the contact form appear here."
+            ),
+            "view_all": f"/content/{FormSubmission._meta.label_lower}",
+            "content": [
+                {
+                    "model": FormSubmission._meta.label_lower,
+                    "id": str(submission.pk),
+                    "title": submission.name,
+                    "description": Truncator(submission.message).chars(120),
+                    "timestamp": submission.created_at,
+                }
+                for submission in latest
+            ],
+        }

package/templates/backend/content/seed.py

@@ -10,7 +10,7 @@ from content_studio.media_library.models import Media
 from django.core.files.base import ContentFile
 from django.db import transaction
 
-from .models import Author, Category, Menu, Page, Post, Redirect, SiteSettings, Tag
+from .models import Author, Category, FormSubmission, Menu, Page, Post, Redirect, SiteSettings, Tag
 
 
 def block(type: str, **data) -> dict:
@@ -141,6 +141,13 @@ def seed(if_empty: bool = False, stdout=None) -> bool:
         items=[block("link", label="RSS", url="/rss.xml")],
     )
     Redirect.objects.create(old_path="/old-about", new_path="/about")
+    # Messages of the contact form, so the dashboard has something to show.
+    FormSubmission.objects.bulk_create(
+        [
+            FormSubmission(name="Grace Reader", email="grace@example.com", message="Is there an RSS feed of the blog?"),
+            FormSubmission(name="Alan Visitor", email="alan@example.com", message="Hello from the contact page."),
+        ]
+    )
 
     settings = SiteSettings.objects.first() or SiteSettings()
     settings.site_name = "{{project_name}}"

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

@@ -101,3 +101,18 @@ def test_contact_form_notifies_the_editors(seeded, django_capture_on_commit_call
 
 def test_read_key_cannot_read_submissions(reader):
     assert reader.get("/api/content.formsubmission").status_code == 403
+
+
+def test_editors_only_read_and_delete_submissions(rf):
+    from content_studio.admin import admin_site
+    from django.contrib.auth import get_user_model
+
+    from content.admin import FormSubmissionStudio
+
+    request = rf.get("/")
+    request.user = get_user_model().objects.create_superuser("editor", "editor@example.com", "x")
+    studio = FormSubmissionStudio(FormSubmission, admin_site)
+    assert studio.has_view_permission(request)
+    assert studio.has_delete_permission(request)
+    assert not studio.has_add_permission(request)
+    assert not studio.has_change_permission(request)

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

@@ -0,0 +1,77 @@
+"""
+The widgets of the admin dashboard (config/studio.py) answer with the
+seeded content, and only to editors who may view it.
+"""
+
+import pytest
+from content_studio.settings import cs_settings
+from django.contrib.auth import get_user_model
+from django.contrib.auth.models import Permission
+from django.test import RequestFactory
+from rest_framework.exceptions import PermissionDenied
+
+from content.dashboard import PublishedCountWidget, RecentSubmissionsWidget, SubmissionCountWidget
+from content.models import Page
+
+pytestmark = pytest.mark.django_db
+
+
+@pytest.fixture
+def seeded(settings, tmp_path):
+    from content.seed import seed
+
+    settings.MEDIA_ROOT = tmp_path
+    seed()
+
+
+def request_as(user):
+    request = RequestFactory().get("/")
+    request.user = user
+    return request
+
+
+@pytest.fixture
+def admin():
+    return get_user_model().objects.create_superuser("admin", "admin@example.com", "password")
+
+
+def widget(cls):
+    return next(w for w in cs_settings.ADMIN_SITE.dashboard.widgets if isinstance(w, cls))
+
+
+def test_every_widget_answers_on_an_empty_site(admin):
+    for item in cs_settings.ADMIN_SITE.dashboard.widgets:
+        assert item.get_data(request_as(admin)) is not None
+
+
+def test_no_submissions_yet(admin):
+    data = widget(RecentSubmissionsWidget).get_data(request_as(admin))
+    assert data["content"] == []
+    assert data["description"].startswith("No messages yet.")
+    assert data["view_all"] == "/content/content.formsubmission"
+
+
+def test_every_widget_answers(seeded, admin):
+    for item in cs_settings.ADMIN_SITE.dashboard.widgets:
+        assert item.get_data(request_as(admin)) is not None
+
+
+def test_counts_published_pages(seeded, admin):
+    data = widget(PublishedCountWidget).get_data(request_as(admin))
+    assert data["value"] == Page.objects.published().count()
+    assert data["footnote"] == "1 draft"
+
+
+def test_submissions(seeded, admin):
+    assert widget(SubmissionCountWidget).get_data(request_as(admin))["value"] == 2
+    rows = widget(RecentSubmissionsWidget).get_data(request_as(admin))["content"]
+    assert [row["title"] for row in rows] == ["Alan Visitor", "Grace Reader"]
+
+
+def test_submissions_need_the_view_permission(seeded):
+    editor = get_user_model().objects.create_user("editor", "editor@example.com", "password", is_staff=True)
+    with pytest.raises(PermissionDenied):
+        widget(RecentSubmissionsWidget).get_data(request_as(editor))
+    editor.user_permissions.add(Permission.objects.get(codename="view_formsubmission"))
+    editor = get_user_model().objects.get(pk=editor.pk)
+    assert len(widget(RecentSubmissionsWidget).get_data(request_as(editor))["content"]) == 2

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.11.0",
+    "django-stack[server,s3]>=0.12.1",
     "django-headless[schema]>=1.1.1",
     "django-content-studio[images,huey]>=1.11.0",
 ]

package/templates/base/README.md

@@ -90,7 +90,7 @@ commands.
 With the `dstack` command installed (`npm i -g @django-stack/cli`),
 `dstack dev`, `dstack check`, `dstack manage <command>` and `dstack types` do
 the same from any directory in the project. See the
-[CLI reference](https://dwarsbit.github.io/django-stack/docs/cli).
+[CLI reference](https://djangostack.org/docs/cli).
 
 ## Preview and publishing
 
@@ -106,7 +106,7 @@ empties its page cache, so the change shows on the next visit.
 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).
+[Preview and revalidation](https://djangostack.org/docs/preview-revalidation).
 <!-- @end -->
 <!-- @if templates -->
 The site keeps each page in Django's cache, and empties it when an editor
@@ -122,7 +122,7 @@ 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).
+[Page analytics](https://djangostack.org/docs/analytics).
 <!-- @end -->
 
 ## Deploy
@@ -138,7 +138,7 @@ docker compose up -d --build
 The `prod` profile runs production images behind Caddy, which gets the HTTPS
 certificate, and backs up the database every day. Media can go to S3 and the
 database to a managed Postgres. `.github/workflows/deploy.yml` deploys from
-GitHub Actions. The [deployment guide](https://dwarsbit.github.io/django-stack/docs/production/server)
+GitHub Actions. The [deployment guide](https://djangostack.org/docs/production/server)
 has every step.
 
 | Task | Command (on the server) |

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.11.0",
+    "@django-stack/utils": "^0.12.1",
     "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.11.0",
-    "@django-stack/react": "^0.11.0",
-    "@django-stack/utils": "^0.11.0",
+    "@django-stack/next": "^0.12.1",
+    "@django-stack/react": "^0.12.1",
+    "@django-stack/utils": "^0.12.1",
     "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.11.0",
-    "@django-stack/vue": "^0.11.0",
+    "@django-stack/utils": "^0.12.1",
+    "@django-stack/vue": "^0.12.1",
     "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.11.0",
-    "@django-stack/utils": "^0.11.0"
+    "@django-stack/svelte": "^0.12.1",
+    "@django-stack/utils": "^0.12.1"
   },
   "devDependencies": {
     "@sveltejs/adapter-node": "^6.0.1",

package/templates/frontend-templates/website/tests/test_site.py

@@ -99,4 +99,4 @@ def test_contact_form(client, seeded):
 def test_contact_form_needs_a_captcha(client, seeded):
     response = client.post("/contact", {"name": "Ada", "email": "ada@example.com", "message": "Hello"})
     assert response.status_code == 400
-    assert not FormSubmission.objects.exists()
+    assert not FormSubmission.objects.filter(email="ada@example.com").exists()