@django-stack/cli 0.0.1 → 0.1.0

package/templates/backend/content/seed.py

@@ -0,0 +1,153 @@
+"""
+Demo content for a new site: `manage.py seed_content` runs ``seed``.
+Change it to fit your site, or delete the demo content in the admin.
+"""
+
+import io
+import uuid
+
+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
+
+
+def block(type: str, **data) -> dict:
+    return {"id": str(uuid.uuid4()), "type": type, "data": data}
+
+
+def text(html: str) -> dict:
+    return block("text", body=html)
+
+
+def image_block(media: Media, caption: str = "") -> dict:
+    return block("image", image=str(media.pk), caption=caption)
+
+
+def make_image(name: str, hue: int, width: int = 1600, height: int = 900) -> Media:
+    """A generated gradient image, so the demo needs no downloads."""
+    from PIL import Image, ImageOps
+
+    gradient = Image.linear_gradient("L").rotate(30 * hue, expand=True).resize((width, height))
+    colors = [("#0c4b33", "#44b78b"), ("#1e3a8a", "#60a5fa"), ("#7c2d12", "#fb923c"), ("#4c1d95", "#c084fc")]
+    dark, light = colors[hue % len(colors)]
+    image = ImageOps.colorize(gradient, black=dark, white=light)
+    buffer = io.BytesIO()
+    image.save(buffer, format="JPEG", quality=85)
+    media = Media(name=name, alt_text=name, type="image", metadata={"width": width, "height": height})
+    media.file.save(f"{name.lower().replace(' ', '-')}.jpg", ContentFile(buffer.getvalue()), save=False)
+    media.save()
+    return media
+
+
+@transaction.atomic
+def seed(if_empty: bool = False, stdout=None) -> bool:
+    if if_empty and (Page.objects.exists() or Post.objects.exists()):
+        return False
+
+    hero = make_image("Hero image", 0)
+    covers = [make_image(f"Cover {number}", number) for number in range(1, 4)]
+
+    home = Page.objects.create(
+        title="Welcome",
+        slug="home",
+        status="published",
+        seo_description="A new site built with DjangoStack.",
+        body=[
+            text(
+                "<h2>Your site is running</h2>"
+                '<p>This page comes from Django: edit it in the admin at <a href="/admin/">/admin/</a>, '
+                "publish, and the site shows the change.</p>"
+            ),
+            image_block(hero, "Images come from the media library, in every size the site needs."),
+            block(
+                "call_to_action",
+                title="Read the blog",
+                text="Three demo posts show categories, tags, authors and cover images.",
+                button_label="Go to the blog",
+                button_url="/blog",
+            ),
+        ],
+    )
+    about = Page.objects.create(
+        title="About",
+        slug="about",
+        status="published",
+        body=[
+            text("<p>An about page. Pages can have child pages, such as the team page below.</p>"),
+            block("quote", text="Content first, code second.", attribution="An editor"),
+        ],
+    )
+    Page.objects.create(
+        title="Team",
+        slug="team",
+        parent=about,
+        status="published",
+        body=[text("<p>A child page at <code>/about/team</code>.</p>")],
+    )
+    contact = Page.objects.create(
+        title="Contact",
+        slug="contact",
+        status="published",
+        body=[text("<p>Send a message with the form below. Submissions appear in the admin.</p>")],
+    )
+    Page.objects.create(
+        title="Draft page",
+        slug="draft",
+        body=[text("<p>Only visible with a preview link from the admin.</p>")],
+    )
+
+    author = Author.objects.create(name="Ada Editor", slug="ada", bio="Writes the demo posts.")
+    news = Category.objects.create(name="News", slug="news")
+    guides = Category.objects.create(name="Guides", slug="guides")
+    django_tag = Tag.objects.create(name="Django", slug="django")
+    astro_tag = Tag.objects.create(name="Astro", slug="astro")
+
+    posts = [
+        ("Hello, world", "hello-world", news, [django_tag], "The first post of the new site."),
+        ("Editing content", "editing-content", guides, [django_tag], "How pages and posts are edited."),
+        ("Rendering with Astro", "rendering-with-astro", guides, [astro_tag], "How the frontend shows content."),
+    ]
+    for (title, slug, category, tags, excerpt), cover in zip(posts, covers, strict=True):
+        post = Post.objects.create(
+            title=title,
+            slug=slug,
+            excerpt=excerpt,
+            cover=cover,
+            author=author,
+            status="published",
+            body=[
+                text(f"<p>{excerpt}</p><h2>A heading</h2><p>Body text with <strong>bold</strong> words.</p>"),
+                text("<ul><li>A list item</li><li>Another one</li></ul>"),
+            ],
+        )
+        post.categories.add(category)
+        post.tags.set(tags)
+
+    Menu.objects.create(
+        name="Main",
+        slug="main",
+        items=[
+            block("link", label="Home", url="/"),
+            block("link", label="Blog", url="/blog"),
+            block("link", label="About", page=about.pk),
+            block("link", label="Contact", page=contact.pk),
+        ],
+    )
+    Menu.objects.create(
+        name="Footer",
+        slug="footer",
+        items=[block("link", label="RSS", url="/rss.xml")],
+    )
+    Redirect.objects.create(old_path="/old-about", new_path="/about")
+
+    settings = SiteSettings.objects.first() or SiteSettings()
+    settings.site_name = "{{project_name}}"
+    settings.tagline = "Built with DjangoStack"
+    settings.home_page = home
+    settings.seo_description = "A website built with Django, Django Headless, Content Studio and Astro."
+    settings.share_image = hero
+    settings.footer_text = "<p>Powered by DjangoStack.</p>"
+    settings.save()
+    return True

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

