Обновление MongoDB

В примечаниях к выпуску каждого нового выпуска Server CE/Server Pro указываются все изменения поддерживаемой версии MongoDB.

​

Нужно ли обновлять MongoDB?

Обновлять версию MongoDB следует рассматривать только в том случае, если вы планируете обновить свой экземпляр Server CE/Server Pro.

Если вы используете версию MongoDB новее рекомендованной для вашей текущей (или целевой) версии, ничего менять не нужно.

Никогда не понижайте версию MongoDB.

Если вы столкнулись с конкретной проблемой, которая, по вашему мнению, может быть связана с текущей версией MongoDB, вы можете создать issue, если вы пользователь Server CE, или обратиться в службу поддержки Overleaf, если вы пользователь Server Pro.

​

Проверка версии MongoDB

При открытии оболочки mongo текущая версия выводится сразу.

Пользователи Overleaf Toolkit:

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:

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"
    }
}

​

Процесс обновления

Обновление версии MongoDB при обновлении экземпляра Server CE/Server Pro выполняется следующим образом:

1. Определите версию Server CE/Server Pro, до которой планируете обновиться.
2. Найдите версию MongoDB, рекомендованную для этого конкретного выпуска Overleaf Server CE/Server Pro.
3. Следуя инструкциям, обновите MongoDB до целевой версии.
4. Обновите версию образа Server CE/Server Pro и перезапустите экземпляр.

Мы рекомендуем всегда обновлять Server CE/Server Pro до последней доступной версии, поскольку её поддержка всегда гарантирована (только для пользователей Server Pro).

При обновлении Server CE/Pro мы рекомендуем сначала обновиться до последнего выпуска развёрнутой мажорной версии, прежде чем переходить на последний выпуск следующей мажорной версии. Если ваше развёртывание отстаёт от последней версии более чем на одну мажорную версию, потребуется многоэтапное обновление.

Например, если у вас версия 3.5.10, нужно обновиться до 3.5.13 -> выполнить миграцию полной истории проектов (Full Project History) -> 4.2.9 -> 5.5.4.

Никогда не пропускайте мажорные версии (3.5.10 -> 5.5.4). Если вы используете Toolkit и отстаёте от последней версии более чем на одну мажорную версию, не используйте скрипт bin/upgrade, так как вам потребуется выполнить многоэтапное обновление вручную.

Важно создавать согласованную резервную копию перед каждым обновлением мажорной версии, чтобы при необходимости иметь возможность откатиться.

​

Сведения о поддержке версий

Если вы решите перейти на более раннюю версию, в этой таблице приведены рекомендуемые версии MongoDB для более ранних выпусков Server CE/Server Pro, однако никогда не понижайте версию MongoDB.

Server CE/Server Pro	Версия MongoDB	Минимальная версия совместимости функций	Максимальная версия, поддерживаемая драйвером Node.js
2.0.x	3.4	-	-
2.1.x – 2.4.x	3.6	-	-
>=2.5.0	4.0	-	-
>=3.1.0	4.2	-	-
>=3.2.0	4.4	-	-
>=4.2.0	5.0	-	-
>=5.1.0	6.0	-	-
>=5.3.1	6.0	5.0	8.0
>=5.5.0	6.0	6.0	8.0
6.0.0	8.0	8.0	8.0

Указанная выше минимальная версия совместимости функций основана на версии MongoDB, рекомендованной для использования с указанной версией Overleaf. Если вы планируете использовать более новую версию, у MongoDB будут собственные минимальные требования.

Таблицу совместимости с указанием поддерживаемых версий драйвера MongoDB Node.js для использования с MongoDB можно посмотреть здесь.

Статус окончания поддержки (end-of-life) для каждой версии MongoDB можно посмотреть здесь.

​

Обновление MongoDB

MongoDB требует пошагового обновления. Это значит, что нельзя перейти напрямую, скажем, с 4.0 на 5.0. Сначала нужно обновиться с 4.2 до 4.4, а затем до 5.0.

Стабильные версии MongoDB имеют чётные номера.

​

Инструкции по обновлению при запуске MongoDB вне Docker

Ниже приведены ссылки на инструкции по обновлению MongoDB с сайта mongodb.com.

