Aggiornare MongoDB

Ogni nuova release di Server CE/Server Pro indicherà nelle sue note di rilascio qualsiasi modifica alla versione di MongoDB supportata.

​

Devo aggiornare MongoDB?

Dovresti prendere in considerazione l’aggiornamento della versione di MongoDB solo se prevedi di aggiornare la tua istanza di Server CE/Server Pro.

Se stai eseguendo una versione di MongoDB più recente di quella consigliata per la tua versione attuale (o di destinazione), non è necessario apportare alcuna modifica.

Non dovresti mai effettuare il downgrade della versione di MongoDB.

Se riscontri un problema specifico che ritieni possa essere legato alla tua versione attuale di MongoDB, sentiti libero di aprire una issue se sei un utente Server CE, oppure contatta il supporto di Overleaf se sei un utente Server Pro.

​

Verificare la versione di MongoDB

L’apertura della shell mongo dovrebbe mostrare immediatamente la versione attuale.

Utenti dell’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"
    }
}

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

​

Processo di aggiornamento

L’aggiornamento della versione di MongoDB durante un upgrade della tua istanza di Server CE/Server Pro si svolge come segue:

1. Decidi la versione di Server CE/Server Pro a cui intendi aggiornare.
2. Trova la versione di MongoDB consigliata per quella specifica release di Overleaf Server CE/Server Pro.
3. Segui le istruzioni per aggiornare MongoDB alla versione di destinazione.
4. Aggiorna la versione dell’immagine di Server CE/Server Pro e riavvia l’istanza.

Ti consigliamo di aggiornare sempre Server CE/Server Pro all’ultima versione disponibile, poiché il suo supporto è sempre garantito (solo per gli utenti Server Pro).

Quando esegui un upgrade di Server CE/Pro, ti consigliamo di aggiornare all’ultima release della versione major installata prima di passare all’ultima release della versione major successiva. Se la tua installazione è indietro di più di una versione major rispetto all’ultima, dovrai eseguire un upgrade in più passaggi.

Ad esempio, se stai eseguendo la 3.5.10, dovrai aggiornare alla 3.5.13 -> eseguire la migrazione della Full Project History -> 4.2.9 -> 5.5.4.

Non dovresti mai saltare versioni major (3.5.10 -> 5.5.4). Se utilizzi il Toolkit e sei indietro di più di una versione major rispetto all’ultima, non devi usare lo script bin/upgrade, poiché dovrai eseguire manualmente un upgrade in più passaggi.

È importante assicurarti di eseguire un backup coerente prima di ogni upgrade di versione major, così da poter tornare indietro in caso di necessità.

​

Informazioni sul supporto delle versioni

Nel caso in cui tu decida di passare a una versione precedente, questa tabella mostra la versione di MongoDB consigliata per le release precedenti di Server CE/Server Pro, ma non dovresti mai effettuare il downgrade della versione di MongoDB.

Server CE/Server Pro	Versione di MongoDB	Feature Compatibility Version minima	Versione massima supportata dal driver Node.js
2.0.x	3.4	-	-
da 2.1.x a 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

La feature compatibility version minima indicata sopra si basa sulla corrispondente versione di MongoDB consigliata per l’uso con la versione di Overleaf mostrata. Se prevedi di utilizzare una versione superiore, MongoDB avrà i propri requisiti minimi.

Puoi consultare la tabella di compatibilità che specifica le versioni supportate del driver Node.js di MongoDB da utilizzare con MongoDB qui.

Puoi consultare lo stato di fine vita di ciascuna versione di MongoDB qui.

​

Aggiornare MongoDB

MongoDB richiede aggiornamenti graduali. Ciò significa che non puoi passare direttamente, ad esempio, dalla 4.0 alla 5.0. Devi prima aggiornare dalla 4.2 alla 4.4, e poi alla 5.0.

MongoDB utilizza numeri pari per le sue versioni stabili.

​

Istruzioni di aggiornamento quando MongoDB è eseguito al di fuori di Docker

Ecco i link alle istruzioni di aggiornamento di mongodb.com per l’upgrade di MongoDB.

• Note di rilascio di MongoDB - aggiornamento di MongoDB dalla 4.2 alla 4.4
• Note di rilascio di MongoDB - aggiornamento di MongoDB dalla 4.4 alla 5.0
• Note di rilascio di MongoDB - aggiornamento di MongoDB dalla 5.0 alla 6.0
• Note di rilascio di MongoDB - aggiornamento di MongoDB dalla 6.0 alla 7.0
• Note di rilascio di MongoDB - aggiornamento di MongoDB dalla 7.0 alla 8.0

Le istruzioni per la 5.0 e successive si riferiscono a un’installazione replica set anziché standalone. Poiché Server Pro/CE 4.0.1+ utilizza le transazioni, MongoDB deve essere eseguito come replica set.

La documentazione per MongoDB dalla 3.2 alla 4.2 è ora disponibile su https://www.mongodb.com/docs/legacy/

Istruzioni di base

Nella maggior parte dei casi l’aggiornamento richiede l’impostazione di un flag di compatibilità prima di aggiornare effettivamente la versione di mongo. I passaggi sono i seguenti:

1. Imposta il flag di compatibilità come descritto nelle note di rilascio di MongoDB (vedi gli esempi seguenti).
2. Quindi aggiorna l’immagine di mongo:
   1. Utenti del Toolkit Aggiorna MONGO_VERSION, ad es. MONGO_VERSION=6.0
   2. Utenti di Docker Compose Aggiorna la versione del tag dell’immagine mongo,
      ad es. services -> mongo -> image: mongo:6.0;

Esempio: aggiornamento di MongoDB dalla 5.0 alla 6.0

Iniziamo assicurandoci di eseguire MongoDB 6.0:

Utenti dell’Overleaf Toolkit:

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

Utenti di Docker Compose:

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

Secondo le istruzioni di aggiornamento, l’unico requisito è avere featureCompatibilityVersion impostato su 5.0. Lo facciamo aprendo una shell MongoDB ed eseguendo il comando indicato:

Utenti dell’Overleaf Toolkit:

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

Gli utenti di Docker Compose possono eseguire docker compose exec mongo mongosh per ottenere una shell ed eseguire gli stessi comandi degli utenti del Toolkit.

Utenti dell’Overleaf Toolkit:

Arrestiamo quindi le istanze di Server CE/Server Pro e MongoDB con il comando bin/stop, impostiamo MONGO_VERSION=6.0 in config/overleaf.rc e riavviamo il servizio mongo con bin/up mongo) per verificare che l’aggiornamento sia andato a buon fine.

Infine, aggiorniamo la versione dell’immagine di Server CE/Server Pro alla versione di destinazione e ricreiamo tutti i servizi con il comando bin/up -d.

Utenti di Docker Compose:

Arrestiamo quindi le istanze di Server CE/Server Pro e MongoDB con il comando docker compose stop, aggiorniamo il file docker-compose.yml per usare image: mongo:6.0 e riavviamo il servizio mongo con il comando docker compose up mongo per verificare che l’aggiornamento sia andato a buon fine.

Infine, aggiorniamo la versione dell’immagine di Server CE/Server Pro alla versione di destinazione e ricreiamo tutti i servizi con il comando docker compose up.

Inizia assicurandoti di eseguire MongoDB 6.0 usando i comandi mongod --version riportati sopra.

Secondo le istruzioni di aggiornamento, l’unico requisito è avere featureCompatibilityVersion impostato su 6.0. Lo facciamo aprendo una shell MongoDB ed eseguendo il comando db.adminCommand({ setFeatureCompatibilityVersion: "6.0" }) .

Utenti dell’Overleaf Toolkit:

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

Arrestiamo quindi le istanze di Server CE/Server Pro e MongoDB con il comando bin/stop, impostiamo MONGO_VERSION=7.0 in config/overleaf.rc e riavviamo il servizio mongo con bin/up mongo) per verificare che l’aggiornamento sia andato a buon fine.

Infine, aggiorniamo la versione dell’immagine di Server CE/Server Pro alla versione di destinazione e ricreiamo tutti i servizi con il comando bin/up -d.

Inizia assicurandoti di eseguire MongoDB 7.0 usando i comandi mongod --version riportati sopra.

Secondo le istruzioni di aggiornamento, l’unico requisito è avere featureCompatibilityVersion impostato su 7.0. Lo facciamo aprendo una shell MongoDB ed eseguendo il comando db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true }). Tieni presente che ora è richiesto il parametro aggiuntivo confirm: true.

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

Arrestiamo quindi le istanze di Server CE/Server Pro e MongoDB con il comando bin/stop, impostiamo MONGO_VERSION=8.0 in config/overleaf.rc e riavviamo il servizio mongo con bin/up mongo) per verificare che l’aggiornamento sia andato a buon fine.

Infine, aggiorniamo la versione dell’immagine di Server CE/Server Pro alla versione di destinazione e ricreiamo tutti i servizi con il comando bin/up -d.

​

Comandi equivalenti per gli utenti di docker compose

Per gli utenti di docker compose, i comandi equivalenti sono:

• docker compose exec mongo mongod --version per visualizzare la versione di mongo
• docker compose exec mongo mongosh per avviare una shell mongo per i comandi di amministrazione
• il comando docker compose stop per arrestare il server
• Modifica il file docker-compose.yml per usare image: mongo:6.0 e aggiornare la versione di mongo
• docker compose up mongo per riavviare il servizio mongo e verificare che l’aggiornamento sia andato a buon fine
• Modifica il file docker-compose.yml per usare image: sharelatex:VERSION e aggiornare la versione dell’immagine
• docker compose up per ricreare tutti i servizi.

​

Creare un ruolo personalizzato

Nella versione 5.5.1 abbiamo introdotto un controllo all’avvio per verificare la feature compatibility version di MongoDB. Se il tuo database MongoDB utilizza l’autenticazione (ad es. l’autenticazione di base), il container sharelatex potrebbe non avviarsi, mostrando un errore di permessi “not authorized on admin to execute command”.

Per risolvere il problema, puoi creare un nuovo ruolo in MongoDB e assegnarlo all’account utente utilizzato per accedere al database seguendo le istruzioni riportate di seguito, oppure impostare ALLOW_MONGO_ADMIN_CHECK_FAILURES=true per consentire che il controllo fallisca senza impedire l’avvio dell’installazione.

Questo nuovo ruolo concede solo il permesso di leggere i parametri del server MongoDB a livello di cluster e può essere riutilizzato a scopo di monitoraggio,

# 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