@@ -0,0 +1,73 @@
+"""
+Smoke tests of the content API: every exposed model answers the read-only
+key, drafts stay hidden, and the contact form takes submissions.
+Run them with `pnpm test` at the project root.
+"""
+
+import pytest
+from django.conf import settings
+from rest_framework.test import APIClient
+
+from content.models import FormSubmission, Page, Post
+from content.seed import seed
+
+pytestmark = pytest.mark.django_db
+
+ROUTES = [
+    "content.page",
+    "content.post",
+    "content.category",
+    "content.tag",
+    "content.author",
+    "content.menu",
+    "content.redirect",
+    "content.sitesettings",
+    "content_studio_media_library.media",
+]
+
+
+@pytest.fixture
+def reader():
+    return APIClient(headers={"X-Secret-Key": settings.HEADLESS["AUTH_READ_ONLY_SECRET_KEY"]})
+
+
+@pytest.fixture
+def seeded(settings, tmp_path):
+    settings.MEDIA_ROOT = tmp_path
+    seed()
+
+
+@pytest.mark.parametrize("route", ROUTES)
+def test_read_key_reads_every_model(reader, seeded, route):
+    assert reader.get(f"/api/{route}").status_code == 200
+
+
+def test_api_is_closed_without_a_key(seeded):
+    assert APIClient().get("/api/content.page").status_code in (401, 403)
+
+
+def test_drafts_are_hidden(reader, seeded):
+    assert Page.objects.filter(slug="draft").exists()
+    assert reader.get("/api/content.page?path=draft").json()["data"] == []
+    assert reader.get("/api/content.page?path=about/team").json()["data"][0]["title"] == "Team"
+
+
+def test_post_by_slug(reader, seeded):
+    post = Post.objects.first()
+    data = reader.get(f"/api/content.post/by_slug/{post.slug}?expand=cover,author").json()
+    assert data["title"] == post.title
+    assert data["cover"]["url"]
+
+
+def test_contact_form(seeded):
+    response = APIClient().post(
+        "/api/content.formsubmission",
+        {"name": "Ada", "email": "ada@example.com", "message": "Hello"},
+        format="json",
+    )
+    assert response.status_code == 201
+    assert FormSubmission.objects.filter(email="ada@example.com").exists()
+
+
+def test_read_key_cannot_read_submissions(reader):
+    assert reader.get("/api/content.formsubmission").status_code == 403

package/templates/backend/entrypoint.sh

