> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 샌드박스 컴파일

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

컴파일은 모든 Ayakaleaf Pro 파드 안의 **clsi** 서비스가 실행합니다. 샌드박스 컴파일을 활성화하면 clsi는 파드가 실행 중인 **노드의 Docker Engine**에 컴파일마다 TeX Live 컨테이너를 시작하도록 요청하고, 해당 노드상의 경로로 프로젝트 디렉터리를 전달합니다. 샌드박싱의 동작 방식과 제공되는 이미지는 [샌드박스 컴파일](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/sandboxed-compiles.md)에 설명되어 있습니다.

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

### 구성

설치 과정에서 모든 것이 설정됩니다: [0. 노드 준비](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-kubernetes/0.-prepare-the-nodes.md)에서 노드의 Docker와 이미지, [4. 인스턴스 개인화](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-kubernetes/4.-personalizing-your-instance.md)에서 설정, [5. Ayakaleaf Pro 배포](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-kubernetes/5.-deploy-ayakaleaf-pro.md)에서 볼륨을 설정합니다. 설정은 모두 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**

```bash theme={null}
# 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에 추가하고 재시작**

```yaml theme={null}
  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
```

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
```

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

### 여러 레플리카

각 레플리카는 자신의 노드에서 컴파일하고 컴파일 출력을 그곳에 보관하므로, 사용자는 컴파일한 레플리카에 머물러야 하며 로드 밸런서의 고정(sticky) 쿠키가 이를 보장합니다. 같은 노드에서 두 레플리카를 실행하지 마세요. 노드의 컴파일 디렉터리를 공유하게 됩니다. [수평 확장](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/kubernetes/horizontal-scaling.md) 구성은 `podAntiAffinity`로 이를 방지합니다.

TeX Live 컨테이너는 파드 옆에서 실행되며, 파드의 메모리 제한과 스케줄러의 관리 범위 밖에 있습니다. 이를 위해 노드에 여유 메모리를 남겨 두세요. [0. 노드 준비](https://ayakaleaf-pro.mintlify.site/ko/on-premises/installation/using-kubernetes/0.-prepare-the-nodes.md)를 참조하세요.

### Kubernetes에서의 테스트

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.