메인 콘텐츠로 건너뛰기

사전 요구 사항

Overleaf는 모든 서비스가 Docker에서 실행되는 전형적인 마이크로서비스 아키텍처 오픈 소스 프로젝트입니다. Overleaf 개발 환경을 구축하려면 강력한 서버가 필요합니다. 20개 이상의 컨테이너를 동시에 실행해야 하므로 최소 8코어, 16GB RAM 구성을 권장합니다.
CPU 코어가 8개 이상인 서버는 보통 비용이 많이 들기 때문에, 개발에는 로컬 컴퓨터를 사용하는 것을 강력히 권장합니다.
또한 개발자라면 이미 Docker 설치에 익숙하리라 생각합니다. 예상치 못한 오류가 발생할 가능성을 줄이기 위해 최신의 안정적인 Ubuntu LTS(예: 2025–2026년 기준 Ubuntu 24.04)와 최신 Docker를 사용하여 개발할 것을 강력히 권장합니다. 요약하면 다음이 필요합니다.
  • 개발용 고성능 서버/데스크톱
  • 최신의 안정적인 Ubuntu LTS(예: Ubuntu 24.04)
  • Docker 및 Git 환경

구성 튜토리얼

여기서는 Ayakaleaf Pro를 예로 Overleaf 개발 환경을 설정하는 방법을 설명합니다. 별도 언급이 없으면 아래의 모든 명령은 develop 디렉터리에서 실행합니다.
1

소스 코드 가져오기

먼저 저장소를 클론합니다.
bash
2

yarn.lock 동기화

이 저장소는 Yarn 4를 사용하며(루트 package.json의 packageManager), yarn.lock이 package.json 파일과 맞지 않을 수 있습니다. 처음 클론한 후와 package.json을 변경할 때마다 동기화하세요.
bash
bin/sync는 node:24.18.1 컨테이너에서 yarn install --mode=update-lockfile을 실행하므로 호스트에 Node.js가 필요 없습니다. 변경된 yarn.lock은 커밋하지 마세요.
3

개발 이미지 빌드

서비스를 빌드합니다.
bash
서비스를 병렬로 빌드하는 동안 Docker의 RAM이 부족해지면, 이 디렉터리에 COMPOSE_PARALLEL_LIMIT=1을 포함하는 .env 파일을 만드세요.
4

번역 적용

Ayakaleaf Pro의 모듈은 번역을 services/web/locales/locales_patches/에 보관하며, 커밋된 로케일 파일에는 이 번역이 없습니다. 처음 시작하기 전에 한 번 적용하세요. 그렇지 않으면 이 모듈의 페이지에 텍스트 대신 about_to_permanently_delete_accounts 같은 키가 표시됩니다.
bash
호스트에 jq가 필요합니다. 번역을 추가하거나 브랜치를 바꾼 뒤에는 다시 실행하세요. i18n 번역 업데이트를 참고하세요.
5

모든 마이크로서비스 시작

그런 다음 서비스를 시작합니다.
bash
서비스가 실행되면 http://localhost/launchpad를 열어 첫 번째 관리자 계정을 만드세요. OVERLEAF_PORT를 변경했다면 포트를 붙이세요(아래 참고).
LDAP는 기본으로 켜져 있습니다(dev.rc의 LDAP_ENABLED=true). 이 경우 launchpad에 LDAP 관리자 양식이 표시됩니다. 이메일만 입력받으며, 그 관리자는 이후 LDAP로 로그인합니다. 예를 들어 professor / professor(professor@planetexpress.com)입니다. 테스트 사용자는 develop/authentication/README.md에 나와 있습니다. 대신 비밀번호가 있는 로컬 관리자를 만들려면 LDAP_ENABLED=false와 SAML_ENABLED=false를 설정하세요.
develop/dev.env에 이미 ADMIN_PRIVILEGE_AVAILABLE=true가 설정되어 있으므로 관리자는 추가 설정 없이 관리자 패널을 열 수 있습니다.

구성(dev.rc)

dev.env 옆의 develop/dev.rc에는 Overleaf Toolkit의 overleaf.rc처럼 개발 환경의 스위치가 들어 있습니다. 값을 바꾼 뒤 bin/dev를 다시 실행하면 적용되며, 끈 기능은 해당 컨테이너도 중지합니다. 각 기능은 docker-compose.yml과 기타 파일을 자체 폴더에 둡니다: authentication/ldap, authentication/saml, mail, s3, hoppscotch, grafana. 환경 변수가 없는 web 설정이 필요한 기능은 /etc/overleaf/settings.d/에 파일을 마운트하고, develop/settings.dev-env.cjs가 이를 모두 병합합니다. 모든 bin/* 스크립트는 켜져 있는 기능의 파일을 추가하는 bin/docker-compose를 거칩니다. 직접 compose 명령이 필요할 때는 docker compose 대신 bin/docker-compose를 사용하세요.
로컬 볼륨과 RustFS는 별개의 저장소입니다. S3_ENABLED=true로 만든 프로젝트는 false로 전환하면 기록과 바이너리 파일이 없으며, 그 반대도 마찬가지입니다. S3_ENABLED가 생기기 전부터 실행되던 환경의 파일을 RustFS로 복사하려면 develop/README.md의 “Moving existing data into RustFS”를 따르세요.

포트

사이트, RustFS 콘솔, Hoppscotch는 호스트의 127.0.0.1에서 수신합니다. 원격 머신에서는 먼저 포트를 포워딩하세요. 예: ssh -L 9001:localhost:9001 <host>. 사이트는 dev.rc의 OVERLEAF_PORT를 사용하므로, 변경했다면 아래 주소에 포트를 붙이세요. Mailpit, Grafana, Mongo Express, RedisInsight는 webpack-dev-server를 통해 사이트의 자체 경로에서 제공되므로 별도 포트가 필요 없습니다. 로그인하면 사이트 내비게이션 바의 Dev tools 메뉴가 이들로 연결되며, dev.rc에서 기능이 꺼진 페이지는 빠집니다. 각 도구가 하는 일은 개발 도구 설정에 나와 있습니다. S3 API(포트 9000)와 SMTP(포트 1025)는 Docker 네트워크 안에서만 접근할 수 있습니다. Mongo(27017), Redis(6379), Mongo Express(8081), RedisInsight(5540), git-bridge(8000)는 호스트의 127.0.0.1에만 공개됩니다.

TeX Live

샌드박스 컴파일은 기본으로 켜져 있습니다. develop/dev.env가 SANDBOXED_COMPILES=true와 이미지 ghcr.io/ayaka-notes/texlive-full:2026.1, ghcr.io/ayaka-notes/texlive-full:2025.1을 설정합니다. clsi는 이미지를 직접 받지 않으므로 한 번 받아 두세요.
자세한 내용은 샌드박스 컴파일 설정을 참고하세요.
SANDBOXED_COMPILES가 꺼져 있을 때 만든 프로젝트에는 TeX Live 이미지가 없습니다. 기본 이미지로 계속 컴파일되지만, 코드와 PDF 사이 이동은 “That didn’t work. Recompile and try again.” 오류로 실패합니다. 이런 프로젝트에 TEX_LIVE_DOCKER_IMAGE의 이미지를 한 번 지정하세요. --commit 없이 실행하면 스크립트는 변경할 내용만 보여 줍니다.
dev.env는 PANDOC_IMAGE=overleaf-pandoc:local로 Pandoc 변환도 켭니다. 저장소 루트에서 이 이미지를 한 번 빌드하세요.
macOS 호스트에서 컴파일하려면 develop 디렉터리에 DOCKER_SOCKET_PATH=/var/run/docker.sock.raw가 들어 있는 .env 파일을 만들어 Docker 소켓 경로를 재정의해야 할 수 있습니다.

개발

코드를 변경할 때마다 bin/build && bin/up을 실행하지 않으려면, 코드 변경 시 서비스가 자동으로 업데이트되는 _개발 모드_로 Overleaf Community Edition을 실행할 수 있습니다. 이를 위해 포함된 bin/dev 스크립트를 사용하세요.
이렇게 하면 node --watch를 사용하여 모든 서비스가 시작되며, 코드를 자동으로 모니터링하고 필요에 따라 서비스를 다시 시작합니다. dev.rc를 변경한 후 다시 실행하세요. 성능을 높이기 위해 bin/dev 스크립트에 공백으로 구분된 목록을 전달하여 일부 서비스만 개발 모드로 시작할 수 있습니다.
web 서비스를 _개발 모드_로 시작하면 백엔드 코드가 변경될 때만 web 서비스가 업데이트됩니다. 프런트엔드 코드도 자동으로 업데이트하려면 webpack 서비스도 _개발 모드_로 시작해야 합니다.
서비스 이름을 지정하지 않으면 모든 서비스가 개발 모드로 시작됩니다. 번역을 추가하거나 브랜치를 바꾼 뒤에는 bin/i18n을 실행하세요. i18n 번역 업데이트를 참고하세요.

디버깅

_개발 모드_로 실행하면 대부분의 서비스가 디버깅 포트를 열어, Chrome Dev Tools의 인스펙터나 IDE에 통합된 디버거를 연결할 수 있습니다. 다음 표는 각 서비스가 호스트 머신의 127.0.0.1에 여는 포트입니다. Chrome의 _원격 디버깅_으로 서비스에 연결하려면 chrome://inspect/로 이동하여 _Discover network targets_가 선택되어 있는지 확인하세요. 다음으로 _Configure…_를 클릭하고 디버거를 연결하려는 각 서비스에 대해 localhost:[service port] 항목을 추가합니다. 항목을 추가하면 해당 서비스가 _Remote Target_으로 표시되며, 이를 검사하고 디버깅할 수 있습니다.

로깅

스크립트 bin/logs는 로그를 따라가며 bunyan으로 서식을 지정합니다. ggrep도 필요한데, 이는 macOS에서 Homebrew로 설치한 GNU grep의 이름이며 Ubuntu에는 ggrep 명령이 없습니다.
또는 다음 명령으로 직접 실행할 수 있습니다.
dev.rc의 기능 서비스(mailpit, rustfs, ldap, saml, hoppscotch, 그리고 Prometheus, Loki, 익스포터가 포함된 grafana)도 찾을 수 있도록 docker compose 대신 bin/docker-compose를 사용하세요. GRAFANA_ENABLED=true이면 모든 컨테이너의 로그가 Grafana에도 있으며, 서비스, 레벨, 텍스트로 필터링할 수 있습니다. 개발 도구 설정을 참고하세요.

기타 도구

모든 작업을 마쳤다면 다음 섹션을 참고하여 overleaf 개발 환경에 디버그 도구를 추가할 수 있습니다.
마지막 수정일 2026년 11월 20일