Adding LaTeX user help

Serve LaTeX help pages from a MediaWiki site under /learn on a Kubernetes deployment.

The /learn pages are served by the web service (the learn module) of every Ayakaleaf Pro pod, from a cache of the wiki set in WIKI_URL. What the module does and which wikis work is described in Adding LaTeX user help.

Service	web (learn module), in every Ayakaleaf Pro pod
Pod → outside	WIKI_URL (default https://learnwiki.overleaf.com): every page at the first start, then a page again when a user opens it after WIKI_MAX_CACHE_AGE
Browser → outside	images of the pages, straight from WIKI_URL
Stored data	the page cache in /var/lib/overleaf/data/learnPages on the data volume
Periodic jobs	none: pages are refreshed when users open them

Configuration

30-config.yaml (additions)

  OVERLEAF_PROXY_LEARN: "true"
  # optional: your own MediaWiki
  # WIKI_URL: https://wiki.example.com

kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
kubectl -n overleaf rollout status deployment/overleaf --timeout=30m

At its first start with the module on, the web service downloads the whole wiki before it accepts requests, which takes several minutes. The pod stays not ready until then, so allow for it in rollout status --timeout and in any startup or liveness probe you add. Later starts reuse the cache on the data volume.

At the first start, before a cache exists, the pods must reach WIKI_URL: without it the web service fails while starting and is restarted inside the pod again and again, so the pod never becomes ready. Turn the module off, or allow the pods out to the wiki. Once the cache exists, the pods start and serve the cached pages also while the wiki cannot be reached.

Several replicas

Each replica keeps its own cache on its node’s disk, so each one downloads the wiki at its first start; with podManagementPolicy: OrderedReady they do it one after the other. A user may see a page in a slightly different version on another replica until it is refreshed there.

Tested on Kubernetes

On Kubernetes 1.37 with three replicas behind HAProxy, each downloading https://learnwiki.overleaf.com into its own node’s cache at its first start, our end-to-end tests for /learn pass (12 cases): the Documentation link in the header, the welcome message and the editor’s Help menu, the contents sidebar, pages, links and redirects inside the wiki, images loaded from the wiki, 404 for unknown pages, the login required without public access, and a stale page served from the cache after WIKI_URL was changed to an address that cannot be reached. Starting with an empty cache and WIKI_URL pointing to an address that refuses connections, the pod stayed not ready without restarting, while the web service inside it started and failed 77 times in three minutes.