메인 콘텐츠로 건너뛰기
개발 환경의 샌드박스 컴파일은 프로덕션 이미지와 조금 다르게 동작합니다. 개발 환경에는 이미 설정되어 있으며, 이 페이지에서는 그 설정과 유의해야 할 세 가지를 설명합니다.
  • 파일 권한 문제
  • history-v1과 filestore 간 볼륨 공유
  • 하위 디렉터리 문제

샌드박스 컴파일 활성화

샌드박스 컴파일은 기본으로 켜져 있습니다. develop/docker-compose.yml이 clsi에 SANDBOXED_COMPILES=true를 설정하고, 나머지는 develop/dev.env에 있습니다.
develop/dev.env
clsi는 이미지를 직접 받지 않으므로 docker pull ghcr.io/ayaka-notes/texlive-full:2026.1(및 :2025.1)로 이미지를 한 번 받으세요. LaTeX는 형제 컨테이너에서 TEXLIVE_IMAGE_USER로 실행됩니다. 개발 환경에서는 tex이며, 이는 clsi의 기본값이기도 합니다(services/clsi/config/settings.defaults.cjs:154). 프로덕션 이미지는 SANDBOXED_COMPILES_SIBLING_CONTAINERS=true일 때 대신 www-data를 사용합니다(server-ce/config/env.sh:15-21). 그곳에서는 Overleaf 컨테이너의 www-data 사용자가 파일을 만들기 때문입니다.
직접 빌드한 이미지는 사용하지 마세요. 여러 가지 오류가 발생할 수 있습니다.

파일 권한 수정

clsi 컨테이너는 root로 시작하여 compiles, output, cache 폴더를 node 사용자(uid 1000)에게 넘긴 뒤 clsi를 node로 실행합니다(services/clsi/entrypoint.sh). 따라서 호스트의 develop/compiles는 uid 1000 소유이며, 이는 개발 환경의 tex와 같은 uid입니다(develop/pandoc/Dockerfile의 주석 참고). 위 설정이면 개발 환경은 권한을 바꾸지 않아도 컴파일됩니다. 대신 TEXLIVE_IMAGE_USER=root를 설정하면 root(uid 0)에는 compiles 하위 폴더에 쓸 권한이 없습니다. 이 경우 compiles의 소유 그룹을 root로 하고 쓰기 권한을 준 다음, 새 하위 폴더가 이 소유권을 상속하도록 setgid를 설정하세요.
bash
자세한 문서는 services/clsi/README.md를 참고하세요.

history-v1과 filestore 간 볼륨 공유

이 섹션과 다음 섹션의 설정은 이미 develop/docker-compose.yml과 develop/dev.env에 들어 있습니다. develop/dev.rc에서 S3_ENABLED=false일 때만 의미가 있습니다. 기본값인 S3_ENABLED=true에서는 filestore와 history-v1이 이 파일들을 대신 RustFS 버킷에 보관합니다(develop/s3/docker-compose.yml).
기본적으로 filestore는 Overleaf에서 S3와 다른 서비스 사이의 다리 역할을 합니다. 하지만 Overleaf CE나 Server Pro에서는 기본적으로 모든 파일이 로컬에 저장됩니다. 그래서 Overleaf는 매우 까다로운 방법을 도입했습니다.
server-ce/config/settings.js
동시에 data/history는 기록 서비스에서도 사용됩니다. 이렇게 하면 서로 다른 마이크로서비스가 같은 데이터를 공유할 수 있습니다. 그래서 develop의 filestore 서비스는 history-v1의 history-v1-buckets 볼륨을 마운트합니다. 이것이 없으면 clsi가 filestore 서비스에서 blob 파일을 가져올 수 없습니다.
develop/docker-compose.yml
filestore는 dev.env의 다음 설정으로 버킷을 찾습니다.
develop/dev.env

하위 디렉터리 사용

filestore는 기록 blob을 항상 하위 디렉터리와 함께 읽습니다(services/filestore/app/js/KeyBuilder.js:58, :70). 프로덕션 이미지는 history-v1에 useSubdirectories를 켜지만(server-ce/config/production.json) history-v1의 기본 설정은 그렇지 않으므로, 개발 환경에서는 history-v1이 모든 데이터를 평탄하게 저장하게 됩니다. 그래서 dev.env가 history-v1에 NODE_CONFIG를 설정합니다.
develop/dev.env
이 설정이 없으면 history-v1은 project_blobs 파일을 다음과 같이 저장합니다.
useSubdirectories를 true로 설정하면 이 이름들의 _가 /가 되어 각 blob이 하위 폴더에 저장됩니다.
마지막 수정일 2026년 11월 20일