@django-stack/cli 0.0.1 → 0.1.0

package/templates/base/compose.yaml

@@ -0,0 +1,303 @@
+# {{project_name}}: one Compose file for development and production.
+#
+# COMPOSE_PROFILES in .env picks the services:
+#   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.
+#   Leave out `db` to use an external Postgres through DATABASE_URL, and add
+#   `s3` in development for a local S3 service (see .env).
+#
+# The frontend only receives the variables it needs: never the full-access
+# API key or the database password.
+
+name: {{project_name}}
+
+# Production containers: read-only file system, no privileges.
+x-hardened: &hardened
+  read_only: true
+  tmpfs:
+    - /tmp
+  security_opt:
+    - no-new-privileges:true
+  cap_drop:
+    - ALL
+
+x-frontend-env: &frontend-env
+  SITE_URL: ${SITE_URL}
+  API_URL: http://backend:8000/api
+  BACKEND_INTERNAL_URL: http://backend:8000
+  API_READ_KEY: ${API_READ_KEY}
+  PREVIEW_SECRET: ${PREVIEW_SECRET}
+  REVALIDATE_SECRET: ${REVALIDATE_SECRET}
+  MEDIA_ORIGINS: ${S3_PUBLIC_URL:-${S3_ENDPOINT_URL:-}}
+
+x-backend-depends: &backend-depends
+  db:
+    condition: service_healthy
+    required: false
+  cache:
+    condition: service_healthy
+  s3:
+    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)"]
+  interval: 5s
+  timeout: 5s
+  start_period: 60s
+  retries: 30
+
+services:
+  # Development ------------------------------------------------------------
+
+  backend:
+    profiles: [dev]
+    build:
+      context: ./backend
+      target: dev
+    env_file: ${ENV_FILE:-.env}
+    environment:
+      DJANGO_MIGRATE: "1"
+    volumes:
+      - ./backend:/app
+      - media:/app/media
+    ports:
+      - "127.0.0.1:8000:8000"
+    depends_on: *backend-depends
+    healthcheck: *backend-health
+    restart: unless-stopped
+
+  worker:
+    profiles: [dev]
+    build:
+      context: ./backend
+      target: dev
+    env_file: ${ENV_FILE:-.env}
+    command: ["python", "manage.py", "run_huey"]
+    volumes:
+      - ./backend:/app
+      - media:/app/media
+    depends_on:
+      backend:
+        condition: service_healthy
+    restart: unless-stopped
+
+  frontend:
+    profiles: [dev]
+    build:
+      context: ./frontend
+      target: dev
+    environment: *frontend-env
+    volumes:
+      - ./frontend:/app
+      - frontend_node_modules:/app/node_modules
+    ports:
+      - "127.0.0.1:3000:3000"
+    depends_on:
+      backend:
+        condition: service_healthy
+    restart: unless-stopped
+
+  mailpit:
+    profiles: [dev]
+    image: axllent/mailpit:v1.27
+    ports:
+      - "127.0.0.1:8025:8025"
+    restart: unless-stopped
+
+  # A local S3 service, so development runs the same storage code as
+  # production with S3. Files are public at http://localhost:8333/<bucket>/.
+  s3:
+    profiles: [s3]
+    image: chrislusf/seaweedfs:4.52
+    command: ["server", "-s3", "-dir=/data", "-ip.bind=0.0.0.0"]
+    volumes:
+      - s3data:/data
+    ports:
+      - "127.0.0.1:8333:8333"
+    restart: unless-stopped
+
+  # Production -------------------------------------------------------------
+
+  backend-prod:
+    profiles: [prod]
+    image: ${BACKEND_IMAGE:-{{project_name}}-backend}
+    build:
+      context: ./backend
+      target: prod
+    <<: *hardened
+    env_file: ${ENV_FILE:-.env}
+    environment:
+      DJANGO_DEBUG: "0"
+      DJANGO_MIGRATE: "1"
+      DJANGO_CHECK_DEPLOY: "1"
+      NUM_PROXIES: ${NUM_PROXIES:-1}
+    volumes:
+      - media:/app/media
+    depends_on: *backend-depends
+    healthcheck: *backend-health
+    networks:
+      default:
+        aliases: [backend]
+    deploy:
+      resources:
+        limits:
+          memory: 768M
+    restart: unless-stopped
+
+  worker-prod:
+    profiles: [prod]
+    image: ${BACKEND_IMAGE:-{{project_name}}-backend}
+    build:
+      context: ./backend
+      target: prod
+    <<: *hardened
+    env_file: ${ENV_FILE:-.env}
+    command: ["python", "manage.py", "run_huey"]
+    environment:
+      DJANGO_DEBUG: "0"
+      NUM_PROXIES: ${NUM_PROXIES:-1}
+    volumes:
+      - media:/app/media
+    depends_on:
+      backend-prod:
+        condition: service_healthy
+    healthcheck:
+      disable: true
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+    restart: unless-stopped
+
+  frontend-prod:
+    profiles: [prod]
+    image: ${FRONTEND_IMAGE:-{{project_name}}-frontend}
+    build:
+      context: ./frontend
+      target: prod
+    <<: *hardened
+    environment: *frontend-env
+    depends_on:
+      backend-prod:
+        condition: service_healthy
+    networks:
+      default:
+        aliases: [frontend]
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+    restart: unless-stopped
+
+  # The only service with public ports: HTTPS for SITE_URL with a
+  # certificate from Let's Encrypt, routing to Django and the frontend.
+  # Behind a platform's proxy, see CADDY_ADDRESS in .env.
+  proxy:
+    profiles: [prod]
+    image: caddy:2.11-alpine
+    <<: *hardened
+    cap_add:
+      - NET_BIND_SERVICE
+    environment:
+      CADDY_ADDRESS: ${CADDY_ADDRESS:-${SITE_URL}}
+      TRUSTED_PROXIES: ${TRUSTED_PROXIES:-127.0.0.1/32}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - media:/srv/media:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    ports:
+      - "${HTTP_PORT:-80}:80"
+      - "${HTTPS_PORT:-443}:443"
+      - "${HTTPS_PORT:-443}:443/udp"
+    depends_on:
+      backend-prod:
+        condition: service_healthy
+      frontend-prod:
+        condition: service_healthy
+    deploy:
+      resources:
+        limits:
+          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:
+    profiles: [db]
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-app}
+      POSTGRES_USER: ${POSTGRES_USER:-app}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+    security_opt:
+      - no-new-privileges:true
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+    restart: unless-stopped
+
+  # Cache, sessions and the task queue. Only keys with an expiry are
+  # evicted when memory runs out, so queued tasks are never dropped.
+  cache:
+    image: valkey/valkey:8-alpine
+    user: valkey
+    command: ["valkey-server", "--save", "", "--appendonly", "no", "--maxmemory", "200mb", "--maxmemory-policy", "volatile-lru"]
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 3s
+      timeout: 3s
+      retries: 20
+    <<: *hardened
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+    restart: unless-stopped
+
+volumes:
+  pgdata:
+  media:
+  backups:
+  s3data:
+  frontend_node_modules:
+  caddy_data:
+  caddy_config:

package/templates/base/env.example

@@ -0,0 +1,80 @@
+# {{project_name}} environment. `npx @django-stack/cli init` generates .env
+# from this file with fresh secrets; .env.example keeps the names without
+# values. Never commit .env.
+
+PROJECT_NAME={{project_name}}
+
+# Which services run (see compose.yaml):
+#   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.
+COMPOSE_PROFILES=dev,db
+
+# 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.
+SITE_URL=http://localhost:3000
+BACKEND_URL=http://localhost:3000
+
+# Behind the proxy of a platform such as Coolify or Dokploy, which gets the
+# certificate, Caddy serves plain HTTP on port 80 to it instead:
+#   CADDY_ADDRESS=:80 TRUSTED_PROXIES=private_ranges NUM_PROXIES=2
+#   HTTP_PORT=127.0.0.1:8080 HTTPS_PORT=127.0.0.1:8443
+
+# Django. The prod profile always runs with debug off.
+DJANGO_SECRET_KEY={{secret:django}}
+DJANGO_DEBUG=1
+
+# Database: the bundled Postgres, or your own URL for an external one
+# (add ?sslmode=require for a server on another host).
+POSTGRES_DB=app
+POSTGRES_USER=app
+POSTGRES_PASSWORD={{secret:postgres}}
+DATABASE_URL=postgres://app:{{secret:postgres}}@db:5432/app
+
+# Cache, task queue and mail. In production, EMAIL_URL is your SMTP server,
+# such as smtp+tls://user:password@smtp.example.com:587.
+CACHE_URL=redis://cache:6379/0
+EMAIL_URL=smtp://mailpit:1025
+DEFAULT_FROM_EMAIL={{project_name}} <noreply@localhost>
+
+# Content API keys. The full-access key is for scripts only; the frontend
+# gets the read-only key. They must differ.
+API_SECRET_KEY={{secret:api}}
+API_READ_KEY={{secret:api_read}}
+
+# Shared between Django and the frontend: preview links and revalidation.
+PREVIEW_SECRET={{secret:preview}}
+REVALIDATE_SECRET={{secret:revalidate}}
+REVALIDATE_URL=http://frontend:3000/revalidate
+
+# The first admin user, created on the first start.
+ADMIN_USERNAME=admin
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD={{secret:admin}}
+
+# Demo content for an empty site (pages, posts, menus); 0 to start empty.
+SEED_DEMO_CONTENT=1
+
+# Media in S3 instead of on this server: any S3-compatible service (AWS,
+# Cloudflare R2, Hetzner, Scaleway). Uploads must be publicly readable, at
+# S3_PUBLIC_URL when that is not the endpoint (a CDN or a custom domain).
+# For the local S3 service: add `s3` to COMPOSE_PROFILES and use
+#   S3_BUCKET=media S3_ENDPOINT_URL=http://s3:8333
+#   S3_PUBLIC_URL=http://localhost:8333/media S3_CREATE_BUCKET=1
+#   S3_ACCESS_KEY_ID=local S3_SECRET_ACCESS_KEY=local
+S3_BUCKET=
+S3_ENDPOINT_URL=
+S3_REGION=
+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.
+BACKUP_TIME=03:00
+BACKUP_KEEP=14
+BACKUP_S3_BUCKET=

