샌드박스 컴파일

Kubernetes 클러스터의 노드에서 TeX Live 컨테이너로 LaTeX를 컴파일합니다.

컴파일은 모든 Ayakaleaf Pro 파드 안의 clsi 서비스가 실행합니다. 샌드박스 컴파일을 활성화하면 clsi는 파드가 실행 중인 노드의 Docker Engine에 컴파일마다 TeX Live 컨테이너를 시작하도록 요청하고, 해당 노드상의 경로로 프로젝트 디렉터리를 전달합니다. 샌드박싱의 동작 방식과 제공되는 이미지는 샌드박스 컴파일에 설명되어 있습니다.

서비스	clsi(컴파일), web(컴파일러 설정의 이미지 목록), 모든 Ayakaleaf Pro 파드에 포함
노드	Ayakaleaf Pro를 실행할 수 있는 모든 노드의 Docker Engine 및 ALL_TEX_LIVE_DOCKER_IMAGES의 모든 이미지
파드 마운트	/var/run/docker.sock, 그리고 hostPath 볼륨으로 마운트되는 컴파일, 출력, 캐시 디렉터리
주기적 작업	clsi는 하루 동안 사용되지 않은 컴파일 디렉터리를 삭제하고, 매시간 노드의 Docker에서 오래된 TeX Live 컨테이너를 제거함

​

구성

설치 과정에서 모든 것이 설정됩니다: 0. 노드 준비에서 노드의 Docker와 이미지, 4. 인스턴스 개인화에서 설정, 5. Ayakaleaf Pro 배포에서 볼륨을 설정합니다. 설정은 모두 ConfigMap에 있습니다.

변수	값
SANDBOXED_COMPILES, SANDBOXED_COMPILES_SIBLING_CONTAINERS, DOCKER_RUNNER	"true"
SANDBOXED_COMPILES_HOST_DIR_COMPILES	/var/lib/overleaf/data/compiles에 마운트된 볼륨의 노드 경로
SANDBOXED_COMPILES_HOST_DIR_OUTPUT	/var/lib/overleaf/data/output에 마운트된 볼륨의 노드 경로
SANDBOXED_COMPILES_HOST_DIR_CACHE	/var/lib/overleaf/data/cache에 마운트된 볼륨의 노드 경로
	ALL_TEX_LIVE_DOCKER_IMAGES, ALL_TEX_LIVE_DOCKER_IMAGE_NAMES, TEX_LIVE_DOCKER_IMAGE	Toolkit과 동일한 이미지

​

TeX Live 버전 추가

1. 모든 노드에서 이미지 pull

   # on each node that can run Ayakaleaf Pro
   sudo docker pull ghcr.io/ayaka-notes/texlive-full:2025.1
   

   Toolkit은 이미지를 직접 pull하지만, Kubernetes에서는 아무도 이를 대신해 주지 않습니다. crictl이 아닌 Docker로 pull하세요. clsi는 Docker에 이미지를 요청합니다. 노드에 없는 이미지로 컴파일하면 실패합니다.

2. ConfigMap에 추가하고 재시작

     ALL_TEX_LIVE_DOCKER_IMAGES: ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1
     ALL_TEX_LIVE_DOCKER_IMAGE_NAMES: TeX Live 2026,TeX Live 2025
     TEX_LIVE_DOCKER_IMAGE: ghcr.io/ayaka-notes/texlive-full:2026.1
   

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

나중에 클러스터에 추가된 노드는 Ayakaleaf Pro가 실행되기 전에 Docker와 모든 이미지가 준비되어 있어야 합니다. 모든 노드가 조건을 충족하지 않는다면 해당 노드에 레이블을 붙이고 nodeSelector로 Ayakaleaf Pro가 그 노드에서만 실행되도록 하세요.

​

여러 레플리카

각 레플리카는 자신의 노드에서 컴파일하고 컴파일 출력을 그곳에 보관하므로, 사용자는 컴파일한 레플리카에 머물러야 하며 로드 밸런서의 고정(sticky) 쿠키가 이를 보장합니다. 같은 노드에서 두 레플리카를 실행하지 마세요. 노드의 컴파일 디렉터리를 공유하게 됩니다. 수평 확장 구성은 podAntiAffinity로 이를 방지합니다.

TeX Live 컨테이너는 파드 옆에서 실행되며, 파드의 메모리 제한과 스케줄러의 관리 범위 밖에 있습니다. 이를 위해 노드에 여유 메모리를 남겨 두세요. 0. 노드 준비를 참조하세요.

​

Kubernetes에서의 테스트

HAProxy 뒤에 노드당 하나씩 레플리카 세 개를 두고 모든 노드의 Docker에 TeX Live 2026과 2025를 pull한 Kubernetes 1.37에서, 샌드박스 컴파일에 대한 엔드 투 엔드 테스트가 통과했습니다(7개 케이스). 테스트 항목은 새 프로젝트를 PDF로 컴파일, 컴파일러 설정에서 두 이미지를 제공하고 서로 전환, fontspec을 사용한 XeLaTeX, LaTeX 오류 및 수정 후 재컴파일, 실행 중인 컴파일 중지, 양방향 SyncTeX입니다. 12명의 사용자가 600페이지 문서를 동시에 컴파일하는 부하 테스트에서는 노드당 4개의 컴파일이 실행되었습니다. 예상 결과를 참조하세요.