@@ -0,0 +1,27 @@
+#!/bin/sh
+# Runs before the backend, worker and backup commands.
+#
+# DJANGO_MIGRATE=1 (the backend service): migrate the database, create the
+# 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.
+set -eu
+
+python manage.py wait_for_db
+
+if [ "${DJANGO_MIGRATE:-0}" = "1" ]; then
+  if [ "${DJANGO_CHECK_DEPLOY:-0}" = "1" ]; then
+    python manage.py check --deploy --fail-level ERROR
+  fi
+  if [ "${S3_CREATE_BUCKET:-0}" = "1" ]; then
+    python manage.py create_bucket
+  fi
+  python manage.py migrate --noinput
+  python manage.py create_admin
+  if [ "${SEED_DEMO_CONTENT:-0}" = "1" ]; then
+    python manage.py seed_content --if-empty
+  fi
+fi
+
+exec "$@"

package/templates/backend/manage.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+"""Django's command-line utility for administrative tasks."""
+
+import os
+import sys
+
+
+def main():
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
+    from django.core.management import execute_from_command_line
+
+    execute_from_command_line(sys.argv)
+
+
+if __name__ == "__main__":
+    main()

package/templates/backend/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "{{project_name}}-backend"
+version = "0.1.0"
+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-headless[schema]>=1.1.1",
+    "django-content-studio[images,huey]>=1.8.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-django>=4.11", "ruff>=0.15"]
+
+[tool.uv]
+package = false
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "config.settings"
+python_files = ["test_*.py"]
+filterwarnings = [
+    # WhiteNoise warns that collectstatic has not run, which tests do not need.
+    "ignore:No directory at:UserWarning",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+extend-exclude = ["*/migrations/*"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "DJ"]

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

@@ -0,0 +1,70 @@
+# Builds the production images, pushes them to the GitHub Container Registry
+# and deploys them to your server over SSH. Optional: without it, build on
+# the server with `docker compose up -d --build`.
+#
+# Set up once (see the deployment docs):
+# 1. The server has Docker, the project directory (DEPLOY_PATH) and its .env.
+# 2. Repository secrets: DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY (a private
+#    key the server accepts), DEPLOY_PATH and DEPLOY_KNOWN_HOSTS (the output
+#    of `ssh-keyscan your-server`).
+#
+# It runs when you start it from the Actions tab. To deploy every push to
+# main, add `push: { branches: [main] }` under `on`.
+
+name: Deploy
+
+on:
+  workflow_dispatch:
+
+concurrency: deploy
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  BACKEND_IMAGE: ghcr.io/${{ github.repository }}-backend:${{ github.sha }}
+  FRONTEND_IMAGE: ghcr.io/${{ github.repository }}-frontend:${{ github.sha }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Log in to the container registry
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io --username "${{ github.actor }}" --password-stdin
+
+      - name: Build and push the images
+        run: |
+          docker build --target prod --tag "${BACKEND_IMAGE,,}" backend
+          docker build --target prod --tag "${FRONTEND_IMAGE,,}" frontend
+          docker push "${BACKEND_IMAGE,,}"
+          docker push "${FRONTEND_IMAGE,,}"
+
+      - name: Set up SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.DEPLOY_SSH_KEY }}" > ~/.ssh/id_deploy
+          echo "${{ secrets.DEPLOY_KNOWN_HOSTS }}" > ~/.ssh/known_hosts
+          chmod 600 ~/.ssh/id_deploy ~/.ssh/known_hosts
+
+      - name: Deploy
+        env:
+          TARGET: ${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}
+          DEPLOY_PATH: ${{ secrets.DEPLOY_PATH }}
+          REGISTRY_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          ssh_cmd="ssh -i $HOME/.ssh/id_deploy"
+          # The Compose file and the Caddyfile come from the repository; the
+          # server keeps its own .env.
+          scp -i ~/.ssh/id_deploy compose.yaml Caddyfile "$TARGET:$DEPLOY_PATH/"
+          $ssh_cmd "$TARGET" "
+            set -e
+            cd '$DEPLOY_PATH'
+            echo '$REGISTRY_TOKEN' | docker login ghcr.io --username '${{ github.actor }}' --password-stdin
+            export BACKEND_IMAGE='${BACKEND_IMAGE,,}' FRONTEND_IMAGE='${FRONTEND_IMAGE,,}'
+            docker compose pull --quiet --ignore-buildable
+            docker compose up -d --no-build --remove-orphans
+            docker logout ghcr.io
+          "

package/templates/base/AGENTS.md

