MongoDB bijwerken

Elke nieuwe release van Server CE/Server Pro vermeldt in de releasenotes eventuele wijzigingen in de ondersteunde versie van MongoDB.

​

Moet ik MongoDB bijwerken?

Je moet alleen overwegen je MongoDB-versie bij te werken als je van plan bent je instantie van Server CE/Server Pro te upgraden.

Als je een MongoDB-versie draait die nieuwer is dan de aanbevolen versie voor je huidige (of beoogde) versie, hoef je niets te wijzigen.

Je moet je MongoDB-versie nooit downgraden.

Als je een specifiek probleem ondervindt waarvan je denkt dat het met je huidige versie van MongoDB te maken heeft, kun je gerust een issue aanmaken als je Server CE-gebruiker bent, of contact opnemen met Overleaf Support als je Server Pro-gebruiker bent.

​

Je MongoDB-versie controleren

Bij het openen van de mongo-shell zou de huidige versie direct moeten worden weergegeven.

Gebruikers van de 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"
    }
}

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

​

Updateproces

Het bijwerken van de MongoDB-versie tijdens een upgrade van je Server CE/Server Pro-instantie gaat als volgt:

1. Bepaal naar welke versie van Server CE/Server Pro je wilt upgraden.
2. Zoek de MongoDB-versie die door die specifieke Overleaf Server CE/Server Pro-release wordt aanbevolen.
3. Volg de instructies om MongoDB naar de beoogde versie te upgraden.
4. Upgrade de imageversie van Server CE/Server Pro en start de instantie opnieuw.

We raden aan Server CE/Server Pro altijd te upgraden naar de nieuwste beschikbare versie, omdat die gegarandeerd wordt ondersteund (alleen voor Server Pro-gebruikers).

Bij het upgraden van Server CE/Pro raden we aan eerst te upgraden naar de nieuwste release van de geïmplementeerde hoofdversie, voordat je upgradet naar de nieuwste release van de volgende hoofdversie. Als je implementatie meer dan één hoofdversie achterloopt, moet je in meerdere stappen upgraden.

Als je bijvoorbeeld 3.5.10 draait, moet je upgraden naar 3.5.13 -> de migratie naar Full Project History uitvoeren -> 4.2.9 -> 5.5.4.

Je mag nooit hoofdversies overslaan (3.5.10 -> 5.5.4). Als je de Toolkit gebruikt en meer dan één hoofdversie achterloopt, mag je het script bin/upgrade niet gebruiken, omdat je dan handmatig in meerdere stappen moet upgraden.

Het is belangrijk dat je vóór elke upgrade van een hoofdversie een consistente back-up maakt, zodat je zo nodig kunt terugdraaien.

​

Informatie over versieondersteuning

Voor het geval je besluit naar een eerdere versie te gaan, toont deze tabel de aanbevolen MongoDB-versie voor eerdere releases van Server CE/Server Pro. Je moet je MongoDB-versie echter nooit downgraden.

Server CE/Server Pro	MongoDB-versie	Minimale Feature Compatibility Version	Maximale versie ondersteund door de Node.js-driver
2.0.x	3.4	-	-
2.1.x t/m 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

De bovenstaande minimale Feature Compatibility Version is gebaseerd op de bijbehorende MongoDB-versie die wordt aanbevolen voor gebruik met de getoonde versie van Overleaf. Als je van plan bent een hogere versie te gebruiken, heeft MongoDB zijn eigen minimumvereiste.

Je kunt de compatibiliteitstabel met de ondersteunde versies van de MongoDB Node.js-driver voor gebruik met MongoDB hier bekijken.

Je kunt de end-of-life-status van elke MongoDB-versie hier bekijken.

​

MongoDB upgraden

MongoDB vereist stapsgewijze upgrades. Dat betekent dat je niet rechtstreeks van bijvoorbeeld 4.0 naar 5.0 kunt gaan. Je moet eerst 4.2 bijwerken naar 4.4, en daarna naar 5.0.

MongoDB gebruikt even nummers voor zijn stabiele versies.

​

Update-instructies wanneer MongoDB buiten Docker draait

Hier zijn links naar de update-instructies van mongodb.com voor het upgraden van MongoDB.

• MongoDB-releasenotes - MongoDB upgraden van 4.2 naar 4.4
• MongoDB-releasenotes - MongoDB upgraden van 4.4 naar 5.0
• MongoDB-releasenotes - MongoDB upgraden van 5.0 naar 6.0
• MongoDB-releasenotes - MongoDB upgraden van 6.0 naar 7.0
• MongoDB-releasenotes - MongoDB upgraden van 7.0 naar 8.0

De instructies voor 5.0 en hoger verwijzen naar een installatie als replica set in plaats van standalone. Omdat Server Pro/CE 4.0.1+ transacties gebruikt, moet MongoDB als replica set worden uitgevoerd.

Documentatie voor MongoDB 3.2 tot en met 4.2 is nu beschikbaar via https://www.mongodb.com/docs/legacy/

Basisinstructies

In de meeste gevallen moet je voor de update een compatibiliteitsvlag instellen voordat je de mongo-versie daadwerkelijk bijwerkt. De stappen zijn als volgt:

