How to update

Updating BlueRange running inside a docker container is as simple as:

$ cd /opt/bluerange-setup/docker
$ sudo git pull
[..]
remote: Enumerating objects: 7, done.
remote: Counting objects: 100% (7/7), done.
remote: Compressing objects: 100% (1/1), done.
remote: Total 4 (delta 3), reused 4 (delta 3), pack-reused 0
Unpacking objects: 100% (4/4), 404 bytes | 404.00 KiB/s, done.
From https://github.com/bluerange-io/bluerange-setup
   901cba7..1ba5aec  master     -> origin/master
Updating 901cba7..1ba5aec
Fast-forward
 docker/.env | 2 ++
 1 file changed, 2 insertions(+)
$ sudo ./bluerange-compose.sh pull
Pulling database           ... done
Pulling elasticsearch      ... done
Pulling mender-redis       ... done
Pulling minio              ... done
Pulling storage-proxy      ... done
Pulling mongodb            ... done
Pulling mender-device-auth ... done
Pulling mender-useradm     ... done
Pulling mender-gui         ... done
Pulling bluerange          ... done
Pulling logagent           ... done
Pulling mender-inventory   ... done
Pulling kibana             ... done
Pulling mosquitto          ... done
Pulling nodered            ... done
Pulling nginx              ... done
Pulling mender-conductor   ... done
Pulling mender-deployments ... done
Pulling mender-api-gateway ... done
$ sudo ./bluerange-compose.sh up --detach
Recreating bluerange_database_1 ...
bluerange_elasticsearch_1 is up-to-date
bluerange_mender-gui_1 is up-to-date
bluerange_minio_1 is up-to-date
bluerange_mender-redis_1 is up-to-date
bluerange_mongodb_1 is up-to-date
bluerange_logagent_1 is up-to-date
bluerange_kibana_1 is up-to-date
bluerange_storage-proxy_1 is up-to-date
bluerange_mender-conductor_1 is up-to-date
bluerange_mender-device-auth_1 is up-to-date
bluerange_mender-deployments_1 is up-to-date
bluerange_mender-inventory_1 is up-to-date
bluerange_mender-useradm_1 is up-to-date
Recreating bluerange_database_1 ... done
Recreating bluerange_bluerange_1 ... done
Recreating bluerange_mosquitto_1 ... done
Recreating bluerange_nodered_1   ... done
Recreating bluerange_nginx_1     ... done

This will download the latest Docker image of each container before restarting the containers. The BlueRange service will be unavailable until containers have finished rebooting.

Database updates

For safety reasons the MariaDB and MongoDB image versions are pinned in the .env file. These versions must be overwritten in your local server.env file for updating these components.

The MongoDB has a special update procedure requiring taking actions before and after updating! Please make sure to consult the official documentation at MongoDB Release Notes.

Make sure to backup the database data before attempting an update of the database images. This can be done by stopping the containers and copying the data volumes, for example.

Update from Version 4.x to BlueRange 5

To upgrade the software to version 5.x, the version 4.79.3 must be installed firstly. This is because the database migration scripts have been baselined when entering version 5.

  1. To do so, temporarily add DOCKER_BLUERANGE=4.79.3 to the server.env file.

  2. Then run bluerange-compose.sh once without any arguments.

  3. The software is downloaded and the database migrated.

  4. Once the server accepts logins again, it is fully up and running.

  5. Potentially update external database servers, see below.

  6. Now the DOCKER_BLUERANGE key, added in the first step, can be removed safely again.

  7. Finally, run an update cycle as outlined in the beginning of this chapter.

Please backup the database before running a major release update.

In case you are running external databases such as Amazon Aurora or native installations of MySQL/MariaDB, you may need to shutdown the BlueRange server for updating your self-managed database server in step 5 above. Please make sure to run a compatible version:

  • MariaDB Support: MariaDB version 10.2 and lower is no longer supported. Please make sure that you update to version 10.3 or newer.

  • MySQL Support: MySQL version 5.7 and lower is no longer supported. Please make sure that you update to version 8 or newer.

Note that using Amazon Aurora also requires a MySQL 8 compatible version.