The Docker Update Module handles the Docker images that shall be running in the device. An deployment with this module will stop all currently running Docker containers in the device, and start new containers with the provided list of Docker images in the Mender Artifact.

In case of an unforeseen error during the process, the module will use the rollback mechanism of the Mender client to restore the previously running Docker containers.


Module name docker
Supports rollback yes
Requires restart no
Artifact generation script yes
Full system updater no
Source code Update Module, Artifact Generator

Prepare the device

This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.

All commands outlined in this section should be run in the device environment.


This update module has the following prerequisites for the device environment:

  • Install Docker Engine, version 17.03 or later.
  • A recent version of the JSON parser jq needs to be installed in the device.
  • Ensure the device has a Bash Unix shell

How to install these depends on which OS you are running.

Install the Update Module

Download the latest version of this Update Module by running:

mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3

Prepare the development environment on your workstation

This section describes how to set up your development environment on your workstation.

All commands outlined in this section should be run in the development environment.

Artifact creation

For convenience, an Artifact generator tool docker-artifact-gen is provided along the module. This tool will generate Mender Artifacts in the same format that the Update Module expects them.

Download docker-artifact-gen, by running the following command:


Make it executable:

chmod +x docker-artifact-gen

Now generate a Mender Artifact using the following command:

DOCKER_IMAGES="docker-image-1 docker-image2"
./docker-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} ${DOCKER_IMAGES}
  • ARTIFACT_NAME - The name of the Mender Artifact
  • DEVICE_TYPE - The compatible device type of this Mender Artifact
  • OUTPUT_PATH - The path where to place the output Mender Artifact. This should always have a .mender suffix
  • DOCKER_IMAGES - The list of Docker images that we want the target to run. Each item can be any valid name for Docker to pull images from (tags or digests). For example debian, debian:jessie, debian:latest, debian:sha256@…, etc

Note that the actual image id that will be added in the Artifact is the digest (sha256 hash) of the image, regardless of the tag used to pull it in. This will ensure that the device will pull the exact same version of each image than the generation tool used when preparing the Artifact.

You can either deploy this Artifact in managed mode with the Mender server as described in Deploy to physical devices or by using the Mender client only in Standalone deployments.

Artifact technical details

The Mender Artifact used by this Update Module has no payload files. Instead it uses the Metadata field to list the Docker images, which will be downloaded by the device. This meta-data is composed by a single containers JSON key with the array of images digests to be installed in the update.

As an example, the following update will install two specific versions of Docker images debian and ubuntu:

    Type: docker
    Provides: Nothing
    Depends: Nothing
            "containers": [
1 Like

Is there a way to pass arguments to container? If yes, how?


Hi @Prakash and welcome to Mender Hub!

As it is, this Update Module does not support passing arguments to the container. However, it is pretty easy to create a new module based on this one that could achieve that.

Have a look at the Docker Update Module and generator source code (links in table above) for inspiration. One possibility could be to pass the parameters as an extra field in the meta-data contained in the Mender Artifact.


Hi IIuiscampos
I am trying build mender artifact for hello-world docker image…
Hope my DOCKER_IMAGES is correct…

./docker-artifact-gen -n {ARTIFACT_NAME} -t {DEVICE_TYPE} -o {OUTPUT_PATH} {DOCKER_IMAGES}
Using default tag: latest
latest: Pulling from library/hello-world
Digest: sha256:6f744a2005b12a704d2608d8070a494ad1145636eeb74a570c56b94d94ccdbfc
Status: Image is up to date for hello-world:latest
No help topic for 'module-image’
I see meta-data.json only in my directory


Are you using the latest mender-artifact tool v3.0.0? Make sure you
download the latest one from
and install it in your path.


Thank you… Now ./docker-artifact-gen able to create the my-container-update-1.0.mender…


Mender Management server for production throwing following error, When i was trying to upload the Artifact…
Seems to be My mender server not supporting version 3…

Artifact couldn’t be uploaded. unsupported version: 3; supported versions are: 1, 2 [Request ID: 3f00876f]


Looks like you are not running 2.0.0 version of the server.


My Mender Server version : 2.0
Mender-artifact tool version : 3.0
I created the mender artifact for Hello-world docker image with Mender-artifact 3.0 tool. But when I want to deploy above docker image to device, mender client on the device throwing below error. I think there is version mismatch …
My meta-mender version is thud-v2019.02-4-gdb6b761

May 23 12:54:37 imx6 mender[743]: level=error msg=“update install failed: installer: failed to read and install update: reader: unsupported version: 3” module=state
May 23 12:54:37 imx6 mender[743]: level=info msg=“State transition: update-store [Download] -> fetch-install-retry-wait [Download]” module=mender


It seems that you are not running Mender client 2.0.0,

It is not the default and you have to actively enable that version, take a look here

for more information


I updated thud branch and now the version is thud-v2019.05-2-gae00ee7 and added below stuff in local.conf and i see mender_client 2.0.0 in logs from my device…

PREFERRED_VERSION_pn-mender = "2.%"
PREFERRED_VERSION_pn-mender-artifact = "3.%"
PREFERRED_VERSION_pn-mender-artifact-native = "3.%"
  1. Now I created mender artifact for hello-world docker and uploaded this artifact i.e my-container-update-1.0 into server.This artifact size is 6kb and showing its type as rootfs-image in the server.
  2. Downloaded the docker updated module in device @ /usr/share/mender/modules/v3.
  3. After downloading this artifact into device, the device is getting rebooted and inventory shows current software as my-container-update-1.0.