샌드박스 컴파일

Ayakaleaf Pro는 엔터프라이즈 보안을 위해 보안 샌드박스 환경에서 컴파일을 실행하는 옵션을 제공합니다. 이는 모든 프로젝트를 각각의 보안 Docker 환경에서 실행하는 방식으로 이루어집니다.

​

향상된 보안

많은 LaTeX 문서가 PDF 컴파일 과정의 일부로 임의의 셸 명령을 실행해야 하거나 실행할 수 있기 때문에, Ayakaleaf Pro에서는 샌드박스 컴파일(Sandboxed Compiles)이 권장되는 방식입니다. 샌드박스 컴파일을 사용하면 각 컴파일은 다른 사용자나 프로젝트와 공유되지 않는 제한된 권한을 가진 별도의 Docker 컨테이너에서 실행되며, 호스트 네트워크와 같은 외부 리소스에 접근할 수 없습니다.

샌드박스 컴파일 없이 Ayakaleaf Pro를 실행하면, 컴파일이 메인 Docker 컨테이너 내부에서 다른 동시 컴파일과 함께 실행되며, 사용자는 LaTeX 컴파일을 실행할 때 sharelatex 컨테이너 리소스(파일 시스템, 네트워크 및 환경 변수)에 대한 완전한 읽기 및 쓰기 권한을 갖게 됩니다.

​

더 쉬운 패키지 관리

패키지를 수동으로 설치하지 않으려면 샌드박스 컴파일을 활성화할 것을 권장합니다. 이는 Server Pro에서 구성할 수 있는 설정으로, 자체 온프레미스 설치 환경에서도 사용자에게 overleaf.com과 동일한 TeX Live 환경을 제공합니다. 샌드박스 컴파일에서 사용하는 TeX Live 이미지에는 갤러리 템플릿으로 테스트된 가장 인기 있는 패키지와 글꼴이 포함되어 있어 온프레미스 프로젝트와의 호환성을 극대화합니다.

샌드박스 컴파일을 활성화하면 사용자가 프로젝트에서 선택할 수 있는 TeX Live 버전을 구성하고, 새 프로젝트의 기본 TeX Live 이미지 버전을 설정할 수 있습니다.

샌드박스 컴파일 없이 Ayakaleaf Pro를 실행하면 인스턴스는 기본적으로 basic scheme 버전의 TeX Live를 사용하여 컴파일합니다. 이 기본 버전은 가볍지만 매우 제한된 LaTeX 패키지만 포함하고 있으므로, 특히 사용자가 미리 만들어진 템플릿을 사용하려고 할 때 패키지 누락 오류가 발생할 가능성이 높습니다.

Ayakaleaf Pro는 오프라인에서 작동하도록 설계되었으므로 overleaf.com 갤러리 템플릿을 온프레미스 설치에 자동으로 통합하는 방법은 없습니다. 하지만 템플릿별로 수동으로 통합할 수는 있습니다. 작동 방식에 대한 자세한 내용은 overleaf.com에서 템플릿 가져오기 가이드를 참조하세요: #transferring-templates-from-overleaf.com.

샌드박스 컴파일을 사용하려면 sharelatex 컨테이너가 이러한 형제(sibling) 컴파일 컨테이너를 관리할 수 있도록 (바인드 마운트를 통해) 호스트 머신의 Docker 소켓에 접근할 수 있어야 합니다.

​

작동 방식

샌드박스 컴파일이 활성화되면 호스트 머신의 Docker 소켓이 sharelatex 컨테이너에 마운트되어, 컨테이너 내 컴파일러 서비스가 호스트에 새 Docker 컨테이너를 생성할 수 있게 됩니다. 그런 다음 각 프로젝트에서 컴파일러가 실행될 때마다 LaTeX 컴파일러 서비스(CLSI)는 다음 작업을 수행합니다.

