Add local Docker deployment and submodules

- docker-compose.yml: builder, nginx web server and a LaTeX container (profile "latex") for regenerating the SVG drawings - Makefile, scripts/fetch.sh, .env.example - 50ohm, 50ohm-contents-dl and 50ohm-ansible as submodules tracking branch sv Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-10 15:03:28 +02:00
commit 5caca05738
14 changed files with 425 additions and 0 deletions
@@ -0,0 +1,4 @@
+HOST_UID=1000
+HOST_GID=1000
+WEB_PORT=8150
+BIND_ADDR=0.0.0.0
@@ -0,0 +1,7 @@
+# local config and generated output
+.env
+site-build/
+
+# editor / OS
+.DS_Store
+.vscode/
@@ -0,0 +1,12 @@
+[submodule "50ohm"]
+	path = 50ohm
+	url = https://git.nyaaa.net/Superminaren/50ohm.git
+	branch = sv
+[submodule "50ohm-contents-dl"]
+	path = 50ohm-contents-dl
+	url = https://git.nyaaa.net/Superminaren/50ohm-contents-dl.git
+	branch = sv
+[submodule "50ohm-ansible"]
+	path = 50ohm-ansible
+	url = https://git.nyaaa.net/Superminaren/50ohm-ansible.git
+	branch = sv
@@ -0,0 +1,47 @@
+-include .env
+export
+
+COMPOSE = docker compose
+
+.PHONY: help fetch build up down logs rebuild drawings drawings-all drawings-one shell-latex remotes
+
+help:
+	@echo "make fetch          init/update the submodules (scripts/fetch.sh)"
+	@echo "make build          generate the site into ./site-build"
+	@echo "make up | down      start/stop the local web server (http://127.0.0.1:8080)"
+	@echo "make rebuild        build, then (re)start the web server"
+	@echo "make drawings       regenerate drawings whose .tex is newer than the .svg (JOBS=4)"
+	@echo "make drawings-all   regenerate every drawing"
+	@echo "make drawings-one ID=502"
+	@echo "make remotes        show git remotes of the three repos"
+
+fetch:
+	./scripts/fetch.sh
+
+build:
+	$(COMPOSE) --profile build run --rm build
+
+up:
+	$(COMPOSE) up -d web
+	@echo "http://$(BIND_ADDR):$(WEB_PORT)"
+
+down:
+	$(COMPOSE) down
+
+logs:
+	$(COMPOSE) logs -f web
+
+rebuild: build up
+
+JOBS ?= 4
+drawings:
+	$(COMPOSE) --profile latex run --rm latex --stale -j $(JOBS)
+
+drawings-all:
+	$(COMPOSE) --profile latex run --rm latex --all -j $(JOBS)
+
+drawings-one:
+	$(COMPOSE) --profile latex run --rm latex $(ID)
+
+remotes:
+	@for r in 50ohm 50ohm-contents-dl 50ohm-ansible; do echo "== $$r ($$(git -C $$r branch --show-current))"; git -C $$r remote -v; done
@@ -0,0 +1,68 @@
+# 50ohm.se – local workspace
+
+Three git repos live here as submodules (branch `sv` in each; the German DARC originals are on `main`):
+
+| dir | what | licence |
+|---|---|---|
+| `50ohm/` | static-site generator (Python) | AGPL |
+| `50ohm-contents-dl/` | Swedish course content, drawings, TikZ sources | CC BY 4.0 |
+| `50ohm-ansible/` | playbook for deploying to a Debian server | – |
+
+Everything else in this folder (`docker-compose.yml`, `docker/`, `Makefile`, `.env`, `site-build/`) is the deployment tooling of the `50ohm-deploy` repo (`.env` and `site-build/` are git-ignored).
+
+## Local deploy
+
+```console
+$ make build      # generate the site -> ./site-build   (about 15 s)
+$ make up         # serve it on http://127.0.0.1:8150   (port: WEB_PORT in .env)
+$ make down
+```
+
+The repos are bind-mounted, not copied into images: edit a template, section or toc file, run `make build`, reload the browser (nginx sends `no-store`). The builder container runs as your user (`HOST_UID`/`HOST_GID` in `.env`), so no root-owned files end up in the repos. `site-build/` is outside all repos.
+
+## Drawings (LaTeX)
+
+The SVGs in `50ohm-contents-dl/contents/drawings/` are generated from the `.tex` files next to them (LuaLaTeX + CircuiTikZ -> PDF -> `pdftocairo`). No TeX install is needed on the host:
+
+```console
+$ make drawings                # rebuild every drawing whose .tex is newer than its .svg  (JOBS=4)
+$ make drawings-one ID=502     # one drawing
+$ make drawings-all            # everything (slow)
+```
+
+The first `docker compose --profile latex build latex` downloads TeX Live (a few GB, ~5 min). Each drawing keeps its existing width (read from the current SVG). Regenerated SVGs show up as modified files in `50ohm-contents-dl` – commit them with the matching `.tex`.
+
+## Git layout
+
+This folder is the `50ohm-deploy` repo; the three repos are **submodules** tracking branch `sv`:
+
+```
+50ohm-deploy  (docker-compose.yml, docker/, Makefile, scripts/)
+├── 50ohm/                generator
+├── 50ohm-contents-dl/    content
+└── 50ohm-ansible/        server playbook
+```
+
+Fresh machine:
+
+```console
+$ git clone https://git.nyaaa.net/Superminaren/50ohm-deploy.git && cd 50ohm-deploy
+$ scripts/fetch.sh        # init submodules, check out sv, add the DARC "upstream" remotes, create .env
+$ make build && make up
+```
+
+`scripts/fetch.sh --pinned` checks out exactly the commits recorded in this repo instead of the tip of `sv`.
+
+**Pushing.** A submodule records a commit hash, so commit and push inside the submodule first, then record the new hash in the parent. `push.recurseSubmodules=on-demand` is set, so from the parent:
+
+```console
+$ git -C 50ohm-contents-dl commit -am "..."        # work happens in the submodule
+$ git add 50ohm-contents-dl && git commit -m "Update content"
+$ git push                                         # pushes the submodule commits first, then this repo
+```
+
+`upstream` (the original DARC repos, local-only) lets you pull their changes: `git -C 50ohm fetch upstream`. `make remotes` lists all remotes. Nothing from the Docker setup lands in the submodules except regenerated `drawings/*.svg`; build leftovers are in each repo's `.gitignore`.
+
+## Deploying to a server
+
+See `50ohm-ansible/README.md`. `vars.yml` needs `site_admin_email` and your two repo URLs before `site.yml` will run.
@@ -0,0 +1,53 @@
+# Local deploy of the Swedish 50ohm site.
+#
+#   make build     generate the static site  (./50ohm + ./50ohm-contents-dl  ->  ./site-build)
+#   make up        serve it on http://127.0.0.1:8080
+#   make drawings  regenerate stale SVG drawings from their .tex sources (profile "latex")
+#
+# The repos are bind-mounted, never copied: nothing the containers do ends up in git except
+# regenerated drawings/*.svg in the content repo (which you do want to commit).
+# Containers run as your user (HOST_UID/HOST_GID) so no root-owned files appear in the repos.
+
+x-user: &user "${HOST_UID:-1000}:${HOST_GID:-1000}"
+
+services:
+  build:
+    build:
+      context: ./docker/builder
+      additional_contexts:
+        src: ./50ohm
+    image: 50ohm-se-builder
+    user: *user
+    volumes:
+      - ./50ohm:/app:ro
+      - ./50ohm-contents-dl:/content:ro
+      - ./site-build:/out
+    profiles: ["build"]
+
+  web:
+    image: nginx:1.27-alpine
+    ports:
+      - "${BIND_ADDR:-127.0.0.1}:${WEB_PORT:-8080}:80"
+    volumes:
+      - ./site-build:/usr/share/nginx/html:ro
+      - ./docker/web/default.conf:/etc/nginx/conf.d/default.conf:ro
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/index.html"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+
+  latex:
+    build:
+      context: ./docker/latex
+    image: 50ohm-se-latex
+    user: *user
+    working_dir: /content
+    volumes:
+      - ./50ohm-contents-dl:/content
+      - texcache:/cache
+    profiles: ["latex"]
+
+volumes:
+  texcache:
@@ -0,0 +1,14 @@
+# Static-site generator for the Swedish 50ohm site.
+# The source is NOT copied into the image: compose bind-mounts ./50ohm at /app
+# so template/renderer edits take effect on the next `make build` without an image rebuild.
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1
+
+WORKDIR /app
+COPY --from=src requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt
+
+ENTRYPOINT ["python", "main.py"]
+CMD ["-i", "/content", "-o", "/out"]
@@ -0,0 +1,34 @@
+# TeX Live (LuaLaTeX + TikZ/CircuiTikZ) + pdftocairo, used to regenerate the SVG drawings
+# from contents/drawings/*.tex in the content repo.
+FROM debian:trixie-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    HOME=/cache \
+    TEXMFVAR=/cache/texmf-var \
+    TEXMFCACHE=/cache/texmf-var \
+    OSFONTDIR=/usr/share/fonts
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        fontconfig \
+        fonts-linuxlibertine \
+        latexmk \
+        poppler-utils \
+        python3 \
+        texlive-fonts-extra \
+        texlive-fonts-recommended \
+        texlive-lang-european \
+        texlive-lang-german \
+        texlive-latex-base \
+        texlive-latex-extra \
+        texlive-latex-recommended \
+        texlive-luatex \
+        texlive-pictures \
+        texlive-plain-generic \
+        texlive-science \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p /cache && chmod 777 /cache
+
+COPY build_drawings.py /usr/local/bin/build_drawings.py
+WORKDIR /content
+ENTRYPOINT ["python3", "/usr/local/bin/build_drawings.py"]
@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""Non-interactive replacement for the content repo's src/build_drawings.py.
+
+Rebuilds contents/drawings/<id>.svg from contents/drawings/<id>.tex
+(LuaLaTeX -> PDF -> pdftocairo -> SVG), run from the content repo root.
+
+  build_drawings.py 502 503        build specific drawings
+  build_drawings.py --stale        build drawings whose .tex is newer than the .svg
+  build_drawings.py --all          build every drawing
+  --preview DIR                    also write PNG previews into DIR (inside the container)
+  -j N                             run N builds in parallel
+
+Width: \\DARCimageOnly autoscales to a width in cm (default 9). To keep the size of the
+existing drawing, the width is derived from the current SVG (pt -> cm); override with --width.
+"""
+import argparse
+import os
+import pathlib
+import re
+import subprocess
+import sys
+import tempfile
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+DRAWINGS = pathlib.Path("contents/drawings")
+PHOTOS = pathlib.Path("contents/photos").resolve()
+
+
+def width_from_svg(svg: pathlib.Path) -> float:
+    """Width in cm of an existing SVG; 9 cm (the repo default) if unknown or ~9 cm."""
+    try:
+        head = svg.read_text(encoding="utf-8", errors="ignore")[:600]
+        # poppler <= 22 writes "42.872pt", newer versions a bare number (same unit: pt)
+        pt = float(re.search(r'width="([\d.]+)(?:pt)?"', head).group(1))
+    except (OSError, AttributeError, ValueError):
+        return 9.0
+    cm = pt * 2.54 / 72
+    if 8.85 <= cm <= 9.15:
+        return 9.0
+    return round(cm, 1)  # round (not ceil): stable when a drawing is rebuilt repeatedly
+
+
+def build_drawing(drawing_id: str, width: float | None, preview: pathlib.Path | None = None) -> tuple[str, bool, str]:
+    tex = DRAWINGS / f"{drawing_id}.tex"
+    svg = DRAWINGS / f"{drawing_id}.svg"
+    if not tex.is_file():
+        return drawing_id, False, f"{tex} not found"
+    latex = tex.read_text(encoding="utf-8")
+    if "\\begin{document}" in latex or "\\begin{table}" in latex:
+        return drawing_id, False, "contains a document environment"
+    if width is None:
+        width = width_from_svg(svg)
+
+    with tempfile.TemporaryDirectory(prefix=f"build_{drawing_id}_", dir=".") as tmp:
+        build = pathlib.Path(tmp)
+        (build / "img").mkdir()
+        (build / "img" / f"{drawing_id}include.tex").write_text(latex, encoding="utf-8")
+        (build / f"{drawing_id}.tex").write_text(
+            f"\\documentclass{{FiftyOhm}}\\DARCimageOnly{{{width}cm}}{{{drawing_id}include}}", encoding="utf-8"
+        )
+        (build / "foto").symlink_to(PHOTOS)
+        (build / "img" / "foto").symlink_to(PHOTOS)
+
+        # Run from the repo root so latexmk picks up ./latexmkrc (TEXINPUTS for FiftyOhm.cls);
+        # its `$do_cd = 1` then runs LaTeX inside the build directory.
+        run = subprocess.run(
+            ["latexmk", "-lualatex", "-interaction=nonstopmode", "-halt-on-error", str(build / f"{drawing_id}.tex")],
+            stdin=subprocess.DEVNULL, capture_output=True, text=True,
+        )
+        pdf = build / f"{drawing_id}.pdf"
+        if run.returncode != 0 or not pdf.is_file():
+            log = (build / f"{drawing_id}.log")
+            tail = log.read_text(errors="ignore")[-1500:] if log.exists() else run.stdout[-1500:]
+            return drawing_id, False, "latexmk failed:\n" + tail
+
+        tmp_svg = build / f"{drawing_id}.svg"
+        conv = subprocess.run(["pdftocairo", "-svg", str(pdf), str(tmp_svg)], capture_output=True, text=True)
+        if conv.returncode != 0 or not tmp_svg.is_file():
+            return drawing_id, False, "pdftocairo failed: " + conv.stderr
+        if preview is not None:
+            preview.mkdir(parents=True, exist_ok=True)
+            subprocess.run(["pdftocairo", "-png", "-r", "130", "-singlefile", str(pdf), str(preview / drawing_id)], check=False)
+        os.replace(tmp_svg, svg)  # only replace the SVG once a new one exists
+    return drawing_id, True, f"{width} cm"
+
+
+def stale_ids() -> list[str]:
+    ids = []
+    for tex in sorted(DRAWINGS.glob("*.tex")):
+        svg = tex.with_suffix(".svg")
+        if not svg.exists() or tex.stat().st_mtime > svg.stat().st_mtime:
+            ids.append(tex.stem)
+    return ids
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("ids", nargs="*")
+    ap.add_argument("--stale", action="store_true")
+    ap.add_argument("--all", action="store_true")
+    ap.add_argument("--width", type=float, help="override width in cm")
+    ap.add_argument("--preview", type=pathlib.Path, help="also write a PNG preview of each drawing into this directory")
+    ap.add_argument("-j", "--jobs", type=int, default=1)
+    args = ap.parse_args()
+
+    if not DRAWINGS.is_dir():
+        print("Run from the content repo root (contents/drawings not found).", file=sys.stderr)
+        return 2
+    ids = list(args.ids)
+    if args.all:
+        ids = sorted(p.stem for p in DRAWINGS.glob("*.tex"))
+    elif args.stale:
+        ids = stale_ids()
+    if not ids:
+        print("Nothing to build.")
+        return 0
+
+    print(f"Building {len(ids)} drawing(s) with {args.jobs} job(s)")
+    failed = []
+    with ThreadPoolExecutor(max_workers=max(1, args.jobs)) as pool:
+        futures = [pool.submit(build_drawing, i, args.width, args.preview) for i in ids]
+        for n, fut in enumerate(as_completed(futures), 1):
+            drawing_id, ok, info = fut.result()
+            print(f"[{n}/{len(ids)}] {drawing_id}: {'ok ' + info if ok else 'FAILED ' + info}", flush=True)
+            if not ok:
+                failed.append(drawing_id)
+    if failed:
+        print(f"\n{len(failed)} failed: {' '.join(sorted(failed))}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -0,0 +1,13 @@
+server {
+    listen 80;
+    server_name _;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # Local deploy: never cache, so a rebuild is visible on reload.
+    add_header Cache-Control "no-store" always;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+}
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Fetch (or update) the three repos this deployment is built from.
+#
+#   scripts/fetch.sh            clone/init the submodules, check out and fast-forward branch "sv" in each
+#   scripts/fetch.sh --pinned   check out exactly the commits recorded in this repo (detached HEAD)
+#
+# Also adds the original DARC repos as the local-only remote "upstream", so upstream changes
+# can be pulled in with `git fetch upstream`.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+BRANCH=sv
+declare -A UPSTREAM=(
+  [50ohm]=https://github.com/DARC-e-V/50ohm.git
+  [50ohm-contents-dl]=https://github.com/DARC-e-V/50ohm-contents-dl.git
+  [50ohm-ansible]=https://github.com/DARC-e-V/50ohm-ansible.git
+)
+
+git submodule sync --quiet
+git submodule update --init
+
+for repo in "${!UPSTREAM[@]}"; do
+  if ! git -C "$repo" remote | grep -qx upstream; then
+    git -C "$repo" remote add upstream "${UPSTREAM[$repo]}"
+    echo "$repo: added remote upstream"
+  fi
+  if [[ "${1:-}" != "--pinned" ]]; then
+    git -C "$repo" fetch --quiet origin
+    git -C "$repo" checkout --quiet "$BRANCH"
+    git -C "$repo" merge --quiet --ff-only "origin/$BRANCH" || echo "$repo: $BRANCH has local commits, not fast-forwarded"
+  fi
+  echo "$repo: $(git -C "$repo" rev-parse --abbrev-ref HEAD) @ $(git -C "$repo" rev-parse --short HEAD)"
+done
+
+[[ -f .env ]] || { cp .env.example .env && echo "created .env from .env.example"; }
+echo "Done. Next: make build && make up"