> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/english/database/how-do-i-update-the-enginsight-database-from-mongodb-5.0-to-mongodb-8.0.md).

# How do I update the Enginsight database from MongoDB 5.0 to MongoDB 8.0?

Enginsight uses MongoDB as its database. In the following, we will show you the steps required to update MongoDB.

Please note that updating MongoDB from version 5.0 to version 8.0 also requires updating the Debian version on the Enginsight Database Server from Debian 11 to Debian 12.

***

## Uninstalling MongoDB 5.0

{% stepper %}
{% step %}

### Stop the Enginsight Application Server

{% hint style="danger" %}
**Please note**: This step is *mandatory* before making any changes to the database!
{% endhint %}

1. Log in to the Enginsight Application Server and navigate to the Enginsight installation directory using the following command:

```
cd /opt/enginsight/enterprise
```

2. Now stop the Application Server using the following command:

```
sudo docker-compose down
```

{% endstep %}

{% step %}

### Back up the MongoDB configuration

{% hint style="danger" %}
**Please note**: This step is *mandatory* before updating MongoDB, as the database configuration under `/etc/mongod.conf` will be deleted during the update!
{% endhint %}

1. Log in to the Enginsight Database Server.
2. Show the MongoDB configuration file `mongod.conf` using the following command:

```
sudo cat /etc/mongod.conf
```

3. Create a backup copy of the file and store it in a safe location of your choice.
   {% endstep %}

{% step %}

### Create a database backup

{% hint style="danger" %}
**Please note**: This step is *mandatory* before updating MongoDB!
{% endhint %}

Now create a database backup, also known as a MongoDB dump.

{% hint style="warning" %}
**Please note**: The commands required for a MongoDB dump may vary, for example if your database is secured via SSL/TLS.
{% endhint %}

{% hint style="success" icon="lightbulb-exclamation" %}
For more information about available MongoDB dump options, see the Knowledge Base: [How do I create a backup of my Enginsight instance?](/docs/knowledge-base/english/database/how-do-i-create-a-backup-of-my-enginsight-instance.md)
{% endhint %}
{% endstep %}

{% step %}

### Uninstall MongoDB 5.0

1. Uninstall the outdated version of MongoDB using the following commands:

```
sudo systemctl stop mongod
sudo apt remove mongodb-org
sudo apt autoremove
```

2. Remove remaining database files using the following command:

```
sudo rm -rf /var/lib/mongodb
```

{% endstep %}

{% step %}

### Update Debian on the Database Server

1. Now update the Database Server from Debian 11 to Debian 12. During this process, the MongoDB repository is automatically updated to version 8.0. Use the update script from the following Knowledge Base article: [How do I update my Enginsight servers from Debian 11 to Debian 12?](/docs/knowledge-base/english/updates/how-do-i-update-my-enginsight-servers-from-debian-11-to-debian-12.md)
2. Restart the Database Server using the following command:

```
sudo systemctl reboot
```

{% hint style="danger" %}
**Please note**: Restarting the Database Server after running the update script is *mandatory*!
{% endhint %}
{% endstep %}
{% endstepper %}

***

## Reinstalling and Setting Up MongoDB 8.0

{% stepper %}
{% step %}

### Reinstall MongoDB

After restarting the Database Server, reinstall MongoDB using the following command:

```
sudo apt install mongodb-org
```

{% endstep %}

{% step %}

### Restore and adjust the MongoDB configuration file

1. Open the MongoDB configuration file `mongod.conf` using the following command:

```
sudo nano /etc/mongod.conf
```

2. Insert the backup copy to restore the original database configuration.
3. Navigate to the `storage` section. Previously, it looked like this:

<pre><code># Where and how to store data.
storage:
  dbPath: /var/lib/mongodb
<strong>  journal:
</strong><strong>    enabled: true
</strong>#  engine:
#  mmapv1:
#  wiredTiger:
</code></pre>

4. Remove the `journal` parameter, including its sub-options, because it is no longer supported.\
   \
   To do this, navigate to the corresponding lines and press **Ctrl + k** to delete each line:

```
# Where and how to store data.
storage:
  dbPath: /var/lib/mongodb
#  engine:
#  mmapv1:
#  wiredTiger:
```

5. Navigate to the `security` section, if it exists, and comment it out together with its sub-options by adding a hash sign **#** at the beginning of each line.
6. Save the changes in the configuration file (**Ctrl**+**o**) and confirm the save process. Close the file (**Ctrl**+**x**).
7. Restart the database service using the following command:

```
sudo systemctl enable --now mongod
```

{% endstep %}

{% step %}

### Set up the replica set

The commands for setting up the replica set differ depending on whether you use SSL/TLS encryption or not.

**Setting up the replica set without SSL/TLS encryption**

<pre><code>mongosh \
<strong>    --host "&#x3C;DatabaseServerIPAddress>:27017" \
</strong>		--eval "rs.initiate({
	    _id: \"rs0\", 
	    members: [{
	      _id: 0,
<strong>	      host: \"&#x3C;DatabaseServerIPAddress>:27017\"
</strong>	    }]
	})"
