> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/sandboxed-compiles.md). # 샌드박스화된 컴파일 Overleaf Pro는 엔터프라이즈 보안을 위해 보안된 샌드박스 환경에서 컴파일을 실행하는 옵션을 제공합니다. 각 프로젝트를 자체 보안 Docker 환경에서 실행하여 이를 수행합니다. ### 향상된 보안 많은 LaTeX 문서가 PDF 컴파일 과정의 일부로 임의의 셸 명령을 실행해야 하거나 실행할 수 있기 때문에, Server Pro에서는 Sandboxed Compiles를 권장합니다. Sandboxed Compiles를 사용하면 각 컴파일은 별도의 Docker 컨테이너에서 실행되며, 이 컨테이너의 기능은 다른 사용자나 프로젝트와 공유되지 않고 호스트 네트워크와 같은 외부 리소스에도 접근할 수 없습니다. {% hint style="warning" %} Overleaf Pro를 실행하려고 시도하면 **없이** Sandboxed Compiles 없이 컴파일을 실행하면, 컴파일은 메인 Docker 컨테이너 안에서 다른 동시 컴파일과 함께 실행되며 사용자는 LaTeX 컴파일을 실행할 때 `sharelatex` 컨테이너 리소스(파일 시스템, 네트워크 및 환경 변수)에 대해 전체 읽기 및 쓰기 권한을 갖습니다. {% endhint %} ### 더 쉬운 패키지 관리 패키지를 수동으로 설치하는 것을 피하려면 Sandboxed Compiles를 활성화하는 것을 권장합니다. 이는 Server Pro 내에서 구성 가능한 설정으로, 사용자가 overleaf.com과 동일한 TeX Live 환경에 접근할 수 있게 하면서도 귀사의 자체 온프레미스 설치 환경 내에서 제공됩니다. Sandboxed Compiles에서 사용하는 TeX Live 이미지는 갤러리 템플릿으로 테스트된 가장 인기 있는 패키지와 글꼴을 포함하여 온프레미스 프로젝트와의 호환성을 최대한 보장합니다. Sandboxed Compiles를 활성화하면 사용자가 프로젝트 내에서 선택할 수 있는 TeX Live 버전을 구성하고, 새 프로젝트의 기본 TeX Live 이미지 버전을 설정할 수 있습니다. {% hint style="info" %} Sandboxed Compiles 없이 Overleaf Pro를 실행하려고 하면, 인스턴스는 컴파일에 기본 스킴 버전의 TeX Live를 사용하도록 기본 설정됩니다. 이 기본 버전은 경량이며 LaTeX 패키지의 매우 제한된 하위 집합만 포함하므로, 특히 사전 제작된 템플릿을 사용하려는 경우 사용자가 패키지 누락 오류를 겪을 가능성이 높습니다. {% endhint %} Overleaf Pro는 오프라인에서 작동하도록 설계되었기 때문에 overleaf.com 갤러리 템플릿을 온프레미스 설치에 자동으로 통합하는 방법은 없습니다. 다만 템플릿별로 수동으로는 가능합니다. 작동 방식에 대한 자세한 내용은 overleaf.com에서 템플릿 전송 가이드를 참고하세요: [/pages/f44d4854176771614a498001261f42a01ed4c64a#transferring-templates-from-overleaf.com](https://overleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/pages/f44d4854176771614a498001261f42a01ed4c64a#transferring-templates-from-overleaf.com "mention"). {% hint style="info" %} Sandboxed Compiles를 사용하려면 다음이 필요합니다: `sharelatex` 컨테이너가 호스트 머신의 Docker 소켓에(바인드 마운트를 통해) 접근할 수 있어야 하며, 그래야 이러한 형제 컴파일 컨테이너를 관리할 수 있습니다. {% endhint %} ## 작동 방식 Sandboxed Compiles가 활성화되면 Docker 소켓이 호스트 머신에서 다음 위치로 마운트됩니다: `sharelatex` 컨테이너 안의 컴파일러 서비스가 호스트에서 새 Docker 컨테이너를 만들 수 있습니다. 그런 다음 각 프로젝트의 컴파일 실행마다 LaTeX 컴파일러 서비스(CLSI)는 다음을 수행합니다: * 프로젝트 파일을 다음 내부의 위치에 기록합니다: `OVERLEAF_DATA_PATH`. * 마운트된 Docker 소켓을 사용하여 새 `texlive` 컴파일 실행용 컨테이너를 생성합니다. * 다음의 `texlive` 컨테이너가 다음 아래의 위치에서 프로젝트 데이터를 읽도록 합니다: `OVERLEAF_DATA_PATH`. * 다음 내부에서 프로젝트를 컴파일합니다: `texlive` 컨테이너. ### Sandboxed Compiles 활성화 #### Toolkit 사용자의 경우 샌드박스 컴파일(형제 컨테이너라고도 함)을 활성화하려면 다음 구성 옵션을 다음에 설정하세요: `overleaf-toolkit/config/overleaf.rc`: {% code title="config/overleaf.rc" %} ```dotenv SERVER_PRO=true SIBLING_CONTAINERS_ENABLED=true ``` {% endcode %} #### Docker Compose 사용자의 경우 {% hint style="danger" %} Overleaf CE/Server Pro부터 `5.0.3` 환경 변수의 브랜드명이 다음에서 변경되었습니다. `SHARELATEX_*` 에서 `OVERLEAF_*`. {% endhint %} 만약 다음을 사용 중이라면 `4.x` 버전(또는 이전 버전)에서는 변수에 올바른 접두사가 붙어 있는지 확인하세요(예: `SHARELATEX_MONGO_URL` 대신에 `OVERLEAF_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"
            #...
        #...
