Date: 2024-02-07

Document version: 2.0

Valid for: MiR Fleet

Valid for software version: Software 2.x and software 3.x

Valid for hardware version: All

There are several ways to create backups of the data used in MiR Fleet. This guide describes options for creating backups of MiR Fleet and identifies when to use which option, what data is contained, and how to use the backup. The final sections identify setups that MiR Fleet Server Solution and MiR Fleet PC do not support and provide information regarding what will occur if MiR Fleet loses power supply.

There are differences in the backup and recover process for MiR Fleet for software 2.x and 3.x. This guide describes the differences and provides instructions for both versions. Make sure to read the section titles to see which instructions apply for your software version.

MiR does not take responsibility for providing backup procedures. You must determine which procedures to implement based on your application, setup, and best practice guidelines. You can consider using the following: 

• The MiR Fleet interface or API.

• Creating scripts to automate processes for you.

• Setting up a job scheduler or cron setup.

You should also decide where and how to store any backups and how to move the backups to the external storage.

Differences between using backups and recover in software 2.x and software 3.x

The backup and recover process in software 3.x differs from software 2.x in the following ways: 

• You cannot generate a backup of MiR Fleet in software 3.x. This also means that you cannot roll back. You can, however, manually make a copy of your mir_persistence folder, which contains all of your data, including your log files. The backup data can be stored on a different server, and it can be used to recover the state of MiR Fleet in the event of a server breakdown. Copying the mir_persistence folder requires you to be able to SSH into MiR Fleet.

• Licenses are only available on software 2.x fleets.

.site files

A .site file is a basic backup of the site configuration. You can export a .site for each site you have saved on your product.

A .site file is tied to the software version that it was generated from. This means that a .site file can only be imported to a MiR product running the same software version as the MiR product the .site file was exported from.

A .site file generated on a robot can be imported on MiR Fleet and vice versa, provided they share the same software version.

When to use .site files

It is recommended to export a .site file of each of your sites in the following situations:

• Before a software update or rollback.

• Before and after any major changes to the content included in a .site file, especially changes in missions and maps.

Use a .site files to recover data in the following situations:

• You have factory reset or made a clean installation of your MiR product.

• You have purchased a new MiR product that should contain the same site configuration.

Data in a .site file and how to use a .site file

To see what data is included in a .site file and how to import and export .site files from MiR products, see MiR Fleet Interface Guide. You can find this guide on MiR Support Portal.

The following data is NOT included in a .site file:

• Robot groups

• Charging groups

• Elevators (software 2.x only—elevators are included in a software 3.x .site file)

• System settings

• Backups

Using a .site file

To import or export a .site file, see the user guide for your MiR Fleet or MiR Fleet Interface Guide.

Backups

A backup is a copy of your product's configuration and all saved data, except the log files. The backup data can be stored on a different server, and it can be used to recover the state of MiR Fleet in the event of a server breakdown.

If you are using software 3.x, there are both Application and Platform backups. Only Application backups are automatically generated before you update or rollback the software. You can manage backups either on the user interface or the platform interface—see How to use backups and recover data on MiR Fleet.

If you are using software 2.x, backups are automatically generated before you update or rollback the software. You can also generate them manually through the user interface or using the API endpoint /software/backups. You can rollback the system to a backup using the interface or the API endpoint /software/backups/{guid}, where the unique identifier (GUID) can be determined using the endpoint /software/backups to see a full list of backups.

When to use a backup

It is recommended that you create backups in the following situations:

• Before a software update or rollback.

• Before and after any major changes to the content included in a .site file, especially changes in missions and maps.

• Before making any changes to the system settings.

• On a regular basis in case of a system failure.

Backups are saved directly on the robot and take up hard drive space. Make sure to remove unnecessary backups over time to free up space on the robot's hard drive.

Use a backup in the following situations to restore data:

• If you want to roll back to a lower software version, and your robot is running software 2.x. If you are running software 3.x, use the platform interface to apply a lower software version without rolling back—see How to use backups and recover data on MiR Fleet.

• In the event that the server hosting MiR Fleet experiences a breakdown.

Data in a backup

The backup contains all data stored in the product database and the .mir software file for the software version of the backup.

Backups contain .site files of all sites saved on your product.

Each backup is stored in the directory /mir_persistence/mir/backups and the license tied to your host is stored in /mir_persistence/mir/license.

The following data is included in a backup:

• MiR Fleet certificates for https communication

• Logs (both MiR logs and Apache logs)

• A backup of your database

• Uploaded software

• A software version file

• docker-compose.yml

• generic_oauth.toml

The following data is NOT included in a backup:

• MiR Fleet license (only relevant for software 2.x)

• MiR Fleet Server Solution configuration file mirfleet-server-config.yml

• Log files

Generating a backup

Software 2.x and 3.x

Using SSH

Software 3.x only

Connect to your MiR Fleet. You can use SSH to connect to your system with the command:

ssh <user>@<IP>

Copy the mir_persistence folder to a separate device. You can for example use scp: https://www.linode.com/docs/guides/how-to-use-scp/

Using the MiR Fleet interface

Software 2.x only

In the MiR Fleet interface, go to System > Backups, and select + Create backup.

The backup is generated and can be seen in the list of backups on the same page.

Using MiR Fleet REST API

Software 2.x only

To create a backup, use the REST request POST /software/backups with the appropriate authentication.

The request creates a backup and returns:

• The GUID of the backup. Use this to identify and roll back to the generated backup later.

• The state of the backup. This indicates if the backup procedure was successful or not.

A list of all available backups and information about the backups can be retrieved using the request GET /software/backups.

Storing a backup

Software 2.x only

Backups are stored on the host in the MiR Fleet persistence storage in the directory /mir_persistence/mir/backups/robot.

Each backup is stored in a directory with a name given by the GUID of the backup. A backup directory contains the following:

• backup.json: Backup metadata, such as date of creation, state (Success/Failed), GUID, message, and software version

• backup.log: Log from the backup creation process

• db.sql.gz: Database dump

• source.zip.gpg: Copy of MiR software for the software version of the backup

A backup directory can and should be copied to a different file storage than the partition that MiR Fleet is hosted on. It is safe to copy a backup directory when the backup has been successfully created and no rollback to the backup is in progress.

Recovering using a backup

Software 2.x and 3.x

The recovery procedure depends on why recovery is needed and how responsive the interface and API is. Different recovery procedures are outlined in the following sections.

Using the MiR Fleet interface

Software 2.x only

1. Sign in to the MiR Fleet interface.

2. In the MiR Fleet interface, go to System > Backups.

3. In the list of backups, find the backup you want to roll back to, and under Function, select View .

4. Select Roll back. MiR Fleet will now roll back to that software backup.

5. Remove all robots from MiR Fleet.

6. In the MiR Fleet interface, go to Setup > Maps and export the .site file you want to store—to import or export a .site file, see the user guide for your MiR Fleet or MiR Fleet Interface Guide.

7. In the MiR Fleet interface, go to System > Settings > Advanced and factory reset MiR Fleet.

8. Wait for MiR Fleet to turn on again after the factory reset.

9. Import the .site file you stored in Step 3—to import or export a .site file, see the user guide for your MiR Fleet or MiR Fleet Interface Guide.

10. Add the robots to the fleet again one by one.

If you are using MiR Fleet Server Solution, the backup version increases the size of the docker container. You can reduce this by installing the MiR Fleet Server Solution installation file of the same version or higher. To install MiR Fleet Server Solution, see the guide How to update MiR Fleet.

Using MiR Fleet REST API

Software 2.x only

1. Find the GUID of the backup you want to restore. You can retrieve a list of backups and their GUID using the request GET /software/backups.

2. Roll back to the backup using the request POST /software/backups/[GUID] where [GUID] is the GUID of the backup you want to restore.

3. Remove all robots from MiR Fleet, and add them to the fleet again one by one.

Recovering from a server breakdown

Software 2.x and 3.x

1. Ensure that MiR Fleet is completely uninstalled from the host by following the guide How to uninstall MiR Fleet Server Solution.

2. Reinstall Docker and MiR Fleet on the host by following the installation guide in the MiR Fleet Server Solution User Guide.

3. Software 2.x only
   Enter the license to the MiR Fleet by following the installation guide in the MiR Fleet Server Solution User Guide.

4. Restart the host device.

5. Copy your backup's data into the directory /mir_persistence/mir/backups in the newly installed MiR Fleet. If any data is present already, overwrite this data with the backup data.

6. Software 2.x: Roll back to a previous version using the steps in either Using the MiR Fleet interface or Using MiR Fleet REST API.
   
   Software 3.x: Roll back to a previous version using the steps in Using SSH.

7. Remove all robots from MiR Fleet using the interface.

8. Restart MiR Fleet.

9. Add and factory reset all robots to MiR Fleet.

Using a backup on a spare server

Software 2.x and 3.x

A backup server with MiR Fleet preinstalled can be kept alongside the main server as long as the robots are not added to the backup server. To set this up, follow these steps: 

1. Install Docker and MiR Fleet on the host by following the installation guide in the MiR Fleet Server Solution User Guide.

2. Software 2.x only
   Enter the license to MiR Fleet by following the installation guide in the MiR Fleet Server Solution User Guide.

3. Restart the host.

4. Copy your data backups from the main server into the directory /mir_persistence/mir/backups on the spare server. You should either do this each time you create a new backup so the spare server is ready when you need it, or you can do this before activating the spare server.

5. Sign in to the MiR Fleet interface on the spare server.

6. Software 2.x: Roll back to a previous version using the steps in either Using the MiR Fleet interface or Using MiR Fleet REST API.
   
   Software 3.x: Roll back to a previous version using the steps in Using SSH.

7. Remove all robots from MiR Fleet using the interface.

8. Restart MiR Fleet.

9. Add and factory reset all robots to MiR Fleet on the spare server.

Redundancy MiR Fleet server

Running a service in a redundancy setup is when multiple instances of the service are running and performing tasks. The tasks sent to the services are typically distributed via a load balancer.

If one instance of a service experiences an error or shuts down unexpectedly, the other instances are able to perform new incoming tasks and thereby keep the application running.

It is not possible to run MiR Fleet Server Solution or MiR Fleet PC in a redundancy setup.

Hot spare MiR Fleet server

A hot spare is a copy of a server instance in standby and is used in case the primary server instance should fail. The hot spare instance is not performing any tasks when the primary is up and running. However, should the primary instance fail, the hot spare instance will be activated and start performing tasks while the primary instance is inactive.

It is not possible to run MiR Fleet Server Solution or MiR Fleet PC in a hot spare setup.

Factory blackout

MiR Fleet requires a continuous power supply and will shut down if the power is cut. You can consider using an uninterruptible power supply (UPS) to ensure this does not happen.

In the case of a factory blackout, the network connection between MiR Fleet and all robots will most likely be cut. The robots will attempt to finish their tasks but will not be able to go through Limit-robots zones or be assigned positions by MiR Fleet until the network connection is re-established. However, the safety systems on all robots will still be fully functional, as this does not depend on MiR Fleet.

If the power to MiR Fleet is cut during a factory blackout, MiR Fleet will turn back on once it is powered. In most cases, MiR Fleet will recover its previous state, as this is similar to restarting MiR Fleet. In some cases, an unexpected power cut can cause unforeseeable complications in MiR Fleet operations.

When you start up MiR Fleet after a power cut, and you experience issues such as robots that can no longer connect or synchronize, the database becomes corrupt, or MiR Fleet becomes unresponsive, you must restore MiR Fleet using a backup.

FAQ

Software 2.x only

This section is only relevant for software 2.x, as the questions deal with rollbacks that are not possible in software 3.x. In software 3.x, you always have to do a clean install when "rolling back".

Document history