0. Preparare i nodi

Installa Docker Engine, containerd e kubeadm sui nodi e scarica le immagini TeX Live.

Ayakaleaf Pro compila LaTeX in container TeX Live isolati in sandbox. Li avvia da solo, tramite il socket Docker della macchina su cui viene eseguito. Su Kubernetes questo significa che:

• ogni nodo che può eseguire il pod di Ayakaleaf Pro ha Docker Engine installato e in esecuzione;
• ogni immagine TeX Live che configuri è scaricata in Docker su ciascuno di questi nodi.

Il kubelet può continuare a usare containerd: Docker Engine include containerd.io, ed entrambi usano lo stesso daemon in namespace diversi.

I node pool gestiti senza Docker (la maggior parte delle configurazioni predefinite di EKS, GKE e AKS) non possono eseguire sandboxed compiles. Usa node pool su cui puoi installare Docker Engine, oppure etichetta tali nodi e mantieni Ayakaleaf Pro su di essi con un nodeSelector.

I passaggi seguenti si riferiscono a Ubuntu 24.04 e a un cluster creato con kubeadm. Se il tuo cluster esiste già, esegui i passaggi 1, 2 e 5 sui nodi che eseguiranno Ayakaleaf Pro.

1. Moduli del kernel e sysctl

   printf 'overlay\nbr_netfilter\n' | sudo tee /etc/modules-load.d/k8s.conf
   sudo modprobe overlay && sudo modprobe br_netfilter
   printf 'net.bridge.bridge-nf-call-iptables=1\nnet.bridge.bridge-nf-call-ip6tables=1\nnet.ipv4.ip_forward=1\n' \
     | sudo tee /etc/sysctl.d/99-k8s.conf
   sudo sysctl --system
   sudo swapoff -a   # and comment out swap in /etc/fstab
   
2. Docker Engine

   Installa Docker Engine dal repository di Docker come descritto in 0. Configurare Docker. Il plugin Compose non è necessario. In questo modo viene installato anche containerd.io.

3. containerd per il kubelet

   Il pacchetto containerd.io del repository di Docker ha il plugin CRI disattivato. Scrivi la configurazione predefinita completa, che lo attiva, e passa ai cgroup di systemd:

   containerd config default | sudo tee /etc/containerd/config.toml >/dev/null
   sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml
   # containerd 2.x writes config_path = '' and ignores /etc/containerd/certs.d without this
   sudo sed -i "s|config_path = ''|config_path = '/etc/containerd/certs.d'|" /etc/containerd/config.toml
   sudo systemctl restart containerd docker
   
4. kubeadm, kubelet e kubectl

   Segui Installing kubeadm, poi crea il cluster con kubeadm init e kubeadm join e installa un plugin di rete. Ad esempio, con flannel:

   kubeadm-config.yaml

   apiVersion: kubeadm.k8s.io/v1beta4
   kind: ClusterConfiguration
   networking:
     podSubnet: 10.244.0.0/16   # flannel's default
   ---
   apiVersion: kubelet.config.k8s.io/v1beta1
   kind: KubeletConfiguration
   cgroupDriver: systemd
   # Compile containers are started by Docker, outside the kubelet's accounting: keep memory for them
   systemReserved:
     memory: 300Mi
   kubeReserved:
     memory: 200Mi
   

   sudo kubeadm init --config kubeadm-config.yaml
   kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml
   

   Il cluster necessita anche di una StorageClass predefinita. Per un cluster di test va bene local-path-provisioner; in produzione, usa lo storage a blocchi della tua piattaforma (Longhorn, Ceph, un driver CSI del cloud).

5. Immagini TeX Live

   Su ogni nodo che può eseguire Ayakaleaf Pro, scarica con Docker le immagini TeX Live che elencherai in ALL_TEX_LIVE_DOCKER_IMAGES, ad esempio:

   sudo docker pull ghcr.io/ayaka-notes/texlive-full:2026.1
   

   crictl pull o ctr non servono in questo caso: Ayakaleaf Pro chiede l’immagine a Docker. Le immagini complete sono grandi (circa 28 GB ciascuna); vedi Sandboxed Compiles per l’elenco. Per un primo test è sufficiente ghcr.io/ayaka-notes/texlive-basic:2026.1 (circa 630 MB, un TeX Live minimale).

​

Q&A

Posso eseguire Ayakaleaf Pro su nodi senza Docker?

Risposta: Solo con SANDBOXED_COMPILES=false. Le compilazioni vengono quindi eseguite all’interno del container di Ayakaleaf Pro con il suo piccolo TeX Live integrato, e i documenti LaTeX possono leggere e scrivere tutto ciò a cui quel container ha accesso. Non lo consigliamo; vedi Sandboxed Compiles.

Le compilazioni rientrano nel limite di memoria del pod?

Risposta: No. I container TeX Live vengono avviati dal Docker del nodo, al di fuori del pod e al di fuori della vista del kubelet. Lascia memoria libera sul nodo per loro, ad esempio con systemReserved come sopra, e non riempire il nodo con altri pod.