</code></pre>

{% hint style="info" %}
Remember to replace `<DatabaseServerIPAddress>` accordingly.
{% endhint %}

**Setting up the replica set with SSL/TLS encryption**

<pre><code>mongosh \
		--host "&#x3C;DatabaseServerIPAddress>:27017" \
<strong>		--tls \
</strong><strong>		--tlsCAFile /etc/enginsight/ssl/mongodbCA.crt \
</strong><strong>		--tlsCertificateKeyFile /etc/enginsight/ssl/mongodb.pem \
</strong>		--eval "rs.initiate({
	    _id: \"rs0\", 
	    members: [{
	      _id: 0,
	      host: \"&#x3C;DatabaseServerIPAddress>:27017\"
	    }]
	})"
</code></pre>

{% hint style="info" %}
Remember to replace `<DatabaseServerIPAddress>` accordingly.
{% endhint %}
{% endstep %}

{% step %}

### Restore database users

{% hint style="warning" %}
**Please note**: This step is only required if you had previously configured users for the database.
{% endhint %}

The commands for restoring the database users `mongoAdminUser` and `mongoDefaultUser` differ depending on whether you use SSL/TLS encryption or not.

**Restoring database users** **without SSL/TLS encryption**

<pre><code>mongosh \
<strong>		--host "&#x3C;DatabaseServerIPAddress>:27017" \
</strong>		--eval "db.createUser({user:'mongoAdminUser',pwd:\"$(&#x3C;/etc/enginsight/mongoAdminUserPassword)\",roles:['userAdminAnyDatabase','clusterMonitor']})" admin
mongosh \
<strong>		--host "&#x3C;DatabaseServerIPAddress>:27017" \
</strong>		--eval "db.createUser({user:'mongoDefaultUser',pwd:\"$(&#x3C;/etc/enginsight/mongoDefaultUserPassword)\",roles:[{role:'readWrite',db:'enginsight'}]})" enginsight
</code></pre>

{% hint style="info" %}
Remember to replace `<DatabaseServerIPAddress>` accordingly.
{% endhint %}

**Restoring database users** **with SSL/TLS encryption**

<pre><code>mongosh \
<strong>		--host "&#x3C;DatabaseServerIPAddress>:27017" \
</strong>		--tls \
		--tlsCAFile /etc/enginsight/ssl/mongodbCA.crt \
		--tlsCertificateKeyFile /etc/enginsight/ssl/mongodb.pem \
		--eval "db.createUser({user:'mongoAdminUser',pwd:\"$(&#x3C;/etc/enginsight/mongoAdminUserPassword)\",roles:['userAdminAnyDatabase','clusterMonitor']})" admin
mongosh \
<strong>		--host "&#x3C;DatabaseServerIPAddress>:27017" \
</strong>		--tls \
		--tlsCAFile /etc/enginsight/ssl/mongodbCA.crt \
		--tlsCertificateKeyFile /etc/enginsight/ssl/mongodb.pem \
		--eval "db.createUser({user:'mongoDefaultUser',pwd:\"$(&#x3C;/etc/enginsight/mongoDefaultUserPassword)\",roles:[{role:'readWrite',db:'enginsight'}]})" enginsight
</code></pre>

{% hint style="info" %}
Remember to replace `<DatabaseServerIPAddress>` accordingly.
{% endhint %}
{% endstep %}

{% step %}

### Optional: Adjust the MongoDB configuration file again

{% hint style="warning" %}
**Please note**: This step is only required if you previously commented out the `security` section.
{% endhint %}

1. Open the MongoDB configuration file `mongod.conf` using the following command:

```
sudo nano /etc/mongod.conf
```

2. Navigate to the `security` section, if you commented it out earlier, and uncomment it together with its sub-options by removing the hash sign **#** from the corresponding lines.
3. Save the changes in the configuration file (**Ctrl**+**o**) and confirm the save process. Close the file (**Ctrl**+**x**).
4. Restart MongoDB using the following command:

```
sudo systemctl restart mongod
```

{% endstep %}

{% step %}

### Restore the database backup

Now restore your database backup.

{% hint style="warning" %}
**Please note**: The commands required to restore a MongoDB dump may vary, for example if your database is secured via SSL/TLS. You can find all options here: [How do I create a backup of my Enginsight instance?](/docs/knowledge-base/english/database/how-do-i-create-a-backup-of-my-enginsight-instance.md)
{% endhint %}
{% endstep %}

{% step %}

### Restart the Application Server

You can now restart the application server with all services.

1. Go back to the Application Server.
2. Navigate to the Enginsight installation directory using the following command:

```
cd /opt/enginsight/enterprise
```

3. Rerun the setup script for the application server using the following command and confirm all prompts by pressing the **Enter** key:

```
sudo ./setup.sh
```

{% endstep %}
{% endstepper %}

***