> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 개발 환경 설정 (로컬)

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

## 사전 요구 사항

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

* 공식 Community Edition 소스 코드는 [GitHub Overleaf Official](https://github.com/overleaf/overleaf/tree)에 있습니다. 
* Overleaf-CEP의 소스 코드는 [GitHub Yu-i-i/Overleaf](https://github.com/yu-i-i/overleaf-cep)에서 확인할 수 있습니다.
* Overleaf Pro Edition은 [GitHub Ayaka-notes/overleaf-pro](https://github.com/ayaka-notes/overleaf-pro)에서 이용할 수 있습니다.

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

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

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

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

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

## 구성 튜토리얼

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

<Steps>
  <Step title="소스 코드 가져오기">
    먼저 저장소를 클론합니다.

    ```bash title="bash" theme={null}
    git clone https://github.com/ayaka-notes/overleaf-pro.git
    cd overleaf-pro
    ```
  </Step>

  <Step title="`package-lock.json` 동기화">
    Overleaf는 [내부 저장소](http://github.com/overleaf/internal)에서 개발되기 때문에, 개발 과정상의 문제로 `package-lock.json` 파일이 동기화되지 않은 상태일 가능성이 매우 높습니다. 다음 명령을 실행하여 동기화해야 합니다(로컬 nodejs 환경이 있는 경우).

    ```bash title="bash" theme={null}
    npm install --package-lock-only --ignore-scripts
    ```

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

    ```bash title="bash" theme={null}
    docker run --rm \
      -v "$(pwd)":/workspace \
      -w /workspace \
      node:22.18.0 \
      npm install --package-lock-only --ignore-scripts
    ```
  </Step>

  <Step title="개발 이미지 빌드">
    Overleaf는 개발 스크립트를 저장하기 위한 전용 디렉터리 `/develop`을 제공합니다. 서비스를 빌드하기만 하면 됩니다.

    ```bash title="bash" theme={null}
    cd ./develop
    bin/build
    ```

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

  <Step title="모든 마이크로서비스 시작">
    그런 다음 서비스를 시작합니다.

    ```bash title="bash" theme={null}
    bin/up
    ```

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

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

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

  ```text theme={null}
  ADMIN_PRIVILEGE_AVAILABLE=true
  ```
</Info>

### TeX Live

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

```text theme={null}
docker build texlive -t texlive-full
```

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

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

### 개발

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

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

```text theme={null}
bin/dev
```

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

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

```text theme={null}
bin/dev [service1] [service2] ... [serviceN]
```

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

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

### 디버깅

\_개발 모드\_로 실행하면 대부분의 서비스가 디버깅 포트를 노출하며, 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` 스크립트를 제공하지만, 몇 가지 의존성을 설치해야 합니다.

```bash theme={null}
sudo npm install -g bunyan
# Or sudo apt install node-bunyan 
```

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

```text theme={null}
docker compose logs -f [service name]
```

### 기타 도구

모든 작업을 마쳤다면 [다음 섹션](/ko/dev/environment/setup-develop-tools)을 참고하여 overleaf 개발 환경에 디버그 도구를 추가할 수 있습니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.