package/templates/base/gitignore

@@ -0,0 +1,15 @@
+.env
+.env.run
+node_modules/
+backend/.venv/
+backend/media/
+backend/staticfiles/
+backend/openapi.json
+backend/db.sqlite3
+__pycache__/
+*.pyc
+frontend/dist/
+frontend/.astro/
+.DS_Store
+backend/backups/
+backend/huey-stats.db*

package/templates/base/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{project_name}}",
+  "private": true,
+  "description": "{{project_name}}: Django, Django Headless, Content Studio and Astro, created with DjangoStack.",
+  "scripts": {
+    "dev": "docker compose up --build",
+    "start": "docker compose up --build --detach",
+    "stop": "docker compose down",
+    "logs": "docker compose logs --follow",
+    "backend": "docker compose exec backend python manage.py",
+    "test": "docker compose exec backend pytest && docker compose exec frontend npm test",
+    "lint": "docker compose exec backend ruff check . && docker compose exec frontend npm run check",
+    "generate:types": "docker compose exec backend python manage.py generateschema --generator_class headless.rest.schema.SchemaGenerator --format openapi-json --file openapi.json && docker compose run --rm --no-deps -v ./backend/openapi.json:/schema.json:ro frontend npx headless generate --file /schema.json --out src/lib/headless.ts",
+    "doctor": "npx @django-stack/cli@{{cli_version}} doctor"
+  },
+  "django-stack": {
+    "version": "{{cli_version}}",
+    "frontend": "{{frontend}}",
+    "preset": "{{preset}}"
+  }
+}

