Vibecoded CI/CD

lean/README.md

@@ -25,6 +25,14 @@ docker build -t mathew-lean ./lean
 docker run --rm -p 8080:8080 mathew-lean
 ```
 
+The build is **multi-stage**: compilers, dev dependencies and build caches stay
+in the builder, and the pushed image is a slim runtime carrying only what
+sessions need — the node server, the elan toolchain, the built client, and
+Mathlib's precompiled cache (the bulk of it, ~7GB of olean files; total image
+~11GB). The upstream "Stable" demo project is dropped: it pinned a second
+~3GB toolchain, and the wiki only ever opens the default project
+(`MathlibDemo`).
+
 `GET http://localhost:8080/health` answers when the server is up — the image
 carries a `HEALTHCHECK` for it. The frontend finds the server at
 `NUXT_PUBLIC_LEAN_URL` (default `http://localhost:8080`, dev included), so out
@@ -38,6 +46,29 @@ docker build --build-arg LEAN4WEB_REF=v0.2.2 -t mathew-lean ./lean
 
 (any branch or tag; the clone is shallow, so commit SHAs are not offered.)
 
+## Keeping Mathlib out of the image
+
+Mathlib's compiled cache is what makes this image (and pushing it) heavy. If
+the registry or the CI runner chokes on it, build without Mathlib and let a
+volume hold it instead:
+
+```bash
+docker build --build-arg BAKE_MATHLIB=false -t mathew-lean ./lean   # ~4GB
+docker run --rm -p 8080:8080 -v lean-mathlib:/opt/lean4web/Projects/MathlibDemo/.lake mathew-lean
+```
+
+The `BAKE_MATHLIB=false` image still ships the pinned elan toolchain, but not
+the project's `.lake`: the entrypoint notices a fresh volume and fills it once
+at first start — `lake update` fetches the sources pinned in
+`lake-manifest.json`, Mathlib's post-update hook downloads the matching
+precompiled cache, `lake build` writes the project's own module. Expect ~10
+minutes and a few hundred MB of download; restarts after that are instant,
+and **image rebuilds never touch Mathlib again** (the volume stays). The
+trade: the cache must survive on the host, first start needs network, and it
+redoes once if you recreate with a clean volume — hence the default staying
+`BAKE_MATHLIB=true`. The commented blocks in `docker-compose.yml` wire this
+up for the production stack.
+
 ## The protocol the wiki's client speaks
 
 The websocket endpoint is `/websocket/<project>` (project names come from
@@ -117,21 +148,27 @@ The image clones lean4web at build time, so a rebuild is an update:
 docker compose build --pull lean && docker compose up -d lean
 ```
 
-Rebuilding also re-runs `Projects/*/leanweb-build.sh` — the demo projects are
-rebuilt and Mathlib's cache re-fetched, so treat this like the heavy build it
-is (several GB of image; run it on the machine that hosts the editor).
+Rebuilding also re-runs the project build — Mathlib's pin moves with upstream
+and its cache re-downloads, so treat this like the heavy build it is (run it
+on the machine that hosts the editor; pin `LEAN4WEB_REF` for a build that
+stands still).
+
+CI follows the same split: `.gitea/workflows/deploy-lean.yml` rebuilds, pushes
+and redeploys the lean image **only when `lean/**` changes**; the regular
+deploy pipeline ignores `lean/**` entirely and just pulls whatever
+`mathew-lean:latest` the registry holds. (In volume mode the pushed image is
+~4GB and a lean rebuild doesn't fetch Mathlib at all.)
 
 ## Adding Lean projects
 
-Anything under `Projects/` of the *image source* becomes a selectable project
-(`#project=<name>`). To ship one with the image, build a custom image that
-copies it in before the project build step:
+Anything under `Projects/` of the *running image* becomes a selectable project
+(`#project=<name>`). To ship one with the image, add it in the Dockerfile's
+builder stage, before the project build step:
 
 ```dockerfile
-FROM mathew-lean AS base   # or edit lean/Dockerfile directly
+# in lean/Dockerfile, build stage, before the BAKE_MATHLIB step
 COPY MyProject /opt/lean4web/Projects/MyProject
-WORKDIR /opt/lean4web/Projects/MyProject
-RUN lake build
+RUN cd Projects/MyProject && lake build
 ```
 
 See upstream's [Adding Projects](https://github.com/leanprover-community/lean4web/blob/main/doc/Projects.md)