Upgrading from previous versions

Upgrading the production Mender Server installations can be a complex task. It is supported, and encouraged, but there is a number of items to take into account:

• upgrade between the adjacent versions, i.e.: if you want to upgrade to 3.5, you should first bring your server to version 3.4.
• always have a full backup
• read this document
• perform a test upgrade using a copy of your production database
• prepare a maintenance window
• be prepared for the necessity to run some commands by hand
• verify that the current installation works, in particular that it starts up correctly

The present section describes the general steps required and recommended for any case of Mender upgrade.

Taking a full backup

In the following chapters the backup will be always the first item on the agenda. It is the first step in the upgrade preparation. Ideally, you should have a backup that you are sure is valid, that is: you have means to restore it to some environment and verify your setup works.

MongoDB

Be sure you have an up-to-date, working, and complete backup of your Mender MongoDB server in a format identical to the one generated by mongodump command.

Artifacts storage (AWS S3, Azure blob)

Be sure you either enable versioning on your S3 buckets or otherwise backup the artifact storage. During the upgrade procedure it is highly unlikely that something can go wrong with the blob storage, however we recommend being extra careful, and especially so during the restore to staging (see the next section).

Deploy to staging environment

We recommend to spin up a staging environment, and deploy the backup you created in the previous section to it. After you make sure it works, you should perform the upgrade on staging. It serves two purposes:

• verify that the backup works
• be sure that new versions properly upgrade the database

Maintenance window

Be prepared that in some complicated upgrades there may be a period when the Mender Server is not available, or otherwise presents lack of proper service, or incomplete data to the clients. Exercising our imagination we can come up with a scenario when during a certain upgrade a flood of request will lead to data inconsistencies. To mitigate that risk it is better to prepare a maintenance window to complete the upgrade in its due time and place.

Running the new version

Once the new version is up and running give a UI a full refresh without cache, and enjoy your upgraded Mender installation.