@django-stack/cli 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -4,6 +4,8 @@ interface Check {
   /** Not a failure: the check could not run or only warns. */
   warning?: boolean;
   detail?: string;
+  /** How to fix a failed check, one line each. */
+  help?: string[];
 }
 /** Checks a project directory: tools, .env, and the running services. */
 export declare function runDoctor(directory: string): Promise<Check[]>;

package/dist/index.js

@@ -1 +1 @@
-export { t as DEFAULT_STACK, u as FRONTENDS, n as NAMED_PRESETS, r as STACK_OPTIONS, b as VERSION, a as decodePreset, o as encodePreset, C as generateProjectSecrets, w as generateSecret, p as normalizeDatabaseUrl, E as parseEnv, s as pendingChoices, x as productionEnv, c as resolvePreset, T as runDoctor, h as scaffold, D as setEnvValues, _ as toProjectName, S as validateDomain, v as validateProjectName } from "./stack-OTrWHXrO.js";
+export { t as DEFAULT_STACK, u as FRONTENDS, n as NAMED_PRESETS, r as STACK_OPTIONS, b as VERSION, a as decodePreset, o as encodePreset, C as generateProjectSecrets, w as generateSecret, p as normalizeDatabaseUrl, D as parseEnv, s as pendingChoices, x as productionEnv, c as resolvePreset, T as runDoctor, h as scaffold, O as setEnvValues, _ as toProjectName, S as validateDomain, v as validateProjectName } from "./stack-CTyqYWCV.js";

package/dist/{stack-OTrWHXrO.js → stack-CTyqYWCV.js}

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
-import { execFileSync } from "node:child_process";
 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 { fileURLToPath } from "node:url";
 // src/env.ts
@@ -28,17 +28,10 @@ function setEnvValues(text, values) {
 	}
 	return result;
 }
