An easy way to integrate the Mender client into an existing image
Switch branches/tags
Clone or download
estenberg Merge pull request #64 from estenberg/device-image-shell
Experimental environment for emulating a device shell
Latest commit 626a37e Dec 14, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
device-image-shell Experimental environment for emulating a device shell Dec 14, 2018
files Added u-boot binaries of Debian 9.4. Nov 22, 2018
.dockerignore merged docker/ directory into root directory Nov 28, 2018
Dockerfile Provide Mender client version as a argument to docker build Nov 29, 2018
LICENSE Add license to repository. Jun 21, 2018 clarify tool name and supported boards/OSes Dec 12, 2018 Make mender-convert tool print more concise output Oct 22, 2018 Make mender-convert tool print more concise output Oct 22, 2018 Create repartitioned Mender compliant image from Yocto image for qemu… Dec 7, 2018 Install Mender related files to Mender image based on Yocto image for… Dec 7, 2018 Install GRUB bootloader to Mender image based on Yocto image for qemu… Dec 7, 2018
docker-build Update Mender client version to 1.7.0 in docker-build script Dec 13, 2018 compile mender during docker image creation Nov 29, 2018
docker-mender-convert Bind entire mender-convert directory into container. Nov 28, 2018
mender-convert Correct raw disk image shrinking Dec 7, 2018 Correct Mender Artifact creation for Mender image containing 6 partit… Dec 7, 2018 Create repartitioned Mender compliant image from Yocto image for qemu… Dec 7, 2018 Make mender-convert tool print more concise output Oct 22, 2018 Make tool ready for handling input images containing 3 partitions Dec 7, 2018


Mender is an open source over-the-air (OTA) software updater for embedded Linux devices. Mender comprises a client running at the embedded device, as well as a server that manages deployments across many devices.

This repository contains mender-convert, which is used to convert pre-built disk images (Debian, Ubuntu, Raspbian, etc) to a Mender compatible image by restructuring partition table and injecting the necessary files.

Currently official Raspberry Pi 3 and BeagleBone Black images are supported and this will be extended.

Mender logo

Getting started

To start using Mender, we recommend that you begin with the Getting started section in the Mender documentation.

Docker environment for mender-convert

In order to correctly set up partitions and bootloaders, mender-convert has many dependencies, and their version and name vary between Linux distributions.

To make using mender-convert easier, a reference setup using a Ubuntu 18.04 Docker container is provided.

You need to install Docker Engine to use this environment.

Build the mender-convert container image

To build a container based on Ubuntu 18.04 with all required dependencies for mender-convert, copy this directory to your workstation and change the current directory to it.

Then run


This will create a container image you can use to run mender-convert.

Use the mender-convert container image

Create a directory input under the directory where you copied these files (docker-build, docker-mender-convert, etc.):

mkdir input

Then put your raw disk image into input/, e.g.

mv ~/Downloads/2018-11-13-raspbian-stretch.img input/2018-11-13-raspbian-stretch.img

You can run mender-convert from inside the container with your desired options, e.g.



./docker-mender-convert from-raw-disk-image                 \
            --raw-disk-image $RAW_DISK_IMAGE                \
            --mender-disk-image $MENDER_DISK_IMAGE          \
            --device-type $DEVICE_TYPE                      \
            --mender-client /mender                         \
            --artifact-name $ARTIFACT_NAME                  \
            --bootloader-toolchain arm-linux-gnueabihf      \
            --server-url ""         \
            --tenant-token $TENANT_TOKEN

Note that the default Mender client is the latest stable and cross-compiled for generic ARM boards, which should work well in most cases. If you would like to use a different Mender client, place it in input/ and adjust the --mender-client argument.

Conversion will take 10-15 minutes, depending on your storage and resources available. You can watch output/build.log for progress and diagnostics information.

After it finishes, you can find your images in the output directory on your host machine!

Known issues

  • BeagleBone images might not convert properly using this docker envirnoment due to permission issues: mount: /mender-convert/output/embedded/rootfs: WARNING: device write-protected, mounted read-only.


We welcome and ask for your contribution. If you would like to contribute to Mender, please read our guide on how to best get started contributing code or documentation.


Mender is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Security disclosure

We take security very seriously. If you come across any issue regarding security, please disclose the information by sending an email to Please do not create a new public issue. We thank you in advance for your cooperation.

Connect with us