1. Stel de compatibiliteitsvlag in zoals beschreven in de releasenotes van MongoDB (zie de voorbeelden hieronder).
2. Werk vervolgens de mongo-image bij:
   1. Toolkit-gebruikers Werk MONGO_VERSION bij, bijv. MONGO_VERSION=6.0
   2. Docker Compose-gebruikers Werk de versie van de image-tag van mongo bij,
      bijv. services -> mongo -> image: mongo:6.0;

Voorbeeld: MongoDB upgraden van 5.0 naar 6.0

Laten we eerst controleren dat we MongoDB 6.0 draaien:

Gebruikers van de Overleaf Toolkit:

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

Gebruikers van Docker Compose:

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

Volgens de upgrade-instructies is de enige vereiste dat featureCompatibilityVersion is ingesteld op 5.0. Dat doen we door een MongoDB-shell te openen en de aangegeven opdracht uit te voeren:

Gebruikers van de 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-gebruikers kunnen docker compose exec mongo mongosh uitvoeren om een shell te openen en dezelfde opdrachten uitvoeren als Toolkit-gebruikers.

Gebruikers van de Overleaf Toolkit:

Vervolgens stoppen we de instanties van Server CE/Server Pro en MongoDB met de opdracht bin/stop, stellen we MONGO_VERSION=6.0 in config/overleaf.rc in en starten we de mongo-service opnieuw met bin/up mongo) om te controleren of de update soepel is verlopen.

Ten slotte werken we de imageversie van Server CE/Server Pro bij naar onze beoogde versie en maken we alle services opnieuw aan met de opdracht bin/up -d.

Gebruikers van Docker Compose:

Vervolgens stoppen we de instanties van Server CE/Server Pro en MongoDB met de opdracht docker compose stop, werken we het bestand docker-compose.yml bij om image: mongo:6.0 te gebruiken en starten we de mongo-service opnieuw met de opdracht docker compose up mongo om te controleren of de update soepel is verlopen.

Ten slotte werken we de imageversie van Server CE/Server Pro bij naar onze beoogde versie en maken we alle services opnieuw aan met de opdracht docker compose up.

Controleer eerst met de bovenstaande mongod --version-opdrachten dat je MongoDB 6.0 draait.

Volgens de upgrade-instructies is de enige vereiste dat featureCompatibilityVersion is ingesteld op 6.0. Dat doen we door een MongoDB-shell te openen en de opdracht db.adminCommand({ setFeatureCompatibilityVersion: "6.0" }) uit te voeren.

Gebruikers van de Overleaf Toolkit:

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

Vervolgens stoppen we de instanties van Server CE/Server Pro en MongoDB met de opdracht bin/stop, stellen we MONGO_VERSION=7.0 in config/overleaf.rc in en starten we de mongo-service opnieuw met bin/up mongo) om te controleren of de update soepel is verlopen.

Ten slotte werken we de imageversie van Server CE/Server Pro bij naar onze beoogde versie en maken we alle services opnieuw aan met de opdracht bin/up -d.

Controleer eerst met de bovenstaande mongod --version-opdrachten dat je MongoDB 7.0 draait.

Volgens de upgrade-instructies is de enige vereiste dat featureCompatibilityVersion is ingesteld op 7.0. Dat doen we door een MongoDB-shell te openen en de opdracht db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true }) uit te voeren. Houd er rekening mee dat hiervoor nu een extra parameter confirm: true vereist is.

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

Vervolgens stoppen we de instanties van Server CE/Server Pro en MongoDB met de opdracht bin/stop, stellen we MONGO_VERSION=8.0 in config/overleaf.rc in en starten we de mongo-service opnieuw met bin/up mongo) om te controleren of de update soepel is verlopen.

Ten slotte werken we de imageversie van Server CE/Server Pro bij naar onze beoogde versie en maken we alle services opnieuw aan met de opdracht bin/up -d.

​

Equivalente opdrachten voor Docker Compose-gebruikers

Voor Docker Compose-gebruikers zijn de equivalente opdrachten:

• docker compose exec mongo mongod --version om de mongo-versie weer te geven
• docker compose exec mongo mongosh om een mongo-shell te starten voor beheeropdrachten
• de opdracht docker compose stop om de server te stoppen
• Bewerk het bestand docker-compose.yml om image: mongo:6.0 te gebruiken en zo de mongo-versie te upgraden
• docker compose up mongo om de mongo-service opnieuw te starten en te controleren of de update soepel is verlopen
• Bewerk het bestand docker-compose.yml om image: sharelatex:VERSION te gebruiken en zo de imageversie te upgraden
• docker compose up om alle services opnieuw aan te maken.

​

Een aangepaste rol aanmaken

In versie 5.5.1 hebben we een controle bij het opstarten geïntroduceerd die de Feature Compatibility Version van MongoDB verifieert. Als je MongoDB-database authenticatie gebruikt (bijv. basisauthenticatie), start de sharelatex-container mogelijk niet en wordt de rechtenfout “not authorized on admin to execute command” weergegeven.

Om dit op te lossen, kun je met de onderstaande instructies een nieuwe rol in MongoDB aanmaken en deze toewijzen aan het gebruikersaccount dat toegang heeft tot de database, of ALLOW_MONGO_ADMIN_CHECK_FAILURES=true instellen zodat de controle mag mislukken zonder dat de implementatie daardoor niet kan starten.

Deze nieuwe rol geeft alleen toestemming om clusterbrede MongoDB-serverparameters te lezen en kan ook worden hergebruikt voor monitoringdoeleinden.

# 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