• 프로젝트 파일을 OVERLEAF_DATA_PATH 내부의 위치에 기록합니다.
• 마운트된 Docker 소켓을 사용하여 컴파일 실행을 위한 새 texlive 컨테이너를 생성합니다.
• texlive 컨테이너가 OVERLEAF_DATA_PATH 아래의 위치에서 프로젝트 데이터를 읽도록 합니다.
• texlive 컨테이너 내부에서 프로젝트를 컴파일합니다.

​

샌드박스 컴파일 활성화하기

​

Toolkit 사용자의 경우

샌드박스 컴파일(Sibling 컨테이너라고도 함)을 활성화하려면 overleaf-toolkit/config/overleaf.rc에서 다음 구성 옵션을 설정합니다.

config/overleaf.rc

SERVER_PRO=true
SIBLING_CONTAINERS_ENABLED=true

​

Docker Compose 사용자의 경우

Overleaf CE/Server Pro 5.0.3부터 환경 변수의 이름이 SHARELATEX_*에서 OVERLEAF_*로 변경되었습니다.

4.x 버전(또는 그 이전 버전)을 사용하는 경우 변수에 적절한 접두사가 붙어 있는지 확인하세요(예: OVERLEAF_MONGO_URL 대신 SHARELATEX_MONGO_URL).

version: '2'
services:
    sharelatex:
        #...
        volumes:
            - /data/overleaf_data:/var/lib/overleaf
            - /var/run/docker.sock:/var/run/docker.sock
        environment:
            #...
            DOCKER_RUNNER: "true"
            SANDBOXED_COMPILES: "true"
            SANDBOXED_COMPILES_HOST_DIR: "/data/overleaf_data/data/compiles"
            #...
        #...

​

TexLive 이미지 설정하기

중국 본토 사용자는 다운로드 속도를 높이기 위해 ghcr.io를 ghcr.nju.edu.cn으로 바꿀 수 있습니다. 하지만 Toolkit 환경 설정에서 ghcr.nju.edu.cn을 직접 사용하지 마세요. ghcr.io만 사용해야 합니다.

Ayakaleaf Pro는 세 가지 환경 변수를 사용하여 샌드박스 컴파일에 사용할 TeX Live 이미지를 결정합니다.

• TEX_LIVE_DOCKER_IMAGE (필수): 새 프로젝트 컴파일에 사용되는 기본 TeX Live 이미지입니다. 이 이미지는 ALL_TEX_LIVE_DOCKER_IMAGES에 포함되어 있어야 합니다.
• ALL_TEX_LIVE_DOCKER_IMAGE_NAMES (필수): 프런트엔드 옵션에 사용되는 이미지의 표시 이름을 쉼표로 구분한 목록입니다.
• ALL_TEX_LIVE_DOCKER_IMAGES (필수): 사용할 TeX Live 이미지를 쉼표로 구분한 목록입니다. Overleaf Toolkit으로 배포하는 경우 이 이미지들이 다운로드되거나 업데이트됩니다. 다운로드를 건너뛰려면 config/overleaf.rc에서 SIBLING_CONTAINERS_PULL=false를 설정하세요.

bin/up 명령으로 Ayakaleaf Pro 인스턴스를 시작하면 Toolkit이 ALL_TEX_LIVE_DOCKER_IMAGES에 나열된 모든 이미지를 자동으로 pull합니다.

다음은 새 프로젝트에는 TeX Live 2026을 기본으로 사용하고, 기존 프로젝트에는 2025를 계속 사용하는 예시입니다.

최소 설치

다음 구성은 2025년부터 2026년까지의 전체 TeX Live Docker 이미지를 설치합니다. 이 구성을 사용하기 전에 최소 64 GB의 사용 가능한 저장 공간을 확보할 것을 권장합니다.

config/variables.env

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=Texlive 2026, Texlive 2025
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

전체 설치

다음 구성은 2020년부터 2026년까지의 전체 TeX Live Docker 이미지를 모두 설치합니다. 이 구성을 사용하기 전에 최소 150 GB의 사용 가능한 저장 공간을 확보할 것을 권장합니다.

config/variables.env

ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2026.1,ghcr.io/ayaka-notes/texlive-full:2025.1,ghcr.io/ayaka-notes/texlive-full:2024.1,ghcr.io/ayaka-notes/texlive-full:2023.1,ghcr.io/ayaka-notes/texlive-full:2022.1,ghcr.io/ayaka-notes/texlive-full:2021.1,ghcr.io/ayaka-notes/texlive-full:2020.1
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2026,Texlive 2025,Texlive 2024,Texlive 2023,Texlive 2022,Texlive 2021,Texlive 2020
TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2026.1

최소 2개의 texlive-full 이미지를 설정할 것을 적극 권장합니다. 자세한 이유는 #known-issues를 참조하세요.

​

사용 가능한 TeX Live 이미지

다음은 Overleaf에 특별히 최적화된 TeX Live 이미지 시리즈로, TEX_LIVE_DOCKER_IMAGE와 ALL_TEX_LIVE_DOCKER_IMAGES에 추가할 수 있습니다.

• ghcr.io/ayaka-notes/texlive-full:2026.1 (latest 태그도 해당)
• ghcr.io/ayaka-notes/texlive-full:2025.1
• ghcr.io/ayaka-notes/texlive-full:2024.1
• ghcr.io/ayaka-notes/texlive-full:2023.1
• ghcr.io/ayaka-notes/texlive-full:2022.1
• ghcr.io/ayaka-notes/texlive-full:2021.1
• ghcr.io/ayaka-notes/texlive-full:2020.1

이미지 태그 지정 방식에는 반드시 따라야 하는 엄격한 규칙이 있습니다(정규식 ^[0-9]+.[0-9]+가 적용되며, 첫 번째 숫자는 TeX Live 연도를, 두 번째 숫자는 패치 버전을 나타냅니다).

​

다른 이미지 레지스트리를 사용할 수 있나요?

ghcr.io를 다른 미러 사이트로 바꾸거나, texlive를 Docker Hub의 다른 이미지로 전환할 수 있는지 궁금해하는 분들도 있을 것입니다.

구성이 비교적 복잡하므로 권장하지 않습니다. 미러 사이트에서 다운로드하는 경우 이미지 이름을 ghcr.io/ayaka-notes/texlive-full로 변경할 수 있습니다.

하지만 정말로 자체 이미지 레지스트리를 사용하려면 다음을 추가하세요.

config/variables.env

IMAGE_ROOT=hub.your.com/your-repo

그런 다음 다음과 같이 모든 texlive 이미지가 your-repo에 있는지 확인해야 합니다.

• hub.your.com/your-repo/texlive-full:2025.1
• hub.your.com/your-repo/texlive-full:2024.1

자세한 내용은 아래 소스 코드를 읽고 환경 변수가 어떻게 파싱되는지 확인하세요.

sandboxed-compiles/index.mjs

if (process.env.SANDBOXED_COMPILES === 'true') {
  // Set default image root if not provided
  let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes";
  // Export imageRoot to Settings
  Settings.imageRoot = imageRootPath

  // allowedImageNames should be:
  // [
  //  { imageName: "texlive-2023:latest", imageDesc: "TeX Live 2023" },
  //  { imageName: "texlive-2022:latest", imageDesc: "TeX Live 2022" },
  // ]
  Settings.allowedImageNames = parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGES)
    .map((texImage, index) => ({
      imageName: texImage.split("/")[texImage.split("/").length - 1],
      imageDesc: parseTextExtensions(process.env.ALL_TEX_LIVE_DOCKER_IMAGE_NAMES)[index]
        || texImage.split(':')[1],
    }))
  
  // In the end, imageName will be put together with imageRoot to form the full image path
  // The full name will be like: ghcr.io/ayaka-notes/texlive-2023:latest

  // Set default image name if not provided
  if(!process.env.TEX_LIVE_DOCKER_IMAGE) {
    process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName
  }

  // Export currentImageName to Settings
  // This is the new created projects' image name
  Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE
}