@@ -0,0 +1,78 @@
+# {{project_name}}: guide for AI agents
+
+A website built with DjangoStack: a Django backend (Django Headless serves
+the content API, Django Content Studio is the admin) and an Astro frontend
+that renders the content, run with Docker Compose.
+
+## Layout
+
+```
+backend/                 Django project
+  config/settings.py     settings; environment-driven ones come from django_stack.settings.configure
+  config/studio.py       the Content Studio site (admin extensions)
+  content/models.py      the content models: Page, Post, Category, Tag, Author, Menu, SiteSettings, Redirect, FormSubmission
+  content/blocks.py      the blocks of page and post bodies
+  content/admin.py       how each model looks in the admin (studios)
+  content/seed.py        demo content
+  content/tests/         pytest tests of the API
+frontend/                Astro site (server output, Node adapter)
+  src/pages/             routes: /, /[...slug], /blog, /blog/[slug], /category/[slug], /tag/[slug], sitemap.xml, rss.xml, robots.txt, /preview, /revalidate
+  src/components/        Blocks.astro maps block types to components in components/blocks/
+  src/lib/api.ts         getContent(): content helpers with the read-only key, drafts in preview
+  src/lib/headless.ts    generated API types; do not edit, run `npm run generate:types`
+  src/middleware.ts      page cache, editor-managed redirects, security headers
+compose.yaml             every service; COMPOSE_PROFILES in .env picks dev or prod
+Caddyfile                the prod profile's reverse proxy and HTTPS
+.github/workflows/deploy.yml  optional deploy to a server over SSH
+.env                     secrets and settings; never commit, never print
+```
+
+## Commands
+
+Run them at the project root. They need Docker; Node is only needed for the `npm run` shortcuts.
+
+| Task | Command |
+|------|---------|
+| Start everything | `docker compose up --build` (or `npm run dev`) |
+| Run a manage.py command | `docker compose exec backend python manage.py <command>` (or `npm run backend -- <command>`) |
+| Make migrations after a model change | `docker compose exec backend python manage.py makemigrations` |
+| Regenerate the API types after a model change | `npm run generate:types` |
+| Run the tests | `npm test` |
+| Lint and type-check | `npm run lint` |
+| Logs | `docker compose logs --follow backend` |
+| 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
+read-only, so a change goes through the code and a new image, never an edit
+in a running container.
+
+## How to add a content model
+
+1. Define the model in `backend/content/models.py` and decorate it with
+   `@expose()` (add `read_only=True` for content the frontend only reads).
+2. Register it in `backend/content/admin.py` with `@register(Model)` and a
+   `ModelStudio`.
+3. Run `makemigrations`; the backend migrates on its next start, or run
+   `migrate`.
+4. Run `npm run generate:types`, then read it in the frontend through
+   `getClient()` from `src/lib/api.ts`: `getClient(Astro.cookies).model("content.mymodel").list()`.
+5. Add an API smoke test to `backend/content/tests/test_api.py`.
+
+## How to add a block type
+
+1. Add a `Block` subclass in `backend/content/blocks.py` and add it to
+   `BODY_BLOCKS`. Blocks need no migration.
+2. Add a component in `frontend/src/components/blocks/` and map the block's
+   type in `frontend/src/components/Blocks.astro`.
+
+## Rules
+
+- Never edit `.env` values you were not asked to change, and never print secrets.
+- Never write migrations by hand; use `makemigrations`.
+- The frontend only ever holds `API_READ_KEY`. Never give it `API_SECRET_KEY`.
+- API routes are closed by default. Opening a model to anonymous writes goes
+  through `DJANGO_STACK["PUBLIC_CREATE"]` in `config/settings.py`, and is
+  rate limited.
+- Django owns `/admin`, `/api`, `/media` and `/static`; frontend routes must
+  not use these prefixes.

package/templates/base/CLAUDE.md

@@ -0,0 +1 @@
+Read [AGENTS.md](AGENTS.md): it describes this project's layout, its commands and what not to touch.

package/templates/base/Caddyfile