### TeX Live 이미지 변경 {% hint style="info" %} 중국 본토 사용자의 경우 다음을 사용할 수 있습니다 `ghcr.nju.edu.cn` 다운로드 속도를 높일 수 있습니다. {% endhint %} Overleaf Pro는 Sandboxed Compiles에 사용할 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을 사용하는 경우 이 이미지들은 다운로드되거나 업데이트됩니다. 다운로드를 건너뛰려면 다음을 설정하세요: `SIBLING_CONTAINERS_PULL=false` 를 `config/overleaf.rc`. 다음으로 Overleaf Pro 인스턴스를 시작할 때 `bin/up` 명령을 사용하면 Toolkit이 다음에 나열된 모든 이미지를 자동으로 가져옵니다: `ALL_TEX_LIVE_DOCKER_IMAGES`. 다음은 새 프로젝트에는 TeX Live 2025를 기본값으로 사용하고 기존 프로젝트에는 2024를 계속 사용하는 예시입니다. {% code title="config/variables.env" overflow="wrap" %} ```dotenv ALL_TEX_LIVE_DOCKER_IMAGES=ghcr.io/ayaka-notes/texlive-full:2025.1, ghcr.io/ayaka-notes/texlive-full:2024.1 ALL_TEX_LIVE_DOCKER_IMAGE_NAMES=Texlive 2025, Texlive 2024 TEX_LIVE_DOCKER_IMAGE=ghcr.io/ayaka-notes/texlive-full:2025.1 ``` {% endcode %} {% hint style="danger" %} 다음을 설정하는 것을 강력히 권장합니다 **적어도 2개의 texlive-full 이미지**. 자세한 이유는 다음을 참고하세요: [#known-issues](#known-issues "mention") {% endhint %} ### 사용 가능한 TeX Live 이미지 이는 Overleaf에 맞게 특별히 최적화된 일련의 TeX Live 이미지이며, 다음에도 추가할 수 있습니다 `TEX_LIVE_DOCKER_IMAGE` 그리고 `ALL_TEX_LIVE_DOCKER_IMAGES`: * `ghcr.io/ayaka-notes/texlive-full:2025.1` (또한 `latest` 태그) * `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` {% hint style="warning" %} 이미지 태깅 방식에 대해 엄격한 스키마가 있습니다 **반드시** 태그되어야 합니다(다음 정규식이 적용됩니다 `^[0-9]+.[0-9]+`, 여기서 첫 번째 숫자는 TeX Live 연도를, 두 번째 숫자는 패치 버전을 나타냅니다). {% endhint %} ### 다른 이미지 레지스트리를 사용할 수 있나요? > 일부 사용자는 제가 다음을 대체할 수 있는지 궁금해할 수 있습니다 `ghcr.io` 다른 미러 사이트로 바꾸거나, texlive를 Docker Hub의 다른 이미지로 변경할 수 있는지? 아니요, 구성 방법이 비교적 복잡하므로 권장하지 않습니다. 미러 사이트에서 다운로드하는 경우 이미지 이름을 다음과 같이 바꿀 수 있습니다 `ghcr.io/ayaka-notes/texlive-full`. 하지만 정말로 자체 이미지 레지스트리를 사용하고 싶다면 다음을 추가하세요: {% code title="config/variables.env" overflow="wrap" %} ```dotenv IMAGE_ROOT=hub.your.com/your-repo ``` {% endcode %} 그다음 texlive의 모든 이미지가 다음에 있는지 확인해야 합니다 `your-repo`, 예를 들어 * `hub.your.com/your-repo/texlive-full:2025.1` * `hub.your.com/your-repo/texlive-full:2024.1` 자세한 정보는 아래 소스 코드를 읽고 env 변수를 어떻게 파싱하는지 확인하세요: {% code title="sandboxed-compiles/index.mjs" overflow="wrap" expandable="true" %} ```mjs if (process.env.SANDBOXED_COMPILES === 'true') { // 제공되지 않은 경우 기본 이미지 루트를 설정 let imageRootPath = process.env.IMAGE_ROOT || "ghcr.io/ayaka-notes"; // imageRoot를 Settings에 내보냄 Settings.imageRoot = imageRootPath // allowedImageNames는 다음과 같아야 합니다: // [ // { 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], })) // 결국 imageName은 imageRoot와 함께 결합되어 전체 이미지 경로를 형성합니다 // 전체 이름은 다음과 같습니다: ghcr.io/ayaka-notes/texlive-2023:latest // 제공되지 않은 경우 기본 이미지 이름을 설정 if(!process.env.TEX_LIVE_DOCKER_IMAGE) { process.env.TEX_LIVE_DOCKER_IMAGE = imageRootPath + "/" + Settings.allowedImageNames[0].imageName } // currentImageName을 Settings에 내보냄 // 이것은 새로 생성된 프로젝트의 이미지 이름입니다 Settings.currentImageName = process.env.TEX_LIVE_DOCKER_IMAGE } ``` {% endcode %} ### 알려진 문제 > 사용 `6.0.1-ext-v3.3`, 저는 다음에 이러한 설정을 가지고 있습니다 `variables.env`: > > ```dotenv > 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` 그리고 이 두 변수를 새 이미지 이름으로 변경했지만 작동하지 않습니다: > > ```dotenv > TEX_LIVE_DOCKER_IMAGE=danteev/texlive:2025-10-15 > ALL_TEX_LIVE_DOCKER_IMAGES=danteev/texlive:2025-10-15 > ``` > > 로그에서 다음을 확인했습니다: > > {% code overflow="wrap" %} > > ``` > {"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 ... > ``` > > {% endcode %} > > 다음의 업데이트된 설정이 적용되지 않는 것 같습니다 `variables.env` 컴파일은 여전히 다음을 실행하려고 시도합니다 `texlive/texlive:latest-full` 이미지를 사용하며, 새 이미지는 아닙니다. > > 재부팅하고 컨테이너를 삭제한 뒤 다시 실행해 봤지만 여전히 같은 문제입니다. > > 해결 방법이 있을까요? 몇 가지 기술적 제한으로 인해, 예를 들어 단일 Docker TeXLive 이미지만 설정한 경우 `texlive-fullA: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 ``` 그리고 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 로그를 확인하려면 다음 명령을 실행하세요: {% code overflow="wrap" %} ```bash bin/logs clsi ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/sandboxed-compiles.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.