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 <[email protected]>
2026-10-10 15:03:28 +02:00
commit 5caca05738
14 changed files with 425 additions and 0 deletions
@@ -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.