> For the complete documentation index, see [llms.txt](https://ayakaleaf-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://ayakaleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/sandboxed-compiles.md). # 샌드박스화된 컴파일 Overleaf Pro에는 엔터프라이즈 보안을 위한 보안 샌드박스 환경에서 컴파일을 실행할 수 있는 옵션이 포함되어 있습니다. 각 프로젝트를 자체 보안 Docker 환경에서 실행함으로써 이를 구현합니다. ### 향상된 보안 많은 LaTeX 문서가 PDF 컴파일 과정의 일부로 임의의 셸 명령을 실행해야 하거나 실행할 수 있기 때문에, Server Pro에서는 샌드박스화된 컴파일이 권장되는 방식입니다. 샌드박스화된 컴파일을 사용하면 각 컴파일은 별도의 Docker 컨테이너에서 실행되며, 그 기능은 다른 사용자나 프로젝트와 공유되지 않고 호스트 네트워크와 같은 외부 리소스에도 접근할 수 없습니다. {% hint style="warning" %} Overleaf Pro를 실행하려고 시도할 때 **샌드박스화된 컴파일 없이** 샌드박스화된 컴파일을 사용하지 않으면, 컴파일은 주 Docker 컨테이너 안에서 다른 동시 컴파일과 함께 실행되며 사용자는 다음에 대해 전체 읽기 및 쓰기 권한을 갖게 됩니다. `sharelatex` LaTeX 컴파일을 실행할 때 컨테이너 리소스(파일 시스템, 네트워크 및 환경 변수). {% endhint %} ### 더 쉬운 패키지 관리 패키지를 수동으로 설치하지 않으려면 샌드박스화된 컴파일을 활성화하는 것을 권장합니다. 이는 Server Pro 내에서 설정 가능한 옵션으로, 사용자가 overleaf.com과 동일한 TeX Live 환경에 접근할 수 있도록 해 주지만 자체 온프레미스 설치 환경 안에서 제공됩니다. 샌드박스화된 컴파일에서 사용하는 TeX Live 이미지는 갤러리 템플릿에서 테스트된 가장 인기 있는 패키지와 글꼴을 포함하므로 온프레미스 프로젝트와의 호환성을 최대한 보장합니다. 샌드박스화된 컴파일을 활성화하면 사용자가 프로젝트 내에서 선택할 수 있는 TeX Live 버전을 설정할 수 있고, 새 프로젝트에 대한 기본 TeX Live 이미지 버전도 지정할 수 있습니다. {% hint style="info" %} 샌드박스화된 컴파일 없이 Overleaf Pro를 실행하려고 하면, 인스턴스는 컴파일에 기본 스킴 버전의 TeX Live를 사용하도록 기본 설정됩니다. 이 기본 버전은 경량이며 매우 제한된 LaTeX 패키지 하위 집합만 포함하므로, 특히 미리 만들어진 템플릿을 사용하려 할 때 사용자에게 패키지 누락 오류가 발생할 가능성이 높습니다. {% endhint %} Overleaf Pro는 오프라인에서도 동작하도록 설계되어 있으므로, overleaf.com 갤러리 템플릿을 온프레미스 설치 환경에 자동으로 통합하는 방법은 없습니다. 다만 템플릿별로 수동으로는 가능합니다. 이 동작 방식에 대한 자세한 내용은 overleaf.com에서 템플릿을 이전하는 방법 가이드를 확인하세요: [/pages/f44d4854176771614a498001261f42a01ed4c64a#transferring-templates-from-overleaf.com](https://ayakaleaf-pro.ayaka.space/on-premises/ko/configuration/overleaf-toolkit/pages/f44d4854176771614a498001261f42a01ed4c64a#transferring-templates-from-overleaf.com "mention"). {% hint style="info" %} 샌드박스화된 컴파일에는 다음이 필요합니다. `sharelatex` 컨테이너가 호스트 머신의 Docker 소켓에 바인드 마운트를 통해 접근할 수 있어야 하며, 그래야 이러한 형제 컴파일 컨테이너를 관리할 수 있습니다. {% endhint %} ## 작동 방식 샌드박스화된 컴파일이 활성화되면 Docker 소켓이 호스트 머신에서 다음으로 마운트됩니다. `sharelatex` 컨테이너, যাতে 컨테이너 안의 컴파일러 서비스가 호스트에 새 Docker 컨테이너를 생성할 수 있습니다. 그런 다음 각 프로젝트에서 컴파일러를 실행할 때마다 LaTeX 컴파일러 서비스(CLSI)는 다음 작업을 수행합니다: * 프로젝트 파일을 다음 내부의 위치에 기록합니다. `OVERLEAF_DATA_PATH`. * 마운트된 Docker 소켓을 사용하여 새 `texlive` 컴파일 실행용 컨테이너를 생성합니다. * 컨테이너가 다음 아래의 위치에서 프로젝트 데이터를 읽도록 합니다. `texlive` OVERLEAF\_DATA\_PATH `OVERLEAF_DATA_PATH`. * 프로젝트를 다음 내부에서 컴파일합니다. `texlive` 컨테이너. ### 샌드박스화된 컴파일 활성화 #### 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 `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"
            #...
        #...
### TexLive 이미지 변경 {% hint style="info" %} 중국 본토 사용자라면 `ghcr.nju.edu.cn` 을 사용해 다운로드를 가속할 수 있습니다. {% endhint %} Overleaf 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을 사용하는 경우 이러한 이미지는 다운로드되거나 업데이트됩니다. 다운로드를 건너뛰려면 다음을 설정하세요. `SIBLING_CONTAINERS_PULL=false` 에서 `config/overleaf.rc`. Overleaf Pro 인스턴스를 다음 명령으로 시작할 때 `bin/up` Toolkit이 다음에 나열된 모든 이미지를 자동으로 가져옵니다. `ALL_TEX_LIVE_DOCKER_IMAGES`. 여기 새 프로젝트에는 TeX Live 2025를 기본값으로 사용하고, 기존 프로젝트에는 2024를 유지하는 예제가 있습니다. {% tabs %} {% tab title="일반 설치" %} 다음 구성은 2025년부터 2026년까지의 전체 TeX Live Docker 이미지를 모두 설치합니다. 이 구성을 사용하기 전에 최소 80GB의 사용 가능한 저장 공간이 있는 것을 권장합니다. {% code title="config/variables.env" overflow="wrap" %} ```dotenv 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 ``` {% endcode %} {% endtab %} {% tab title="전체 설치" %} 다음 구성은 2020년부터 2026년까지의 전체 TeX Live Docker 이미지를 모두 설치합니다. 이 구성을 사용하기 전에 최소 256GB의 사용 가능한 저장 공간이 있는 것을 권장합니다. {% code title="config/variables.env" overflow="wrap" %} ```dotenv 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 ``` {% endcode %} {% endtab %} {% endtabs %} {% 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: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` {% 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 %} ### 알려진 문제 다음은 overleaf 커뮤니티의 실제 사례입니다: > 사용 중 `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://ayakaleaf-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.