Upgrading from Open Source to Enterprise

tutorial

This section describes how to upgrade from the Mender Open Source server, to the Mender Enterprise server. If you have any questions or would like assistance with upgrading to Mender Enterprise, please email contact@mender.io.

In this version of Mender, there is no support for migrating data between the Open Source and Enterprise servers. Hence you will lose all data on the server by following this tutorial, and all users must be recreated, artifacts must be re-uploaded, and devices re-accepted. The focus in this tutorial will be on how to migrate the device fleet. Support for migrating server data will be added to a later Mender release.

Creating a backup

The first thing we will do is to create a backup of the Open Source server so that it can be restored if needed.

Start by shutting down the Mender server:

cd mender-server/production
./run down -v

Create new backup volumes:

docker volume create --name=mender-artifacts-backup
docker volume create --name=mender-db-backup

Clone the contents of the original volumes to the backup volumes:

docker run --rm -v mender-artifacts:/from        -v mender-artifacts-backup:/to        alpine cp -a /from /to
docker run --rm -v mender-db:/from               -v mender-db-backup:/to               alpine cp -a /from /to

This backup can later be restored with this command:

docker run --rm -v mender-artifacts:/to        -v mender-artifacts-backup:/from        alpine cp -a /from /to
docker run --rm -v mender-db:/to               -v mender-db-backup:/from               alpine cp -a /from /to

You can try the above command immediately, it will just restore the already existing volumes.

Setting up the Enterprise server

Delete the original volumes:

docker volume create --name=mender-artifacts
docker volume create --name=mender-db

After deleting the volumes, you need to follow the main tutorial for installing the Enterprise server. You will be directed back to this tutorial when it is time to migrate the clients.

Migrating clients

With Mender Enterprise, each device needs to have a tenant token associated with it. When upgrading from Open Source however, the devices that are already deployed will be lacking this token. Therefore we need to use a special default tenant token which will automatically be assigned to all clients that try to connect without a tenant token.

  1. Fetch the tenant token using the tenant ID that you obtained while creating the first organization and user (replace $TENANT_ID accordingly):

    ./run exec -T mender-tenantadm /usr/bin/tenantadm get-tenant --id $TENANT_ID | jq -r .tenant_token

    eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZW5kZXIudGVuYW50IjoiNWQ4MzM1MzJkMTMwNTgwMDI4NDhmZmRmIiwia
    XNzIjoiTWVuZGVyIiwic3ViIjoiNWQ4MzM1MzJkMTMwNTgwMDI4NDhmZmRmIn0.HJDGHzqZqbosAYyJpSIEeL0W4HMiOmb15ETnu
    ChxE0i7ahW49dZZlQNJBKLkLzuESDxXnmQbQwsSGP6t32pGkeHVXTPjrSjhtMPC80NiibNG3f-QATw9I8YgG2SBd5xaKl17qdta1
    nGi80T2UKrwlzqLHR7wNed10ss3NgJDIDvrm89XO0Rg6jpFZsHCPyyK1c8-Vn8zZjW5azZLNSgtgSLSmFQguQLRRXL2x12VEcmez
    tFY0kJnhGtN07CD3XXxcz0BpWbevDYOPOEUusGd2KpLK2Y4QU8RdngqNtRe7SppG0fn6m6tKiifrPDAv_THCEG6dvpMHyIM77vGI
    PwvV4ABGhZKRAlDe1R4csJQIbhVcTWMGcoZ4bKH-zDK0900_wWM53i9rkgNFDM470i6-d1oqfaCPcbiniKsq1HcJRZsIVNJ1edDo
    vhQ6IbffPRCw-Au_GlnPTn_czovJqSa3bgwrJguYRIKJGWhHgx0e3j795oJ08ks2Mp3Rshbv4da

  2. Shut down the server:

    ./run down

  3. In config/enterprise.yml, locate the DEVICEAUTH_DEFAULT_TENANT_TOKEN variable, and make sure its value is set to the tenant token that was fetched in the previous step

  4. Start the server again:

    ./run up -d

  5. To finalize the upgrade follow the steps in the Enterprise installation tutorial from saving the enterprise configuration.

Optional: Migrating away from default tenant token

After the Enterprise server has been set up and verified to work correctly, it is recommended to switch to tenant tokens on each device, as opposed to the default tenant token that was configured earlier in this tutorial. This gives a small security benefit, by completely blocking devices that don't have a tenant token, and prevents devices showing up in the default organization by mistake, for example if the tenant token has been misspelled.

In order to migrate to tenant tokens on the device, an update must be made to all devices. The update must contain the the tenant token of the default organization. See one of these sections for details on how to include tenant tokens using various client integration methods:

Once all devices have been migrated, the DEVICEAUTH_DEFAULT_TENANT_TOKEN should be configured empty.

  1. Shut down the server:

    ./run down

  2. In config/enterprise.yml, locate the DEVICEAUTH_DEFAULT_TENANT_TOKEN variable, and make sure it is empty

  1. Bring up the server again: 
    ./run up -d

It's important that all devices are migrated before removing the default tenant token, or you will lose access to these devices unless it is reinstated.

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .