Deploy a Container update


This tutorial is not supported by the virtual device because it does not come with a package manager to install the needed dependencies.

This tutorial will walk you through how to deploy Docker container updates with Mender. We will be using the Docker Update Module which allows you to specify a list of container images and their versions in a Mender Artifact which can later be deployed to your device using the hosted Mender Server.


To follow this tutorial, you will need to install:

It is also assumed that you have completed the following tutorials:

Step 1 - Install Docker Engine on your Raspberry Pi

Log in to your Raspberry Pi and run the commands outlined below.

The Docker Update Module has a dependency on the jq utility, run the following command to install it:

sudo apt-get install jq

Download the Docker install script:

curl -fsSL -o

Execute the Docker install script:

sudo sh

Once the installation script has finished, verify that you can run the sudo docker images command.

You will get similar output to below:

sudo docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE

As you can see, there are no Docker images on the device. In the next step we will generate a Mender Artifact which will download an image.

Step 2 - Download the mender-artifact utility on your workstation

If you already installed mender-artifact on your system, you can skip this step.

Prepare destination directory:

mkdir -p ${HOME}/bin

Download the mender-artifact binary. If you're on Linux

wget -O ${HOME}/bin/mender-artifact

On MacOS

wget -O ${HOME}/bin/mender-artifact

Make the mender-artifact binary executable:

chmod +x "${HOME}/bin/mender-artifact"

Add ${HOME}/bin to PATH:

export PATH="${PATH}:${HOME}/bin"

Add above to ~/.bashrc or equivalent to make it persistent across multiple terminal sessions.

Step 3 - Prepare a Mender Artifact on your workstation

Prepare a workspace and change directory to it:

mkdir "${HOME}/mender-docker" && cd "${HOME}/mender-docker"

Download the docker-artifact-gen utility script:


Make docker-artifact-gen executable:

chmod +x docker-artifact-gen

Set the target device type:


Change raspberrypi4 to raspberrypi3 if you are using a Raspberry Pi 3

Generate a Mender Artifact that will deploy the hello-world Docker container image:

./docker-artifact-gen \
    -n "hello-world-container-update" \
    -t "${DEVICE_TYPE}" \
    -o "hello-world-container-update.mender" \

hello-world is the name of the Docker image that we want to download on the device when we deploy the generated Mender Artifact

Step 3 - Deploy the Docker update

Upload the file hello-world-container-update.mender from the previous step to the hosted Mender. Go to the RELEASES tab in the UI and upload it.

Once uploaded, click CREATE DEPLOYMENT WITH THIS RELEASE in order to deploy it to your device.

If the deployment of hello-world-container-update.mender is successful, you will see that there is a image downloaded on the device:

sudo docker images
REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
hello-world         <none>              851163c78e4a        4 months ago        4.85kB

You can also see that the container was started, but since the hello-world container does not contain a daemon it exited immediately:

sudo docker ps -a | head
CONTAINER ID   IMAGE         COMMAND    CREATED          STATUS                      PORTS     NAMES
72e6cf80fa6a   hello-world   "/hello"   45 seconds ago   Exited (0) 42 seconds ago             optimistic_shaw

The Docker Update Module will download and run the specified images from e.g

Read more

There is an alternative option for deploying containerized updates:

You can explore other types of updates available by extending the Mender client in the Update Modules category in the Mender Hub community platform.

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 .