package/templates/frontend-astro/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.astro
+.env

package/templates/frontend-astro/Dockerfile

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1
+
+# The frontend image. The `dev` target runs the Astro dev server with the
+# source mounted; `prod` builds the site and runs the Node server.
+FROM node:22-alpine AS base
+WORKDIR /app
+ENV ASTRO_TELEMETRY_DISABLED=1
+
+FROM base AS deps
+COPY package.json package-lock.json* ./
+COPY vendor/ vendor/
+RUN --mount=type=cache,target=/root/.npm \
+    if [ -f package-lock.json ]; then npm ci; else npm install; fi
+
+FROM deps AS dev
+EXPOSE 3000
+CMD ["npm", "run", "dev"]
+
+FROM deps AS build
+COPY . .
+RUN npm run build && npm prune --omit=dev
+
+FROM base AS prod
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --from=build --chown=node:node /app/package.json ./package.json
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=10s --timeout=5s --start-period=20s --retries=5 \
+    CMD wget -qO- http://127.0.0.1:3000/robots.txt > /dev/null || exit 1
+CMD ["node", "./dist/server/entry.mjs"]

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

@@ -0,0 +1,38 @@
+// @ts-check
+import node from "@astrojs/node";
+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";
+
+export default defineConfig({
+  site: process.env.SITE_URL ?? "http://localhost:3000",
+  // Server output: pages render on request, so a publish shows within seconds.
+  output: "server",
+  adapter: node({ mode: "standalone" }),
+  server: { host: true, port: 3000 },
+  // A Content-Security-Policy on every page: scripts and styles only from
+  // this site, with hashes for the ones Astro inlines. src/middleware.ts adds
+  // the origin of the media files.
+  security: {
+    csp: {
+      directives: ["default-src 'self'", "base-uri 'self'", "form-action 'self'", "object-src 'none'"],
+      // Inline style attributes, such as the focal point of an image.
+      styleDirective: { resources: ["'self'", { resource: "'unsafe-inline'", kind: "attribute" }] },
+    },
+  },
+  vite: {
+    server: {
+      // Django calls /revalidate at http://frontend:3000 on the Compose network.
+      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 },
+        ]),
+      ),
+    },
+  },
+});