@@ -0,0 +1,51 @@
+# {{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
+# gets and renews the HTTPS certificate for SITE_URL by itself.
+#
+# Behind a platform's proxy (Coolify, Dokploy), CADDY_ADDRESS=:80 serves
+# plain HTTP to that proxy, and TRUSTED_PROXIES=private_ranges keeps the
+# client's address and scheme it forwards. See the deployment docs.
+
+{
+	servers {
+		trusted_proxies static {$TRUSTED_PROXIES}
+	}
+}
+
+{$CADDY_ADDRESS} {
+	encode zstd gzip
+
+	# Defaults for every response; Django and the frontend set their own,
+	# stricter ones where they need them. One directive per header: Caddy
+	# skips a whole block of `?` headers when any one of them is set.
+	header ?Strict-Transport-Security "max-age=31536000"
+	header ?X-Content-Type-Options "nosniff"
+	header ?Referrer-Policy "strict-origin-when-cross-origin"
+	header ?X-Frame-Options "DENY"
+	header -Server
+
+	# Uploads, when media is stored on the server instead of S3. No scripts
+	# run from uploaded files, whatever their type.
+	handle_path /media/* {
+		root * /srv/media
+		header Content-Security-Policy "script-src 'none'; object-src 'none'"
+		header Cache-Control "public, max-age=604800"
+		file_server
+	}
+
+	@django path /admin /admin/* /api /api/* /static/*
+	handle @django {
+		reverse_proxy backend:8000
+	}
+
+	handle {
+		reverse_proxy frontend:3000
+	}
+
+	log {
+		output stdout
+		format console
+	}
+}

package/templates/base/README.md

@@ -0,0 +1,87 @@
+# {{project_name}}
+
+A website with a Django backend and an Astro frontend, created with
+[DjangoStack](https://github.com/dwarsbit/django-stack).
+
+- [Django Headless](https://djangoheadless.org) serves the content API.
+- [Django Content Studio](https://djangocontentstudio.org) is the admin.
+- [Astro](https://astro.build) renders the site.
+- Postgres stores the content; Valkey is the cache and task queue.
+
+## Start
+
+You need Docker.
+
+```bash
+docker compose up --build
+```
+
+- Site: http://localhost:3000
+- Admin: http://localhost:3000/admin/ (user `admin`, password `ADMIN_PASSWORD` in `.env`)
+- Outgoing mail: http://localhost:8025
+
+The first start migrates the database, creates the admin user and adds demo
+content. Edit a page in the admin, publish, and reload the site.
+
+## Develop
+
+Both sides reload on save: the backend runs Django's development server and
+the frontend Astro's, with the source mounted from `backend/` and
+`frontend/`. `AGENTS.md` lists the layout and the commands.
+
+| Task | Command |
+|------|---------|
+| Run a manage.py command | `docker compose exec backend python manage.py <command>` |
+| Make migrations | `docker compose exec backend python manage.py makemigrations` |
+| Regenerate the API types | `npm run generate:types` |
+| Run the tests | `npm test` |
+| Check the setup | `npm run doctor` |
+
+With the `dstack` command installed (`npm install --global @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).
+
+## Preview and publishing
+
+Pages and posts have a status. Drafts and posts with a future publish date
+are not served by the API. The **Preview** button in the admin opens the
+site with drafts shown, for an hour.
+
+When an editor saves, Django tells the frontend (`REVALIDATE_URL`), which
+empties its page cache, so the change shows on the next visit.
+
+## Deploy
+
+On a server with Docker and a domain pointing at it:
+
+```bash
+npx @django-stack/cli production --domain example.com --email-url smtp+tls://user:pass@smtp.example.com:587
+# copy the project to the server, with .env.production as .env, then there:
+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)
+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>` |
+| Logs | `docker compose logs --follow backend-prod` |
+
+## Security
+
+- The API answers only requests with a key. The frontend holds the
+  read-only key (`API_READ_KEY`) and uses it on the server only.
+- `API_SECRET_KEY` can write: keep it for scripts and never give it to the
+  frontend.
+- `.env` holds every secret. It is generated with random values and is not
+  committed.
+
+See `SECURITY.md` to report a problem.

package/templates/base/SECURITY.md

@@ -0,0 +1,12 @@
+# Security
+
+To report a security problem in this site, contact its maintainers
+privately.
+
+Problems in the packages it is built on go to their projects:
+
+- DjangoStack: https://github.com/dwarsbit/django-stack/security
+- Django Headless: https://github.com/dwarsbit/django-headless/security
+- Django Content Studio: https://github.com/dwarsbit/django-content-studio/security
+- Django: https://www.djangoproject.com/security/
+- Astro: https://github.com/withastro/astro/security