​

TeX Live 이미지 자동 동기화

매번 bin/up으로 인스턴스를 수동 업데이트하지 않도록 TeX Live 이미지 업데이트를 자동화할 수 있습니다. updating-tex-live-full-images-automatically.md를 참조하세요.

​

알려진 문제

다음은 Overleaf 커뮤니티의 실제 사례입니다.

6.0.1-ext-v3.3을 사용하고 있으며, variables.env에 다음과 같이 설정했습니다.

TEX_LIVE_DOCKER_IMAGE=texlive/texlive:latest-full
ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texlive:latest-full

texlive/texlive:latest-full에서는 잘 작동합니다. 그런데 다른 texlive 이미지 danteev/texlive:2025-10-15를 pull하고 두 변수를 모두 새 이미지 이름으로 변경했더니 작동하지 않습니다.

TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15
ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15

로그에는 다음과 같은 내용이 표시됩니다.

{"name":"clsi","level":50,"err":{"message":"(HTTP code 404) no such container - No such image: texlive/texlive:latest-full ","name":"Error","stack":"Error: (HTTP code 404) no such container - No such image: texlive/texlive:latest-full ... 

variables.env에서 업데이트한 설정이 적용되지 않는 것 같습니다. 컴파일은 여전히 새 이미지가 아닌 texlive/texlive:latest-full 이미지를 실행하려고 합니다.

재부팅하고, 컨테이너를 삭제한 후 다시 실행해 보았지만 여전히 같은 문제가 발생합니다.

해결 방법이 있을까요?

기술적인 제약으로 인해, texlive-fullA:latest와 같이 단일 Docker TeXLive 이미지만 설정한 경우

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

Overleaf 인스턴스를 한동안 실행한 후 TeXLive 이미지를 texlive-fullB:latest로 변경하고 싶을 수 있습니다. 그러면 사용자들이 모든 프로젝트를 컴파일할 수 없게 되는 것을 보게 됩니다.

ALL_TEX_LIVE_DOCKER_IMAGES=texlive/texliveA:latest-full
ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=TeXLiveA
TEX_LIVE_DOCKER_IMAGE=texlive/texliveA:latest-full

이는 각 프로젝트의 (샌드박스 컴파일용) TeXLive-Full 이미지 이름이 데이터베이스에 저장되기 때문입니다. 사용자가 프로젝트의 TeXLive 버전을 예를 들어 2024에서 2025로 전환할 때에만 데이터베이스의 이미지 이름이 변경됩니다.

CLSI는 프로젝트를 컴파일할 때 데이터베이스에 저장된 컨테이너 이미지 이름을 그대로 사용하여 프로젝트를 컴파일합니다.

Docker 이미지를 하나만 제공하면 사용자는 프로젝트 컴파일에 사용되는 이미지를 변경할 수 없습니다. 이 경우 MongoDB에서 모든 사용자 프로젝트의 TeXLive 이미지를 수동으로 수정하는 스크립트를 작성해야 합니다.

​

디버그 및 보고

다음 명령을 실행하여 Toolkit에서 clsi 로그를 확인합니다.

bin/logs clsi

TeX Live 이미지로 컴파일하는 데 문제가 발생하면 여기에 이슈를 제출해 주세요.

https://github.com/ayaka-notes/texlive-full/issues/new?template=texlive-image-bug.yml

문제를 재현하고 해결하는 데 도움이 되도록 프로젝트를 Overleaf에 업로드해 달라는 요청을 받을 수 있습니다. 그러면 저희가 프로젝트를 가져와 GitHub Action으로 컴파일 테스트를 실행합니다.