package/templates/frontend-astro/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{project_name}}-frontend",
+  "private": true,
+  "type": "module",
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "start": "node ./dist/server/entry.mjs",
+    "preview": "astro preview",
+    "check": "astro check",
+    "test": "vitest run",
+    "generate:types": "headless generate --url \"${API_URL:-http://localhost:8000/api}/schema\" --out src/lib/headless.ts"
+  },
+  "dependencies": {
+    "@astrojs/node": "^11.1.9",
+    "@astrojs/rss": "^4.0.19",
+    "@django-headless/client": "^1.1.1",
+    "@django-stack/utils": "^0.1.0",
+    "astro": "^7.4.5"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.12",
+    "@types/node": "^22.20.5",
+    "typescript": "~5.9.3",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/frontend-astro/public/favicon.svg

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

package/templates/frontend-astro/src/components/Blocks.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * Renders a Content Studio block field. To add a block type: define it in
+ * backend/content/blocks.py, add a component in ./blocks and map its type
+ * here. Unknown types render nothing.
+ */
+import type { Block } from "@django-stack/utils";
+import CallToAction from "./blocks/CallToAction.astro";
+import Image from "./blocks/Image.astro";
+import Quote from "./blocks/Quote.astro";
+import Text from "./blocks/Text.astro";
+
+const registry: Record<string, (props: { block: Block }) => unknown> = {
+  text: Text,
+  image: Image,
+  quote: Quote,
+  call_to_action: CallToAction,
+};
+
+interface Props {
+  blocks: Block[] | null | undefined;
+}
+
+const { blocks = [] } = Astro.props;
+---
+
+{
+  (blocks ?? []).map((block) => {
+    const Component = registry[block.type];
+    return Component ? <Component block={block} /> : null;
+  })
+}

package/templates/frontend-astro/src/components/ContactForm.astro

@@ -0,0 +1,68 @@
+---
+/**
+ * The contact form. It posts to Django's public create route for form
+ * submissions (PUBLIC_CREATE in backend/config/settings.py), which is
+ * rate limited per IP address. Submissions appear in the admin.
+ */
+---
+
+<form class="contact-form" data-endpoint="/api/content.formsubmission">
+  <label>Name <input name="name" required maxlength="200" autocomplete="name" /></label>
+  <label>Email <input name="email" type="email" required autocomplete="email" /></label>
+  <label>Message <textarea name="message" required maxlength="5000" rows="6"></textarea></label>
+  <button class="button" type="submit">Send</button>
+  <p class="status" role="status" aria-live="polite"></p>
+</form>
+
+<script>
+  for (const form of document.querySelectorAll<HTMLFormElement>("form.contact-form")) {
+    form.addEventListener("submit", async (event) => {
+      event.preventDefault();
+      const status = form.querySelector<HTMLElement>(".status")!;
+      const button = form.querySelector<HTMLButtonElement>("button")!;
+      button.disabled = true;
+      status.textContent = "Sending…";
+      try {
+        const response = await fetch(form.dataset.endpoint!, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(Object.fromEntries(new FormData(form))),
+        });
+        if (response.status === 429) throw new Error("Too many messages; try again in a minute.");
+        if (!response.ok) throw new Error("The message could not be sent. Check the fields and try again.");
+        form.reset();
+        status.textContent = "Thank you, your message was sent.";
+      } catch (error) {
+        status.textContent = error instanceof Error ? error.message : String(error);
+      } finally {
+        button.disabled = false;
+      }
+    });
+  }
+</script>
+
+<style>
+  .contact-form {
+    display: grid;
+    gap: 1rem;
+    max-width: 32rem;
+    margin-top: 2rem;
+  }
+  label {
+    display: grid;
+    gap: 0.25rem;
+    font-weight: 600;
+  }
+  input,
+  textarea {
+    font: inherit;
+    padding: 0.5rem 0.75rem;
+    border: 1px solid var(--color-line);
+    border-radius: 0.375rem;
+    background: transparent;
+    color: inherit;
+  }
+  button {
+    justify-self: start;
+  }
+</style>

package/templates/frontend-astro/src/components/Image.astro

@@ -0,0 +1,34 @@
+---
+import { imageAttributes, type Media } from "@django-stack/utils";
+
+interface Props {
+  media: Media | string | null | undefined;
+  /** An image size from IMAGE_SIZES, such as card or hero. */
+  size?: string;
+  /** The sizes attribute, for the browser to pick from the srcset. */
+  sizes?: string;
+  alt?: string;
+  class?: string;
+  eager?: boolean;
+}
+
+const { media, size, sizes = "100vw", alt, eager = false, class: className } = Astro.props;
+const attributes = imageAttributes(media, { size, alt });
+---
+
+{
+  attributes && (
+    <img
+      src={attributes.src}
+      srcset={attributes.srcset}
+      sizes={attributes.srcset ? sizes : undefined}
+      width={attributes.width}
+      height={attributes.height}
+      alt={attributes.alt}
+      class={className}
+      style={attributes.objectPosition ? `object-position: ${attributes.objectPosition}` : undefined}
+      loading={eager ? "eager" : "lazy"}
+      decoding="async"
+    />
+  )
+}