-// src/doctor.ts
-const REQUIRED_KEYS = [
-	"DJANGO_SECRET_KEY",
-	"DATABASE_URL",
-	"API_SECRET_KEY",
-	"API_READ_KEY",
-	"PREVIEW_SECRET",
-	"REVALIDATE_SECRET",
-	"SITE_URL"
-];
-function command(cmd, args, cwd) {
+/** The oldest Python the backend runs on. */
+const MIN_PYTHON = "3.12";
+/** Runs a command and returns its trimmed output, or undefined when it fails. */
+const run = (cmd, args, cwd) => {
 	try {
 		return execFileSync(cmd, args, {
 			cwd,
@@ -52,32 +45,69 @@ function command(cmd, args, cwd) {
 	} catch {
 		return;
 	}
+};
+/** The first `x.y.z` version in a text, such as `Python 3.13.1` or `v22.11.0`. */
+function parseVersion(text) {
+	return text?.match(/(\d+)\.(\d+)(?:\.(\d+))?/)?.[0];
 }
-async function fetchStatus(url, headers = {}) {
-	try {
-		return (await fetch(url, {
-			headers,
-			redirect: "manual",
-			signal: AbortSignal.timeout(5e3)
-		})).status;
-	} catch {
-		return;
+/** Whether version `a` is at least `b`, compared by number per part. */
+function atLeast(a, b) {
+	const left = a.split(".").map(Number);
+	const right = b.split(".").map(Number);
+	for (let i = 0; i < Math.max(left.length, right.length); i++) {
+		const x = left[i] ?? 0;
+		const y = right[i] ?? 0;
+		if (x !== y) return x > y;
 	}
+	return true;
 }
-/** Checks a project directory: tools, .env, and the running services. */
-async function runDoctor(directory) {
-	const checks = [];
-	const docker = command("docker", [
+function dockerHelp(platform) {
+	if (platform === "darwin") return ["Install Docker Desktop: brew install --cask docker", "or https://docs.docker.com/desktop/setup/install/mac-install/"];
+	if (platform === "win32") return ["Install Docker Desktop: winget install Docker.DockerDesktop", "or https://docs.docker.com/desktop/setup/install/windows-install/"];
+	return ["Install Docker Engine and the Compose plugin: https://docs.docker.com/engine/install/"];
+}
+function dockerStartHelp(platform) {
+	if (platform === "linux") return ["Start it: sudo systemctl start docker"];
+	return ["Open Docker Desktop and wait until it says it is running."];
+}
+function nodeHelp(platform) {
+	return [`Install it with fnm: ${platform === "darwin" ? "brew install fnm" : platform === "win32" ? "winget install Schniz.fnm" : "curl -fsSL https://fnm.vercel.app/install | bash"}, then fnm install 22`, "or https://nodejs.org/en/download"];
+}
+function pythonHelp(platform, hasUv) {
+	const python = "uv python install 3.13";
+	if (hasUv) return [`Install it with uv: ${python}`];
+	return [`Install uv: ${platform === "darwin" ? "brew install uv" : platform === "win32" ? "winget install astral-sh.uv" : "curl -LsSf https://astral.sh/uv/install.sh | sh"}, then ${python}`, "or https://docs.astral.sh/uv/getting-started/installation/"];
+}
+function pythonVersion(runCommand) {
+	for (const [cmd, args] of [
+		["python3", ["--version"]],
+		["python", ["--version"]],
+		["py", ["-3", "--version"]]
+	]) {
+		const version = parseVersion(runCommand(cmd, [...args]));
+		if (version) return version;
+	}
+}
+/** Docker and Docker Compose, which run the project. */
+function checkDocker({ run: runCommand = run, platform = process.platform } = {}) {
+	const client = parseVersion(runCommand("docker", ["--version"]));
+	if (!client) return [{
+		name: "Docker is installed",
+		ok: false,
+		help: dockerHelp(platform)
+	}];
+	const server = runCommand("docker", [
 		"version",
 		"--format",
 		"{{.Server.Version}}"
 	]);
-	checks.push({
+	const checks = [{
 		name: "Docker is running",
-		ok: Boolean(docker),
-		detail: docker ? `Docker ${docker}` : "Install Docker and start it: https://docs.docker.com/get-docker/"
-	});
-	const compose = command("docker", [
+		ok: Boolean(server),
+		detail: server ? `Docker ${server}` : `Docker ${client} is installed but not running.`,
+		help: server ? void 0 : dockerStartHelp(platform)
+	}];
+	const compose = runCommand("docker", [
 		"compose",
 		"version",
 		"--short"
@@ -85,8 +115,66 @@ async function runDoctor(directory) {
 	checks.push({
 		name: "Docker Compose v2",
 		ok: Boolean(compose),
-		detail: compose ? `Compose ${compose}` : "Docker Compose v2 is part of Docker Desktop and the docker-compose-plugin package."
+		detail: compose ? `Compose ${compose}` : void 0,
+		help: compose ? void 0 : ["Docker Compose v2 is part of Docker Desktop and the docker-compose-plugin package."]
 	});
+	return checks;
+}
+/**
+* Node.js and Python, which you need to work on the frontend and the backend
+* outside the containers. They only warn: the project runs in Docker without them.
+*/
+function checkDevTools({ run: runCommand = run, platform = process.platform } = {}) {
+	const checks = [];
+	const node = parseVersion(runCommand("node", ["--version"]));
+	const nodeOk = Boolean(node && atLeast(node, "22"));
+	checks.push({
+		name: `Node.js 22 or later`,
+		ok: nodeOk,
+		warning: !nodeOk,
+		detail: node ? `Node.js ${node}` : "Node.js was not found.",
+		help: nodeOk ? void 0 : nodeHelp(platform)
+	});
+	const python = pythonVersion(runCommand);
+	const pythonOk = Boolean(python && atLeast(python, "3.12"));
+	checks.push({
+		name: `Python ${MIN_PYTHON} or later`,
+		ok: pythonOk,
+		warning: !pythonOk,
+		detail: python ? `Python ${python}` : "Python was not found.",
+		help: pythonOk ? void 0 : pythonHelp(platform, Boolean(runCommand("uv", ["--version"])))
+	});
+	return checks;
+}
+/** Every tool a project needs on this computer. */
+function checkTools(options = {}) {
+	return [...checkDocker(options), ...checkDevTools(options)];
+}
+// src/doctor.ts
+const REQUIRED_KEYS = [
+	"DJANGO_SECRET_KEY",
+	"DATABASE_URL",
+	"API_SECRET_KEY",
+	"API_READ_KEY",
+	"PREVIEW_SECRET",
+	"REVALIDATE_SECRET",
+	"SITE_URL"
+];
+async function fetchStatus(url, headers = {}) {
+	try {
+		return (await fetch(url, {
+			headers,
+			redirect: "manual",
+			signal: AbortSignal.timeout(5e3)
+		})).status;
+	} catch {
+		return;
+	}
+}
+/** Checks a project directory: tools, .env, and the running services. */
+async function runDoctor(directory) {
+	const checks = [];
+	checks.push(...checkTools());
 	const envPath = join(directory, ".env");
 	if (!existsSync(envPath)) {
 		checks.push({
@@ -131,7 +219,7 @@ async function runDoctor(directory) {
 			detail: "Set EMAIL_URL to your SMTP server; Mailpit only runs in development."
 		});
 	}
-	const running = command("docker", [
+	const running = run("docker", [
 		"compose",
 		"ps",
 		"--services",
@@ -148,7 +236,7 @@ async function runDoctor(directory) {
 		detail: services.length ? services.join(", ") : `Nothing is running. Start the project with \`docker compose up${prod ? " -d" : ""}\`.`
 	});
 	if (services.length === 0) return checks;
-	const health = command("docker", [
+	const health = run("docker", [
 		"compose",
 		"ps",
 		backendService,
@@ -709,4 +797,4 @@ function pendingChoices(stack) {
 		}];
 	});
 }
-export { generateProjectSecrets as C, setEnvValues as D, parseEnv as E, validateDomain as S, runDoctor as T, toProjectName as _, decodePreset as a, CLI_VERSION as b, resolvePreset as c, LOCAL_S3 as d, lockBackend as f, timeZones as g, scaffold as h, applies as i, stackOption as l, relativeDirectory as m, NAMED_PRESETS as n, encodePreset as o, normalizeDatabaseUrl as p, STACK_OPTIONS as r, pendingChoices as s, DEFAULT_STACK as t, FRONTENDS as u, validateProjectName as v, generateSecret as w, productionEnv as x, validateTimeZone as y };
+export { generateProjectSecrets as C, parseEnv as D, checkTools as E, setEnvValues as O, validateDomain as S, runDoctor as T, toProjectName as _, decodePreset as a, CLI_VERSION as b, resolvePreset as c, LOCAL_S3 as d, lockBackend as f, timeZones as g, scaffold as h, applies as i, stackOption as l, relativeDirectory as m, NAMED_PRESETS as n, encodePreset as o, normalizeDatabaseUrl as p, STACK_OPTIONS as r, pendingChoices as s, DEFAULT_STACK as t, FRONTENDS as u, validateProjectName as v, generateSecret as w, productionEnv as x, validateTimeZone as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@django-stack/cli",
-  "version": "0.1.0",
+  "version": "0.3.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",
@@ -44,6 +44,7 @@
   "dependencies": {
     "@bomb.sh/tab": "^0.0.22",
     "@clack/prompts": "^1.8.1",
+    "@napi-rs/keyring": "^2.1.2",
     "commander": "^15.0.0",
     "picocolors": "^1.1.1"
   },

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

package/templates/base/AGENTS.md

@@ -43,7 +43,8 @@ Run them at the project root. They need Docker; Node is only needed for the `npm
 | Production settings for a server | `npx @django-stack/cli production --domain example.com` |
 
 In production (`COMPOSE_PROFILES=prod,db`) the services are `backend-prod`,
-`worker-prod`, `frontend-prod`, `proxy` and `backup`; their containers are
+`worker-prod` (which also runs the daily backup), `frontend-prod` and
+`proxy`; 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/README.md

@@ -37,7 +37,7 @@ the frontend Astro's, with the source mounted from `backend/` and
 | Run the tests | `npm test` |
 | Check the setup | `npm run doctor` |
 
-With the `dstack` command installed (`npm install --global @django-stack/cli`),
+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).
@@ -70,9 +70,9 @@ has every step.
 | Task | Command (on the server) |
 |------|---------|
 | Update | `git pull && docker compose up -d --build` |
-| Back up now | `docker compose exec backup python manage.py backup_database` |
-| List backups | `docker compose exec backup python manage.py backup_database --list` |
-| Restore | `docker compose exec backup python manage.py restore_database <name>` |
+| Back up the database and media now | `docker compose exec worker-prod python manage.py backup_database` |
+| List backups | `docker compose exec worker-prod python manage.py backup_database --list` |
+| Restore | `docker compose exec worker-prod python manage.py restore_database <name> --media` |
 | Logs | `docker compose logs --follow backend-prod` |
 
 ## Security

package/templates/base/compose.yaml

@@ -4,7 +4,7 @@
 #   dev,db    `docker compose up` on a laptop: dev servers with hot reload,
 #             http://localhost:3000, Mailpit at http://localhost:8025.
 #   prod,db   `docker compose up -d` on a server: production images behind
-#             Caddy on ports 80 and 443, with automatic HTTPS and backups.
+#             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).
 #
@@ -156,11 +156,17 @@ services:
     <<: *hardened
     env_file: ${ENV_FILE:-.env}
     command: ["python", "manage.py", "run_huey"]
+    # Also runs the daily backup of the database, and of the media volume
+    # when uploads are not in S3, at BACKUP_TIME (UTC) into the backups
+    # volume and BACKUP_S3_BUCKET. See README.md.
     environment:
       DJANGO_DEBUG: "0"
       NUM_PROXIES: ${NUM_PROXIES:-1}
+      BACKUP_DAILY: "1"
+      BACKUP_DIR: /app/backups
     volumes:
       - media:/app/media
+      - backups:/app/backups
     depends_on:
       backend-prod:
         condition: service_healthy
@@ -224,33 +230,6 @@ services:
           memory: 256M
     restart: unless-stopped
 
-  # Backs up the database every day at BACKUP_TIME (UTC) into the backups
-  # volume, and into BACKUP_S3_BUCKET when it is set. See README.md.
-  backup:
-    profiles: [prod]
-    image: ${BACKEND_IMAGE:-{{project_name}}-backend}
-    build:
-      context: ./backend
-      target: prod
-    <<: *hardened
-    env_file: ${ENV_FILE:-.env}
-    command: ["python", "manage.py", "run_backups"]
-    environment:
-      DJANGO_DEBUG: "0"
-      BACKUP_DIR: /app/backups
-    volumes:
-      - backups:/app/backups
-    depends_on:
-      backend-prod:
-        condition: service_healthy
-    healthcheck:
-      disable: true
-    deploy:
-      resources:
-        limits:
-          memory: 256M
-    restart: unless-stopped
-
   # Shared -----------------------------------------------------------------
 
   db:

package/templates/base/env.example

@@ -71,10 +71,13 @@ S3_ACCESS_KEY_ID=
 S3_SECRET_ACCESS_KEY=
 S3_PUBLIC_URL=
 
-# Backups (prod profile): a daily pg_dump at BACKUP_TIME (UTC), the newest
-# BACKUP_KEEP kept in the backups volume. Set BACKUP_S3_BUCKET to a private
-# bucket (never the public media bucket) to keep a copy off the server; it
-# uses the S3_* credentials unless BACKUP_S3_* ones are set.
+# 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.
+# Set BACKUP_S3_BUCKET to a private bucket (never the public media bucket)
+# to keep a copy off the server; it uses the S3_* credentials unless
+# BACKUP_S3_* ones are set.
 BACKUP_TIME=03:00
 BACKUP_KEEP=14
+BACKUP_MEDIA=1
 BACKUP_S3_BUCKET=

package/templates/base/gitignore

@@ -1,4 +1,5 @@
 .env
+.env.production
 .env.run
 node_modules/
 backend/.venv/

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