build-wagtail 0.1.0__tar.gz

build_wagtail-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: build-wagtail
+Version: 0.1.0
+Summary: Dockerise a Wagtail project in place with one command.
+Keywords: wagtail,django,docker,deployment
+Author: Kailash Nadh
+Author-email: Kailash Nadh <kailash@nadh.in>
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Wagtail
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Installation/Setup
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# build-wagtail
+
+Dockerise a Wagtail project in place with one command. It generates a
+Dockerfile, settings overrides and a `compose.yml`, copies the site's database
+and media into `./data`, and builds the image. The app runs on
+[granian](https://github.com/emmett-framework/granian).
+
+Needs Docker with the compose plugin. The tool itself has no dependencies.
+
+## Install
+
+```shell
+uv tool install build-wagtail   # or: pipx install build-wagtail
+```
+
+## Usage
+
+Run it from the Wagtail project root (where `manage.py` is):
+
+```shell
+build-wagtail example.org,www.example.org
+docker compose up -d
+docker compose exec web python manage.py createsuperuser
+```
+
+The first hostname is canonical. The site is served on `127.0.0.1:8000`; put a
+reverse proxy in front of it for TLS. By default the host's proxy is expected to
+serve `/static` and `/media` from `./data`, and the tool prints an example Caddy
+config for that. With `--caddy`, a Caddy container serves them instead.
+
+| Option            | Default                                         |                                                    |
+|-------------------|-------------------------------------------------|----------------------------------------------------|
+| `--port`          | `8000`                                          | Localhost port the site is served on               |
+| `--caddy`         | off                                             | Run Caddy in a container for static/media          |
+| `--workers`       | `3`                                             | granian workers                                    |
+| `--python`        | `.python-version`, else `3.13`                  | Python version of the image                        |
+| `--settings`      | from `manage.py`, or `<project>.settings.production` | Settings module to build on                   |
+| `--no-build`      | off                                             | Write the files but skip `docker compose build`    |
+
+The project needs a `uv.lock`, `pyproject.toml` or `requirements.txt`.
+
+## What it writes
+
+- `.env`: secret key, hostnames and the container user. Created once, never overwritten.
+- `data/`: the live database, media and collected static files. Seeded once, never overwritten. Back it up.
+- `.wagtail-docker/` and `compose.yml`: regenerated on every run. Options aren't
+  stored, so pass the same ones each time.

build_wagtail-0.1.0/README.md

@@ -0,0 +1,47 @@
+# build-wagtail
+
+Dockerise a Wagtail project in place with one command. It generates a
+Dockerfile, settings overrides and a `compose.yml`, copies the site's database
+and media into `./data`, and builds the image. The app runs on
+[granian](https://github.com/emmett-framework/granian).
+
+Needs Docker with the compose plugin. The tool itself has no dependencies.
+
+## Install
+
+```shell
+uv tool install build-wagtail   # or: pipx install build-wagtail
+```
+
+## Usage
+
+Run it from the Wagtail project root (where `manage.py` is):
+
+```shell
+build-wagtail example.org,www.example.org
+docker compose up -d
+docker compose exec web python manage.py createsuperuser
+```
+
+The first hostname is canonical. The site is served on `127.0.0.1:8000`; put a
+reverse proxy in front of it for TLS. By default the host's proxy is expected to
+serve `/static` and `/media` from `./data`, and the tool prints an example Caddy
+config for that. With `--caddy`, a Caddy container serves them instead.
+
+| Option            | Default                                         |                                                    |
+|-------------------|-------------------------------------------------|----------------------------------------------------|
+| `--port`          | `8000`                                          | Localhost port the site is served on               |
+| `--caddy`         | off                                             | Run Caddy in a container for static/media          |
+| `--workers`       | `3`                                             | granian workers                                    |
+| `--python`        | `.python-version`, else `3.13`                  | Python version of the image                        |
+| `--settings`      | from `manage.py`, or `<project>.settings.production` | Settings module to build on                   |
+| `--no-build`      | off                                             | Write the files but skip `docker compose build`    |
+
+The project needs a `uv.lock`, `pyproject.toml` or `requirements.txt`.
+
+## What it writes
+
+- `.env`: secret key, hostnames and the container user. Created once, never overwritten.
+- `data/`: the live database, media and collected static files. Seeded once, never overwritten. Back it up.
+- `.wagtail-docker/` and `compose.yml`: regenerated on every run. Options aren't
+  stored, so pass the same ones each time.

build_wagtail-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "build-wagtail"
+version = "0.1.0"
+description = "Dockerise a Wagtail project in place with one command."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+keywords = [
+    "wagtail",
+    "django",
+    "docker",
+    "deployment",
+]
+classifiers = [
+    "Environment :: Console",
+    "Framework :: Django",
+    "Framework :: Wagtail",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Installation/Setup",
+]
+
+[[project.authors]]
+name = "Kailash Nadh"
+email = "kailash@nadh.in"
+
+[project.scripts]
+build-wagtail = "build_wagtail:main"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.14"]
+build-backend = "uv_build"

build_wagtail-0.1.0/pyproject.toml.orig

@@ -0,0 +1,23 @@
+[project]
+name = "build-wagtail"
+version = "0.1.0"
+description = "Dockerise a Wagtail project in place with one command."
+readme = "README.md"
+authors = [{ name = "Kailash Nadh", email = "kailash@nadh.in" }]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["wagtail", "django", "docker", "deployment"]
+classifiers = [
+    "Environment :: Console",
+    "Framework :: Django",
+    "Framework :: Wagtail",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Installation/Setup",
+]
+
+[project.scripts]
+build-wagtail = "build_wagtail:main"
+
+[build-system]
+requires = ["uv_build>=0.8,<0.14"]
+build-backend = "uv_build"

build_wagtail-0.1.0/src/build_wagtail/__init__.py

@@ -0,0 +1,396 @@
+"""Dockerise a Wagtail project in place.
+
+Run it from the project root (where manage.py is). It writes .wagtail-docker/,
+compose.yml and .env, copies the site's data into ./data, and builds the image.
+After that, use `docker compose up -d` and `docker compose down`.
+
+  build-wagtail example.org,www.example.org
+  build-wagtail example.org --port 8001 --workers 4 --caddy
+
+By default, only the app server runs in Docker, on 127.0.0.1:PORT, and the
+host's reverse proxy serves /static and /media straight from ./data. With
+--caddy, a Caddy container serves them and proxies the rest to the app.
+
+Re-running is safe: .env and data/ are never overwritten, generated files are.
+Hostnames are only needed on the first run, and update .env when given later.
+The other options aren't stored, so pass the same ones on every run.
+Needs only the Python standard library.
+"""
+
+import argparse
+import os
+import re
+import secrets
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+MARKER = "# Generated by build-wagtail"
+
+# Files and directories in the project, relative to its root.
+MANAGE_PY = Path("manage.py")
+PYTHON_VERSION_FILE = Path(".python-version")
+DB_FILE = "db.sqlite3"
+MEDIA_DIR = "media"
+STATIC_DIR = "static"
+
+# What this script writes into the project.
+GEN = Path(".wagtail-docker")
+ENV_FILE = Path(".env")
+COMPOSE_FILE = Path("compose.yml")
+DATA_DIR = Path("data")
+
+# Paths and names inside the containers.
+APP_DIR = "/app"
+CONTAINER_DATA_DIR = "/data"
+CADDY_STATIC_DIR = "/srv/static"
+CADDY_MEDIA_DIR = "/srv/media"
+APP_PORT = 8000
+SETTINGS_MODULE = "wagtail_docker_settings"
+
+UV_IMAGE = "ghcr.io/astral-sh/uv:python{python}-bookworm-slim"
+CADDY_IMAGE = "caddy:2.10-alpine"
+
+DEFAULT_PORT = 8000
+DEFAULT_WORKERS = 3
+DEFAULT_PYTHON = "3.13"
+
+# Containers shouldn't run as root. Used instead when the script is run by root.
+FALLBACK_UID = FALLBACK_GID = 1000
+
+# Dependency files, in order of preference, and the Dockerfile lines to install from each.
+DEP_INSTALLERS = [
+    ("uv.lock", "COPY pyproject.toml uv.lock ./\nRUN uv sync --frozen --no-dev --no-install-project"),
+    ("pyproject.toml", "COPY pyproject.toml ./\nRUN uv sync --no-dev --no-install-project"),
+    ("requirements.txt", "COPY requirements.txt ./\nRUN uv venv && uv pip install -r requirements.txt"),
+]
+
+
+def die(msg):
+    sys.exit(f"error: {msg}")
+
+
+def parse_args():
+    p = argparse.ArgumentParser(description="Dockerise a Wagtail project in place. Run from the project root.")
+    p.add_argument("hosts", nargs="?",
+                   help="comma-separated hostnames, the first one canonical. Required on the first run.")
+    p.add_argument("--port", type=int, default=DEFAULT_PORT, help="localhost port the site is served on (default: %(default)s)")
+    p.add_argument("--caddy", action="store_true",
+                   help="run Caddy in a container to serve /static and /media and proxy the app")
+    p.add_argument("--workers", type=int, default=DEFAULT_WORKERS, help="granian workers (default: %(default)s)")
+    p.add_argument("--python", help=f"Python version (default: {PYTHON_VERSION_FILE}, else {DEFAULT_PYTHON})")
+    p.add_argument("--settings",
+                   help="settings module to build on (default: from manage.py, or <project>.settings.production)")
+    p.add_argument("--no-build", action="store_true", help="write the files but don't run docker compose build")
+    args = p.parse_args()
+
+    if not 0 < args.port < 65536:
+        p.error("--port must be between 1 and 65535.")
+    if args.workers < 1:
+        p.error("--workers must be at least 1.")
+    return args
+
+
+def find_settings(override):
+    """Return (project package, settings module to build on)."""
+    m = re.search(r"""DJANGO_SETTINGS_MODULE["'],\s*["']([^"']+)["']""", MANAGE_PY.read_text())
+    if not m:
+        die(f"couldn't find DJANGO_SETTINGS_MODULE in {MANAGE_PY}.")
+
+    settings = m.group(1)
+    project = settings.split(".")[0]
+    if not Path(project, "wsgi.py").is_file():
+        die(f"{project}/wsgi.py not found.")
+
+    if override:
+        return project, override
+    if Path(project, "settings", "production.py").is_file():
+        settings = f"{project}.settings.production"
+    return project, settings
+
+
+def find_python(override):
+    if override:
+        return override
+    if PYTHON_VERSION_FILE.is_file():
+        return PYTHON_VERSION_FILE.read_text().split()[0]
+    return DEFAULT_PYTHON
+
+
+def deps_step():
+    """Return the Dockerfile lines that install the project's dependencies."""
+    for name, step in DEP_INSTALLERS:
+        if Path(name).is_file():
+            return step
+    die(f"none of {', '.join(n for n, _ in DEP_INSTALLERS)} found.")
+
+
+def read_env():
+    env = {}
+    for line in ENV_FILE.read_text().splitlines():
+        if "=" in line and not line.lstrip().startswith("#"):
+            k, v = line.split("=", 1)
+            env[k.strip()] = v.strip()
+    return env
+
+
+def create_env(hosts):
+    if os.getuid() == 0:
+        uid, gid = FALLBACK_UID, FALLBACK_GID
+    else:
+        uid, gid = os.getuid(), os.getgid()
+
+    body = (
+        f"DJANGO_SECRET_KEY={secrets.token_urlsafe(50)}\n"
+        "# Comma-separated. The first one is canonical.\n"
+        f"DJANGO_ALLOWED_HOSTS={hosts}\n"
+        f"PUID={uid}\n"
+        f"PGID={gid}\n"
+    )
+    fd = os.open(ENV_FILE, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(body)
+    print(f"Created {ENV_FILE}")
+
+
+def update_env_hosts(hosts):
+    text = ENV_FILE.read_text()
+    new, n = re.subn(r"(?m)^DJANGO_ALLOWED_HOSTS=.*$", lambda _: f"DJANGO_ALLOWED_HOSTS={hosts}", text)
+    if n == 0:
+        new = text.rstrip("\n") + f"\nDJANGO_ALLOWED_HOSTS={hosts}\n"
+    if new != text:
+        ENV_FILE.write_text(new)
+        print(f"Updated DJANGO_ALLOWED_HOSTS in {ENV_FILE}")
+
+
+def setup_data(uid, gid):
+    """Seed the data dir from the project's db and media on the first run."""
+    (DATA_DIR / STATIC_DIR).mkdir(parents=True, exist_ok=True)
+
+    if not (DATA_DIR / DB_FILE).exists() and Path(DB_FILE).is_file():
+        shutil.copy2(DB_FILE, DATA_DIR / DB_FILE)
+        print(f"Copied {DB_FILE} to {DATA_DIR / DB_FILE}")
+
+    if not (DATA_DIR / MEDIA_DIR).exists():
+        if Path(MEDIA_DIR).is_dir():
+            shutil.copytree(MEDIA_DIR, DATA_DIR / MEDIA_DIR, symlinks=True)
+            print(f"Copied {MEDIA_DIR}/ to {DATA_DIR / MEDIA_DIR}/")
+        else:
+            (DATA_DIR / MEDIA_DIR).mkdir()
+
+    if os.getuid() == 0:
+        for p in [DATA_DIR, *DATA_DIR.rglob("*")]:
+            os.chown(p, uid, gid, follow_symlinks=False)
+
+
+def settings_py(settings):
+    return f'''{MARKER}. Docker overrides on top of the project's own settings.
+import os
+
+from {settings} import *  # noqa: F401,F403
+
+DEBUG = False
+SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
+
+ALLOWED_HOSTS = os.environ["DJANGO_ALLOWED_HOSTS"].split(",")
+CSRF_TRUSTED_ORIGINS = [f"https://{{h}}" for h in ALLOWED_HOSTS]
+WAGTAILADMIN_BASE_URL = f"https://{{ALLOWED_HOSTS[0]}}"
+
+# TLS is terminated by the reverse proxy in front.
+SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+
+if DATABASES["default"]["ENGINE"] == "django.db.backends.sqlite3":
+    DATABASES["default"]["NAME"] = "{CONTAINER_DATA_DIR}/{DB_FILE}"
+
+MEDIA_ROOT = "{CONTAINER_DATA_DIR}/{MEDIA_DIR}"
+STATIC_ROOT = "{CONTAINER_DATA_DIR}/{STATIC_DIR}"
+'''
+
+
+def dockerfile(python, deps, project, workers):
+    return f'''{MARKER}.
+FROM {UV_IMAGE.format(python=python)}
+
+WORKDIR {APP_DIR}
+ENV UV_COMPILE_BYTECODE=1 \\
+    PYTHONDONTWRITEBYTECODE=1 \\
+    PYTHONUNBUFFERED=1 \\
+    VIRTUAL_ENV={APP_DIR}/.venv \\
+    PATH="{APP_DIR}/.venv/bin:$PATH" \\
+    DJANGO_SETTINGS_MODULE={SETTINGS_MODULE}
+
+{deps}
+RUN python -c "import granian" 2>/dev/null || uv pip install granian
+
+COPY . .
+COPY {GEN}/settings.py {SETTINGS_MODULE}.py
+
+EXPOSE {APP_PORT}
+CMD ["sh", "-c", "python manage.py migrate --noinput && python manage.py collectstatic --noinput && exec granian --interface wsgi {project}.wsgi:application --host 0.0.0.0 --port {APP_PORT} --workers {workers}"]
+'''
+
+
+# BuildKit picks up <Dockerfile>.dockerignore next to the Dockerfile.
+DOCKERIGNORE = f"""\
+.git
+.venv
+**/__pycache__
+*.sqlite3
+*.sqlite3-*
+*.sqlite3.*
+{MEDIA_DIR}
+{STATIC_DIR}
+{DATA_DIR}
+backups
+node_modules
+{ENV_FILE}
+{COMPOSE_FILE}
+"""
+
+CADDYFILE = f"""{MARKER}.
+{{
+	admin off
+	# Pass through X-Forwarded-Proto from the host's reverse proxy.
+	servers {{
+		trusted_proxies static private_ranges
+	}}
+}}
+
+:80 {{
+	encode zstd gzip
+
+	handle_path /static/* {{
+		root * {CADDY_STATIC_DIR}
+		header Cache-Control "public, max-age=31536000, immutable"
+		file_server
+	}}
+	handle_path /media/* {{
+		root * {CADDY_MEDIA_DIR}
+		file_server
+	}}
+	handle {{
+		reverse_proxy web:{APP_PORT}
+	}}
+}}
+"""
+
+
+def compose(port, caddy):
+    # Localhost only: Docker-published ports bypass host firewalls.
+    ports = f"""    ports:
+      - "127.0.0.1:{port}:{{}}"
+"""
+    out = f"""{MARKER}. Re-run build-wagtail to change this file; secrets and hosts are in {ENV_FILE}.
+services:
+  web:
+    build:
+      context: .
+      dockerfile: {GEN}/Dockerfile
+    restart: unless-stopped
+    env_file: {ENV_FILE}
+    user: "${{PUID}}:${{PGID}}"
+    volumes:
+      - ./{DATA_DIR}:{CONTAINER_DATA_DIR}
+"""
+    if not caddy:
+        return out + ports.format(APP_PORT)
+
+    return out + f"""
+  # Serves /static and /media, proxies the rest to granian.
+  caddy:
+    image: {CADDY_IMAGE}
+    restart: unless-stopped
+    depends_on: [web]
+{ports.format(80)}    volumes:
+      - ./{GEN}/Caddyfile:/etc/caddy/Caddyfile:ro
+      - ./{DATA_DIR}/{STATIC_DIR}:{CADDY_STATIC_DIR}:ro
+      - ./{DATA_DIR}/{MEDIA_DIR}:{CADDY_MEDIA_DIR}:ro
+"""
+
+
+def proxy_example(host, port, caddy):
+    """Return an example host Caddy config for the site."""
+    if caddy:
+        return f"""  {host} {{
+      reverse_proxy 127.0.0.1:{port}
+  }}"""
+
+    data = DATA_DIR.resolve()
+    return f"""  {host} {{
+      encode zstd gzip
+
+      handle_path /static/* {{
+          root * {data / STATIC_DIR}
+          header Cache-Control "public, max-age=31536000, immutable"
+          file_server
+      }}
+      handle_path /media/* {{
+          root * {data / MEDIA_DIR}
+          file_server
+      }}
+      handle {{
+          reverse_proxy 127.0.0.1:{port}
+      }}
+  }}"""
+
+
+def write_files(args, project, settings, python, deps):
+    GEN.mkdir(exist_ok=True)
+    (GEN / "settings.py").write_text(settings_py(settings))
+    (GEN / "Dockerfile").write_text(dockerfile(python, deps, project, args.workers))
+    (GEN / "Dockerfile.dockerignore").write_text(DOCKERIGNORE)
+
+    if args.caddy:
+        (GEN / "Caddyfile").write_text(CADDYFILE)
+
+    COMPOSE_FILE.write_text(compose(args.port, args.caddy))
+    print(f"Wrote {COMPOSE_FILE} and {GEN}/ (project: {project}, settings: {settings}, "
+          f"python: {python}, caddy: {'yes' if args.caddy else 'no'})")
+
+
+def main():
+    args = parse_args()
+
+    if not MANAGE_PY.is_file():
+        die(f"{MANAGE_PY} not found. Run this from the Wagtail project root.")
+    if not args.no_build and subprocess.run(["docker", "compose", "version"], capture_output=True).returncode != 0:
+        die("docker compose is not available.")
+    if COMPOSE_FILE.exists() and not COMPOSE_FILE.read_text().startswith(MARKER):
+        die(f"{COMPOSE_FILE} exists and wasn't generated by this script. Move it aside first.")
+
+    project, settings = find_settings(args.settings)
+    python = find_python(args.python)
+    deps = deps_step()
+
+    if not ENV_FILE.exists():
+        if not args.hosts:
+            die("first run needs the site's hostnames, e.g. build-wagtail example.org,www.example.org")
+        create_env(args.hosts)
+    elif args.hosts:
+        update_env_hosts(args.hosts)
+    env = read_env()
+
+    setup_data(int(env["PUID"]), int(env["PGID"]))
+    write_files(args, project, settings, python, deps)
+
+    if not args.no_build and subprocess.run(["docker", "compose", "build"]).returncode != 0:
+        die("docker compose build failed.")
+
+    host = env["DJANGO_ALLOWED_HOSTS"].split(",")[0]
+    print(f"""
+Done. Start with:   docker compose up -d
+Stop with:          docker compose down
+Admin user:         docker compose exec web python manage.py createsuperuser
+
+The site is on 127.0.0.1:{args.port}. Point your reverse proxy at it for TLS, e.g. Caddy:
+
+{proxy_example(host, args.port, args.caddy)}
+
+{DATA_DIR}/ now holds the live database and media. Back it up.""")
+
+
+if __name__ == "__main__":
+    main()