Introduction
For this tutorial, we quickly refresh some topics that you will need to have a grasp of such as Mender client, Mender Artifact and Update Modules in order to deploy an application-based update over-the-air (OTA). As part of the prerequisites for this tutorial, it is recommended that you have completed the Mender onboarding to get familiar with the Mender workflow.
Mender Client is a process that runs in user space on top of an embedded Linux operating system which talks to the Mender server and applies the update. The Mender client needs to be integrated with the device so it can install software updates to it. This integration also adds functionality to work with a Mender server such as provisioning, authentication, inventory monitoring and deployment reporting. When integrated, all images built for this device supports robust OTA updates. For a robust update process, Mender defines and uses a file format with .mender suffix, called Mender Artifact to handle additional metadata alongside the raw bits of the image filesystem namely, the Name of the software build, compatibility with device type, and checksum of the root filesystem for controllability during transit or storage.
Mender uses a framework called Update Modules to enable application-based or partial updates and comes with support for these types of updates out-of-the-box:
- Packages (deb and rpm)
- Containers (docker)
- Files (directory copy/sync)
An Update Module is just a piece of user-written code that defines how the Mender client installs an update to a device. They are customizable and can be written in any programming language, so it can be tailored to meet the specific needs of a device or environment.
This tutorial will guide you through how to use Docker Update Module to update a Docker container using a Raspberry Pi 3.
Prerequisites
To follow this tutorial, you will need:
-
A Raspberry Pi 3 board running Raspbian with SSH enabled. You can use any of the methods suggested to install the OS image to your device.
-
A deployment environment using a desktop PC with Ubuntu 18.04 and Google Chrome as a web browser and at least 10 GB free disk space and 2 GB RAM available for Mender.
-
Mender onboarding completed using the latest version of Mender documentation.
Step 1 - Install and Configure Mender Client Properly on Device
We assume that you have familiarized yourself with Mender by doing the latest Mender onboarding as stated in the prerequisites section of this tutorial. To make sure the experience is smoother we will revisit this step since we are doing a partial update and it is important to have installed and configured the Mender client properly in order to do this tutorial.
Installing this way does not offer a full Mender integration in your Raspberry Pi board and only enables Update Modules to do partial updates as intended for this tutorial, in this case a Docker container.
Download a Debian package .deb to install on Debian, Ubuntu or Raspbian:
wget https://d1b0l86ne08fsf.cloudfront.net/2.3.0/dist-packages/debian/armhf/mender-client_2.3.0-1_armhf.deb
Install the package:
sudo dpkg -i mender-client_2.3.0-1_armhf.deb
After successfully installing the Mender client Debian package, some initial setup is required. First, we have to configure the Mender client for the demo setting using the configuration file at /etc/mender/mender.conf. The .mender.conf file resides on the client side.
Copy the demo configuration file:
sudo cp /etc/mender/mender.conf.demo /etc/mender/mender.conf
By viewing the content of the file you should see the following:
{
"ServerCertificate": "/etc/mender/server.crt",
"InventoryPollIntervalSeconds": 5,
"RetryPollIntervalSeconds": 30,
"ServerURL": "https://docker.mender.io/",
"UpdatePollIntervalSeconds": 5
}
The demo server uses docker.mender.io and hosted server uses hosted.mender.io. In this tutorial, we are using the demo server so you need to make sure that ServerURL in the configuration file is set to https://docker.mender.io/. These URLs are not valid domain names and for it to be useful you will need an entry in â/etc/hostsâ such as an IP address docker.mender.io s3.docker.mender.io, with the IP address being the IP of the PC or any environment that is running the demo server.
Next, you need to configure your device type.The device type is a string that defines your device and is used to ensure software compatibility by comparing the device type set in a Mender Artifact with the string on the device.
Create Mender client state directory:
sudo mkdir -p /var/lib/mender
Create the device type file:
echo "device_type=raspberrypi3" | sudo tee /var/lib/mender/device_type
Now you should have the Mender client installed and properly setup in your device.
Start the Mender client:
sudo systemctl enable mender && sudo systemctl restart mender
At this point you should have a login password and have also accepted your Raspberry Pi 3.
Step 2 - Install Docker Update Module
A Docker container packages applications in containers by virtualizing the operating system and dividing it into compartments to run applications.
Mender enables this workflow through Docker Update Modules. The Mender client (installed in step 1) supports different types of updates, using a framework called Update Modules. Installing the Docker Update Module will enable support for installing Docker containers. When the Mender client downloads a Docker container from the server, it will run the Docker Update Module executable associated with the type of software downloaded. The Update Module is responsible for carrying out the steps needed to install software of this type.
A deployment with this module will stop all currently running Docker containers on the device, and start new containers with the provided list of Docker images defined in the Mender Artifact (step 3).
This approach enables targeted application-level updates for the benefit of lower bandwidth usage, faster updates and more frequent deployments.
In order to use this Update Module you will need to download the mender.artifact.
Make it executable and make sure your location is in your PATH:
chmod +x ~/PATH/mender-artifact
Download the latest version of this Update Module by running:
sudo mkdir -p /usr/share/mender/modules/v3 && sudo wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules/docker
Step 3 - Create a Mender Artifact
Download docker-artifact-gen, by running the following command:
wget https://raw.githubusercontent.com/mendersoftware/mender/master/support/modules-artifact-gen/docker-artifact-gen
Make it executable:
chmod +x docker-artifact-gen
You will need to set the variables first just like any standard shell scripting.
ARTIFACT_NAME="my-container-update-1.0"
DEVICE_TYPE="raspberrypi3"
OUTPUT_PATH="my-container-update-1.0.mender"
DOCKER_IMAGES="hello-world"
As you note, in this tutorial we have assigned the âhello-worldâ container tag to the DOCKER_IMAGES variable. This will allow the Mender Artifact generator command below to point to the Docker Hub with the latest hello-world tag digest.
Now after assigning variables, generate a Mender Artifact using the following command:
./docker-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} ${DOCKER_IMAGES}
Step 4 - Update a Docker Container
Now you are all set to deploy a Docker container to your Raspberry Pi 3. Login to the Mender web UI and upload the Artifact file you created in Step 3 in the âRELEASESâ tab. You should also have accepted your Raspberry Pi 3 in the DEVICES tab (no pending device) and create a deployment in the DEPLOYMENTS tab.
To make sure you have updated your device successfully, run the following command on the Raspberry Pi 3 board:
docker run hello-world
You should see a success message from Docker with steps taken to generate the pul and stream to the client.
Conclusion
In this tutorial we went through a step-by-step guide on how to utilize Mender Update Modules to do a simple âhello-worldâ Docker container update to a Raspberry Pi 3 board.
For further reading please visit:
- Overview of Docker
- What is a Mender Update Module, How It Works and Why Use It?
- Docker Update Modules
- Installing production level server
If this tutorial was useful to you, please press like, or leave a thank you note to the contributor who put valuable time into this and made it available to you. It will be much appreciated!
