개발 환경 설정 (로컬)

로컬 서버나 데스크톱에서 개발 환경을 설정합니다.

​

사전 요구 사항

Overleaf는 모든 서비스가 Docker에서 실행되는 전형적인 마이크로서비스 아키텍처 오픈 소스 프로젝트입니다.

• 공식 Community Edition 소스 코드는 GitHub Overleaf Official에 있습니다.
• Overleaf-CEP의 소스 코드는 GitHub Yu-i-i/Overleaf에서 확인할 수 있습니다.
• Overleaf Pro Edition은 GitHub Ayaka-notes/overleaf-pro에서 이용할 수 있습니다.

Overleaf 개발 환경을 구축하려면 강력한 서버가 필요합니다. 20개 이상의 컨테이너를 동시에 실행해야 하므로 최소 8코어, 16GB RAM 구성을 권장합니다.

CPU 코어가 8개 이상인 서버는 보통 비용이 많이 들기 때문에, 개발에는 로컬 컴퓨터를 사용하는 것을 강력히 권장합니다.

또한 개발자라면 이미 Docker 설치에 익숙하리라 생각합니다. 예상치 못한 오류가 발생할 가능성을 줄이기 위해 최신의 안정적인 Ubuntu LTS(예: 2025–2026년 기준 Ubuntu 24.04)와 최신 Docker를 사용하여 개발할 것을 강력히 권장합니다.

요약하면 다음이 필요합니다.

• 개발용 고성능 서버/데스크톱
• 최신의 안정적인 Ubuntu LTS(예: Ubuntu 24.04)
• Docker 및 Git 환경

​

구성 튜토리얼

여기서는 overleaf-cep를 예로 들어 Overleaf 개발 환경을 구성하는 방법을 보여드립니다.

1. 소스 코드 가져오기

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

   bash

   git clone https://github.com/ayaka-notes/overleaf-pro.git
   cd overleaf-pro
   
2. package-lock.json 동기화

   Overleaf는 내부 저장소에서 개발되기 때문에, 개발 과정상의 문제로 package-lock.json 파일이 동기화되지 않은 상태일 가능성이 매우 높습니다. 다음 명령을 실행하여 동기화해야 합니다(로컬 nodejs 환경이 있는 경우).

   bash

   npm install --package-lock-only --ignore-scripts
   

   nodejs가 설치되어 있지 않더라도 걱정하지 마세요. docker를 사용하여 동일한 명령을 바로 실행할 수 있습니다. Overleaf 저장소의 루트에서 실행하세요.

   bash

   docker run --rm \
     -v "$(pwd)":/workspace \
     -w /workspace \
     node:22.18.0 \
     npm install --package-lock-only --ignore-scripts
   
3. 개발 이미지 빌드

   Overleaf는 개발 스크립트를 저장하기 위한 전용 디렉터리 /develop을 제공합니다. 서비스를 빌드하기만 하면 됩니다.

   bash

   cd ./develop
   bin/build
   

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

4. 모든 마이크로서비스 시작

   그런 다음 서비스를 시작합니다.

   bash

   bin/up
   

   서비스가 실행되면 http://localhost/launchpad를 열어 첫 번째 관리자 계정을 만드세요.

   bin/dev 명령을 실행하기 전에 반드시 bin/up을 실행해야 합니다. 그렇지 않으면 일련의 권한 문제가 발생할 수 있습니다.

기본적으로 관리자 권한은 사용할 수 없습니다. develop/dev.env에 다음을 추가해야 합니다. 그러면 관리자 패널에 접근할 수 있습니다.

ADMIN_PRIVILEGE_AVAILABLE=true

​

TeX Live

PDF를 컴파일하려면 Docker 내부에서 컴파일을 처리할 TeX Live 이미지를 빌드해야 합니다.

docker build texlive -t texlive-full

macOS 호스트에서 컴파일하려면, 이 디렉터리에 DOCKER_SOCKET_PATH=/var/run/docker.sock.raw를 포함하는 .env 파일을 만들어 Docker 소켓 경로를 재정의해야 할 수 있습니다.

또한 ayaka-notes/texlive-full을 사용해도 좋으며, texlive의 최소 버전인 base 태그를 사용할 수 있습니다.

​

개발

코드를 변경할 때마다 bin/build && bin/up을 실행하지 않으려면, 코드 변경 시 서비스가 자동으로 업데이트되는 _개발 모드_로 Overleaf Community Edition을 실행할 수 있습니다.

이를 위해 포함된 bin/dev 스크립트를 사용하세요.

bin/dev

이렇게 하면 node --watch를 사용하여 모든 서비스가 시작되며, 코드를 자동으로 모니터링하고 필요에 따라 서비스를 다시 시작합니다.

성능을 높이기 위해 bin/dev 스크립트에 공백으로 구분된 목록을 전달하여 일부 서비스만 개발 모드로 시작할 수 있습니다.

bin/dev [service1] [service2] ... [serviceN]

web 서비스를 _개발 모드_로 시작하면 백엔드 코드가 변경될 때만 web 서비스가 업데이트됩니다. 프런트엔드 코드도 자동으로 업데이트하려면 webpack 서비스도 _개발 모드_로 시작해야 합니다.

서비스 이름을 지정하지 않으면 모든 서비스가 개발 모드로 시작됩니다.

​

디버깅

_개발 모드_로 실행하면 대부분의 서비스가 디버깅 포트를 노출하며, Chrome 개발자 도구의 인스펙터나 IDE에 통합된 디버거 등을 연결할 수 있습니다. 다음 표는 각 서비스에 대해 호스트 머신에 노출되는 포트를 보여줍니다.

서비스	포트
web	9229
clsi	9230
chat	9231
contacts	9232
docstore	9233
document-updater	9234
filestore	9235
notifications	9236
real-time	9237
references	9238
history-v1	9239
project-history	9240
linked-url-proxy	9241

Chrome의 _원격 디버깅_으로 서비스에 연결하려면 chrome://inspect/로 이동하여 _Discover network targets_가 선택되어 있는지 확인하세요. 다음으로 _Configure…_를 클릭하고 디버거를 연결하려는 각 서비스에 대해 localhost:[service port] 항목을 추가합니다.

항목을 추가하면 해당 서비스가 _Remote Target_으로 표시되며, 이를 검사하고 디버깅할 수 있습니다.

​

로깅

개발 환경에서 overleaf는 bin/logs 스크립트를 제공하지만, 몇 가지 의존성을 설치해야 합니다.

sudo npm install -g bunyan
# Or sudo apt install node-bunyan 

또는 다음 명령으로 직접 실행할 수 있습니다.

docker compose logs -f [service name]

​

기타 도구

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