• Примечания к выпуску MongoDB — обновление MongoDB с 4.2 до 4.4
• Примечания к выпуску MongoDB — обновление MongoDB с 4.4 до 5.0
• Примечания к выпуску MongoDB — обновление MongoDB с 5.0 до 6.0
• Примечания к выпуску MongoDB — обновление MongoDB с 6.0 до 7.0
• Примечания к выпуску MongoDB — обновление MongoDB с 7.0 до 8.0

Инструкции для 5.0 и выше относятся к установке в виде набора реплик (replica set), а не автономной установке. Поскольку Server Pro/CE 4.0.1+ использует транзакции, MongoDB необходимо запускать как набор реплик.

Документация по MongoDB с 3.2 по 4.2 теперь доступна по адресу https://www.mongodb.com/docs/legacy/

Основные инструкции

В большинстве случаев перед фактическим обновлением версии 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:

bin/docker-compose exec mongo mongod --version
# db version v5.0.24

Пользователи Docker Compose:

docker compose exec mongo mongod --version
# db version v5.0.24

Согласно инструкциям по обновлению, единственное требование — чтобы для featureCompatibilityVersion было установлено значение 5.0. Для этого откроем оболочку MongoDB и выполним указанную команду:

Пользователи Overleaf Toolkit:

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

Пользователи Docker Compose могут выполнить docker compose exec mongo mongosh, чтобы открыть оболочку, и выполнить те же команды, что и пользователи Toolkit.

Пользователи Overleaf Toolkit:

Затем остановим экземпляры Server CE/Server Pro и MongoDB командой bin/stop, зададим MONGO_VERSION=6.0 в config/overleaf.rc и перезапустим сервис mongo с помощью bin/up mongo), чтобы убедиться, что обновление прошло без проблем.

Наконец, обновим версию образа Server CE/Server Pro до целевой и пересоздадим все сервисы командой bin/up -d.

Пользователи Docker Compose:

Затем остановим экземпляры Server CE/Server Pro и MongoDB командой docker compose stop, изменим файл docker-compose.yml, указав image: mongo:6.0, и перезапустим сервис mongo командой docker compose up mongo, чтобы убедиться, что обновление прошло без проблем.

Наконец, обновим версию образа Server CE/Server Pro до целевой и пересоздадим все сервисы командой docker compose up.

Сначала убедитесь, что используется MongoDB 6.0, с помощью приведённых выше команд mongod --version.

Согласно инструкциям по обновлению, единственное требование — чтобы для featureCompatibilityVersion было установлено значение 6.0. Для этого откроем оболочку MongoDB и выполним команду db.adminCommand({ setFeatureCompatibilityVersion: "6.0" }).

Пользователи Overleaf Toolkit:

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

Затем остановим экземпляры Server CE/Server Pro и MongoDB командой bin/stop, зададим MONGO_VERSION=7.0 в config/overleaf.rc и перезапустим сервис mongo с помощью bin/up mongo), чтобы убедиться, что обновление прошло без проблем.

Наконец, обновим версию образа Server CE/Server Pro до целевой и пересоздадим все сервисы командой bin/up -d.

Сначала убедитесь, что используется MongoDB 7.0, с помощью приведённых выше команд mongod --version.

Согласно инструкциям по обновлению, единственное требование — чтобы для featureCompatibilityVersion было установлено значение 7.0. Для этого откроем оболочку MongoDB и выполним команду db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true }). Обратите внимание, что теперь требуется дополнительный параметр confirm: true.

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

Затем остановим экземпляры Server CE/Server Pro и MongoDB командой bin/stop, зададим MONGO_VERSION=8.0 в config/overleaf.rc и перезапустим сервис mongo с помощью bin/up 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, указав image: mongo:6.0, чтобы обновить версию mongo
• docker compose up mongo — перезапустить сервис mongo и убедиться, что обновление прошло без проблем
• Измените файл 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, чтобы проверка могла завершиться неудачей, не препятствуя запуску развёртывания.

Эта новая роль предоставляет только право на чтение параметров сервера MongoDB на уровне кластера и может повторно использоваться для целей мониторинга,

# 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