commit 5caca05738cd2eb33ad26935378cd3766d3991ab Author: Carl Vargklint Date: Sat Oct 10 15:03:28 2026 +0200 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 diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..a7b7c69 --- /dev/null +++ b/.env.example @@ -0,0 +1,4 @@ +HOST_UID=1000 +HOST_GID=1000 +WEB_PORT=8150 +BIND_ADDR=0.0.0.0 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7c68250 --- /dev/null +++ b/.gitignore @@ -0,0 +1,7 @@ +# local config and generated output +.env +site-build/ + +# editor / OS +.DS_Store +.vscode/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..c8eeca9 --- /dev/null +++ b/.gitmodules @@ -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 diff --git a/50ohm b/50ohm new file mode 160000 index 0000000..874838f --- /dev/null +++ b/50ohm @@ -0,0 +1 @@ +Subproject commit 874838f5257f4135cd115cc35d0e18d915511939 diff --git a/50ohm-ansible b/50ohm-ansible new file mode 160000 index 0000000..691d60f --- /dev/null +++ b/50ohm-ansible @@ -0,0 +1 @@ +Subproject commit 691d60f1cda537807326e264373acecdb8d1dd96 diff --git a/50ohm-contents-dl b/50ohm-contents-dl new file mode 160000 index 0000000..f7fa8cf --- /dev/null +++ b/50ohm-contents-dl @@ -0,0 +1 @@ +Subproject commit f7fa8cfbc1188553d6e38d9321eabf7c2984ba94 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..7918d7a --- /dev/null +++ b/Makefile @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..bc190ce --- /dev/null +++ b/README.md @@ -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. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..66fe866 --- /dev/null +++ b/docker-compose.yml @@ -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: diff --git a/docker/builder/Dockerfile b/docker/builder/Dockerfile new file mode 100644 index 0000000..41fb34e --- /dev/null +++ b/docker/builder/Dockerfile @@ -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"] diff --git a/docker/latex/Dockerfile b/docker/latex/Dockerfile new file mode 100644 index 0000000..ba3656c --- /dev/null +++ b/docker/latex/Dockerfile @@ -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"] diff --git a/docker/latex/build_drawings.py b/docker/latex/build_drawings.py new file mode 100644 index 0000000..ac665f0 --- /dev/null +++ b/docker/latex/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/.svg from contents/drawings/.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()) diff --git a/docker/web/default.conf b/docker/web/default.conf new file mode 100644 index 0000000..da03727 --- /dev/null +++ b/docker/web/default.conf @@ -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; + } +} diff --git a/scripts/fetch.sh b/scripts/fetch.sh new file mode 100755 index 0000000..acd946c --- /dev/null +++ b/scripts/fetch.sh @@ -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"