> ## 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.

# MongoDB 업데이트

<Info>
  Server CE/Server Pro의 새 릴리스는 지원되는 MongoDB 버전의 변경 사항을 [릴리스 노트](https://docs.overleaf.com/on-premises/release-notes)에 명시합니다.
</Info>

### MongoDB를 업데이트해야 하나요?

Server CE/Server Pro 인스턴스를 업그레이드할 계획인 경우에**만** MongoDB 버전 업데이트를 고려해야 합니다.

현재(또는 목표) 버전에 권장되는 것보다 최신 버전의 MongoDB를 실행하고 있다면 아무것도 변경할 필요가 없습니다.

<Warning>
  MongoDB 버전을 절대로 다운그레이드해서는 안 됩니다.
</Warning>

현재 MongoDB 버전과 관련이 있다고 생각되는 특정 문제가 발생하면, Server CE 사용자는 언제든지 [이슈를 등록](https://github.com/overleaf/overleaf/issues)하고, Server Pro 사용자는 Overleaf Support에 문의하세요.

### MongoDB 버전 확인

`mongo` 셸을 열면 즉시 현재 버전이 출력됩니다.

Overleaf Toolkit 사용자:

```bash theme={null}
bin/docker-compose exec mongo mongod --version
db version v5.0.24
Build Info: {
    "version": "5.0.24",
    "gitVersion": "f034f0c51b3dffef4b8c9452d77ede9888f28f66",
    "openSSLVersion": "OpenSSL 1.1.1f  31 Mar 2020",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2004",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}
```

Docker Compose 사용자:

```bash theme={null}
docker compose exec mongo mongod --version
db version v5.0.24
Build Info: {
    "version": "5.0.24",
    "gitVersion": "f034f0c51b3dffef4b8c9452d77ede9888f28f66",
    "openSSLVersion": "OpenSSL 1.1.1f  31 Mar 2020",
    "modules": [],
    "allocator": "tcmalloc",
    "environment": {
        "distmod": "ubuntu2004",
        "distarch": "x86_64",
        "target_arch": "x86_64"
    }
}

```

### 업데이트 과정

Server CE/Server Pro 인스턴스를 업그레이드하는 동안 MongoDB 버전을 업데이트하는 과정은 다음과 같습니다:

1. 업그레이드할 Server CE/Server Pro 버전을 결정합니다.
2. 해당 Overleaf Server CE/Server Pro 릴리스에서 권장하는 MongoDB 버전을 찾습니다.
3. 안내에 따라 MongoDB를 목표 버전으로 업그레이드합니다.
4. Server CE/Server Pro 이미지 버전을 업그레이드하고 인스턴스를 다시 시작합니다.

**Server CE/Server Pro**는 항상 지원이 보장되므로 항상 사용 가능한 최신 버전으로 업그레이드할 것을 권장합니다(Server Pro 사용자만 해당).

<Danger>
  Server CE/Pro를 업그레이드할 때는 **다음** 메이저 버전의 최신 릴리스로 업그레이드하기 **전에** 배포된 메이저 버전의 최신 릴리스로 먼저 업그레이드할 것을 권장합니다. 배포가 최신 버전보다 메이저 버전이 두 개 이상 뒤처진 경우 여러 단계에 걸친 업그레이드를 수행해야 합니다.

  예를 들어 3.5.10을 실행 중이라면 3.5.13으로 업그레이드 -> 전체 프로젝트 기록 마이그레이션 수행 -> 4.2.9 -> 5.5.4 순서로 업그레이드해야 합니다.

  메이저 버전을 **절대로** 건너뛰어서는 안 됩니다(3.5.10 -> 5.5.4). Toolkit을 사용하고 있고 최신 버전보다 메이저 버전이 두 개 이상 뒤처져 있다면, 여러 단계의 수동 업그레이드를 수행해야 하므로 `bin/upgrade` 스크립트를 사용해서는 **안 됩니다**.
</Danger>

<Warning>
  필요한 경우 롤백할 수 있도록 모든 메이저 버전 업그레이드 **전에** [일관된 백업](/ko/on-premises/maintenance/data-and-backups#performing-a-consistent-backup)을 만들어 두는 것이 중요합니다.
</Warning>

#### 버전 지원 정보

이전 버전을 사용하기로 결정한 경우를 위해 이 표는 이전 Server CE/Server Pro 릴리스에 권장되는 MongoDB 버전을 보여 주지만, MongoDB 버전을 **절대로** 다운그레이드해서는 안 됩니다.

<div style={{ overflowX: "auto" }}><table style={{ display: "table", width: "100%" }}><thead><tr><th width="175">Server CE/Server Pro</th><th width="139" style={{ textAlign: "center" }}>MongoDB 버전</th><th style={{ textAlign: "center" }}>최소 기능 호환성 버전</th><th style={{ textAlign: "center" }}>Node.js 드라이버가 지원하는 최대 버전</th></tr></thead><tbody><tr><td>2.0.x</td><td style={{ textAlign: "center" }}>3.4</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>2.1.x \~ 2.4.x</td><td style={{ textAlign: "center" }}>3.6</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=2.5.0</td><td style={{ textAlign: "center" }}>4.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=3.1.0</td><td style={{ textAlign: "center" }}>4.2</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=3.2.0</td><td style={{ textAlign: "center" }}>4.4</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=4.2.0</td><td style={{ textAlign: "center" }}>5.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=5.1.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>-</td><td style={{ textAlign: "center" }}>-</td></tr><tr><td>>=5.3.1</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>5.0</td><td style={{ textAlign: "center" }}>8.0</td></tr><tr><td>>=5.5.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>6.0</td><td style={{ textAlign: "center" }}>8.0</td></tr><tr><td>6.0.0</td><td style={{ textAlign: "center" }}>8.0</td><td style={{ textAlign: "center" }}>8.0</td><td style={{ textAlign: "center" }}>8.0</td></tr></tbody></table></div>

<Danger>
  위의 최소 기능 호환성 버전은 표시된 Overleaf 버전과 함께 사용하도록 권장되는 해당 MongoDB 버전을 기준으로 합니다. 더 높은 버전을 사용하려는 경우 MongoDB 자체의 최소 요구 사항이 적용됩니다.
</Danger>

MongoDB와 함께 사용할 수 있는 MongoDB Node.js 드라이버의 지원 버전을 명시한 호환성 표는 [여기](https://www.mongodb.com/docs/drivers/node/current/reference/compatibility/)에서 볼 수 있습니다.

각 MongoDB 버전의 지원 종료(end-of-life) 상태는 [여기](https://endoflife.date/mongodb)에서 볼 수 있습니다.

#### MongoDB 업그레이드

MongoDB는 **단계별 업그레이드**가 필요합니다. 즉, 예를 들어 `4.0`에서 `5.0`으로 바로 업그레이드할 수 없습니다. 먼저 `4.2`에서 `4.4`로 업데이트한 다음 `5.0`으로 업데이트해야 합니다.

<Info>
  MongoDB는 안정 버전에 짝수를 사용합니다.
</Info>

#### **Docker 외부에서 MongoDB를 실행하는 경우의 업데이트 안내**

다음은 MongoDB를 업그레이드할 때 참고할 mongodb.com의 업데이트 안내 링크입니다.

* [MongoDB 릴리스 노트 - MongoDB를 `4.2`에서 `4.4`로 업그레이드](https://www.mongodb.com/docs/v4.4/release-notes/4.4-upgrade-standalone/)
* [MongoDB 릴리스 노트 - MongoDB를 `4.4`에서 `5.0`으로 업그레이드](https://www.mongodb.com/docs/v5.0/release-notes/5.0-upgrade-replica-set/)
* [MongoDB 릴리스 노트 - MongoDB를 `5.0`에서 `6.0`으로 업그레이드](https://www.mongodb.com/docs/v6.0/release-notes/6.0-upgrade-replica-set/)
* [MongoDB 릴리스 노트 - MongoDB를 `6.0`에서 `7.0`으로 업그레이드](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set)
* [MongoDB 릴리스 노트 - MongoDB를 `7.0`에서 `8.0`으로 업그레이드](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set)

<Info>
  `5.0` 이상의 안내는 독립 실행형(standalone)이 아닌 복제본 세트(replica set) 설치를 기준으로 합니다. Server Pro/CE 4.0.1 이상은 트랜잭션을 사용하므로 MongoDB를 복제본 세트로 실행해야 합니다.
</Info>

<Warning>
  MongoDB 3.2 \~ 4.2 문서는 이제 [https://www.mongodb.com/docs/legacy/](https://www.mongodb.com/docs/legacy/)에서 볼 수 있습니다.
</Warning>

**기본 안내**

대부분의 경우 실제로 mongo 버전을 업데이트하기 전에 호환성 플래그를 설정해야 합니다. 단계는 다음과 같습니다:

1. MongoDB 릴리스 노트에 설명된 대로 호환성 플래그를 설정합니다(아래 예시 참조).
2. 그런 다음 mongo 이미지를 업데이트합니다:
   1. **Toolkit 사용자** `MONGO_VERSION`을 업데이트합니다. 예: `MONGO_VERSION=6.0`
   2. **Docker Compose 사용자** `mongo` 이미지 태그의 버전을 업데이트합니다.\
      예: `services -> mongo -> image: mongo:6.0`

**예시: MongoDB를 `5.0`에서 `6.0`으로 업그레이드**

먼저 MongoDB `6.0`을 실행 중인지 확인해 보겠습니다:

Overleaf Toolkit 사용자:

```bash theme={null}
bin/docker-compose exec mongo mongod --version
# db version v5.0.24
```

Docker Compose 사용자:

```bash theme={null}
docker compose exec mongo mongod --version
# db version v5.0.24
```

[업그레이드 안내](https://docs.mongodb.com/manual/release-notes/3.6-upgrade-standalone/#upgrade-version-path)에 따르면 유일한 요구 사항은 `featureCompatibilityVersion`을 `5.0`으로 설정하는 것입니다. MongoDB 셸을 열고 안내된 명령을 실행하여 설정합니다:

Overleaf Toolkit 사용자:

```bash theme={null}
bin/mongo
# MongoDB shell version v5.0.24
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "5.0" } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

<Info>
  Docker Compose 사용자는 `docker compose exec mongo mongosh`를 실행하여 셸을 열고 Toolkit 사용자와 같은 명령을 실행할 수 있습니다.
</Info>

Overleaf Toolkit 사용자:

그런 다음 `bin/stop` 명령으로 Server CE/Server Pro 및 MongoDB 인스턴스를 중지하고, `config/overleaf.rc`에서 `MONGO_VERSION=6.0`을 설정한 후, `bin/up mongo`로 `mongo` 서비스를 다시 시작하여 업데이트가 원활하게 진행되었는지 확인합니다.

마지막으로 Server CE/Server Pro 이미지 버전을 목표 버전으로 업데이트하고 `bin/up -d` 명령으로 모든 서비스를 다시 생성합니다.

Docker Compose 사용자:

그런 다음 `docker compose stop` 명령으로 Server CE/Server Pro 및 MongoDB 인스턴스를 중지하고, [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) 파일이 `image: mongo:6.0`을 사용하도록 업데이트한 후, `docker compose up mongo` 명령으로 `mongo` 서비스를 다시 시작하여 업데이트가 원활하게 진행되었는지 확인합니다.

마지막으로 Server CE/Server Pro 이미지 버전을 목표 버전으로 업데이트하고 `docker compose up` 명령으로 모든 서비스를 다시 생성합니다.

<strong>예시: MongoDB를 `6.0`에서 `7.0`으로 업그레이드(Toolkit 사용자)</strong>

먼저 위의 `mongod --version` 명령을 사용해 MongoDB `6.0`을 실행 중인지 확인합니다.

[업그레이드 안내](https://www.mongodb.com/docs/manual/release-notes/7.0-upgrade-replica-set/#std-label-7.0-upgrade-replica-set)에 따르면 유일한 요구 사항은 `featureCompatibilityVersion`을 `6.0`으로 설정하는 것입니다. MongoDB 셸을 열고 `db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })` 명령을 실행하여 설정합니다.

Overleaf Toolkit 사용자:

```bash theme={null}
bin/mongo
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "6.0" } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

그런 다음 `bin/stop` 명령으로 Server CE/Server Pro 및 MongoDB 인스턴스를 중지하고, `config/overleaf.rc`에서 `MONGO_VERSION=7.0`을 설정한 후, `bin/up mongo`로 `mongo` 서비스를 다시 시작하여 업데이트가 원활하게 진행되었는지 확인합니다.

마지막으로 Server CE/Server Pro 이미지 버전을 목표 버전으로 업데이트하고 `bin/up -d` 명령으로 모든 서비스를 다시 생성합니다.

<strong>예시: MongoDB를 `7.0`에서 `8.0`으로 업그레이드(Toolkit 사용자)</strong>

먼저 위의 `mongod --version` 명령을 사용해 MongoDB `7.0`을 실행 중인지 확인합니다.

[업그레이드 안내](https://www.mongodb.com/docs/manual/release-notes/8.0-upgrade-replica-set/#std-label-8.0-upgrade-replica-set)에 따르면 유일한 요구 사항은 `featureCompatibilityVersion`을 `7.0`으로 설정하는 것입니다. MongoDB 셸을 열고 `db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })` 명령을 실행하여 설정합니다. 이제 추가로 `confirm: true` 매개변수가 필요하다는 점에 유의하세요.

```bash theme={null}
bin/mongo
# ...
# overleaf:PRIMARY> db.adminCommand( { setFeatureCompatibilityVersion: "7.0", confirm: true } )
# { 
# "ok" : 1,
# ...
# }
overleaf:PRIMARY> exit
# bye
```

그런 다음 `bin/stop` 명령으로 Server CE/Server Pro 및 MongoDB 인스턴스를 중지하고, `config/overleaf.rc`에서 `MONGO_VERSION=8.0`을 설정한 후, `bin/up mongo`로 `mongo` 서비스를 다시 시작하여 업데이트가 원활하게 진행되었는지 확인합니다.

마지막으로 Server CE/Server Pro 이미지 버전을 목표 버전으로 업데이트하고 `bin/up -d` 명령으로 모든 서비스를 다시 생성합니다.

#### docker compose 사용자를 위한 동등한 명령

docker compose 사용자의 경우 동등한 명령은 다음과 같습니다:

* `docker compose exec mongo mongod --version`: mongo 버전 표시
* `docker compose exec mongo mongosh`: 관리 명령을 위한 mongo 셸 시작
* `docker compose stop`: 서버 중지
* [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) 파일이 `image: mongo:6.0`을 사용하도록 편집하여 mongo 버전 업그레이드
* `docker compose up mongo`: mongo 서비스를 다시 시작하고 업데이트가 원활하게 진행되었는지 확인
* [`docker-compose.yml`](https://github.com/overleaf/overleaf/blob/4b1babd4ea634ab12c54e9a9aea7db0e8a500941/docker-compose.yml) 파일이 `image: sharelatex:VERSION`을 사용하도록 편집하여 이미지 버전 업그레이드
* `docker compose up`: 모든 서비스 다시 생성

### 사용자 지정 역할 만들기

버전 `5.5.1`에서 MongoDB의 기능 호환성 버전을 확인하는 시작 검사가 도입되었습니다. MongoDB 데이터베이스가 인증(예: 기본 인증)을 사용하는 경우 `sharelatex` 컨테이너가 시작되지 않고 "*not authorized on admin to execute command*" 권한 오류가 표시될 수 있습니다.

이 문제를 해결하려면 아래 안내에 따라 MongoDB에서 새 역할을 만들어 데이터베이스 접근에 사용하는 사용자 계정에 할당하거나, `ALLOW_MONGO_ADMIN_CHECK_FAILURES=true`를 설정하여 검사가 실패해도 배포 시작이 차단되지 않도록 할 수 있습니다.

<Check>
  이 새 역할은 클러스터 전체의 MongoDB 서버 매개변수를 읽는 권한**만** 부여하며, 모니터링 용도로도 재사용할 수 있습니다.
</Check>

```bash wrap theme={null}
# Toolkit users
$ bin/docker-compose exec -it mongo mongosh -u {{YOUR-ADMIN-USERNAME}} -p

# Switch to the "admin" database using
overleaf [direct: primary] sharelatex> use admin
switched to db admin
overleaf [direct: primary] admin> 

# Create a new role with permission to use "getParamter". Copy and paste the function below into the shell and press the return key

db.createRole(
  {
    role: "clusterParameterReader",
    privileges: [
      {
        resource: { cluster: true },
        actions: ["getParameter"]    
      }
    ],
    roles: [] 
  }
);

# Switch back to the "sharelatex" database 
use sharelatex
switched to db sharelatex
overleaf [direct: primary] sharelatex> 

# Assign the new "clusterParameterReader" role to your database user by copy and pasting the function below into the shell and press the return key 
db.grantRolesToUser(
  "{{YOUR-DATABASE-USER}}",
  [
    { role: "clusterParameterReader", db: "admin" }
  ]
);

# Type exit then return to exit the MongoDB shell
# Run bin/up -d to start the deployment stack
$ bin/up -d
```


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