How to run Docker on VOXL


This document provides an overview of how to run run docker containers on your VOXL developer board!

Alongside a copy of docker itself, the VOXL Software Bundle includes voxl-docker-support which provides a hello-world Docker image along with tools to configure and enable Docker on VOXL.

Dependencies to run Docker on VOXL are contained in VOXL Factory Bundle as of version 0.0.2.



After installing the required image and bundles, run the configuration script:

Stopping original docker service
Enabling our own services docker-start & docker-prepare
starting docker-start.service
loading hello-world docker image
successfully loaded hello-world
starting docker-prepare service

done configuring voxl-docker-support

Now you can list the available images.

yocto:/# docker images
REPOSITORY          TAG                 IMAGE ID            CREATED                  VIRTUAL SIZE
hello-world         latest              efc161607398        Less than a second ago   2.088 kB

Try running the hello-world image!

yocto:/# docker run hello-world

Hello from Docker on arm64!
This message shows that your installation appears to be working correctly.

Pushing a Docker Image to VOXL

VOXL’s flash memory is broken up into partitions, the largest of which is /data/ which is 16GB. voxl-docker-support already configures docker to use this partition for storage. When pushing a large docker image to VOXL you should also push to this directory.

To push an image and load it on VOXL: (note, this will be slow!!! But you only need to do it once)

hostPC:~$ adb push roskinetic.tgz /data/
hostPC:~$ adb shell
/ # bash
yocto:/# cd /data/
yocto:/data# docker load -i roskinetic.tgz

Now look to make sure the image is loaded

yocto:/data# docker images
REPOSITORY          TAG                 IMAGE ID            CREATED                  VIRTUAL SIZE
hello-world         latest              efc161607398        Less than a second ago   2.088 kB
roskinetic          latest              d3859c0865c1        Less than a second ago   1.958 GB

Running a Docker Image

When running an image, we suggest telling docker to mount the home directory in Yocto to a directory inside the docker image to facilitate transferring data in and out. Here, we mount /home/root/ in Yocto to /root/yoctohome/ in docker. We also suggest using the –net=host option so processes such as ROS running inside Docker can transparently communicate with processes outside of the Docker. With this method ROS nodes can run and communicate both inside and outside of a Docker image seamlessly.

docker run -it --rm --privileged --net=host --name roskinetic-instance -v /home/root:/root/yoctohome/:rw -w /root/ roskinetic /bin/bash

The –rm flag is nice to use if you plan to be starting and stopping containers. This will remove the container after you have exited from it.

The –privileged flag allows you to access all of the device drivers in /dev.

Suggested ‘docker run’ Arguments

For a complete list of arguments, see the Official Docker Documentation. However, for the purposes of running docker images on VOXL, here are the arguments you will likely wish to use:

Argument Description
-it Interactive mode, usually used when you wish to open a bash shell inside the docker.
–rm Automatically remove the container when it exits to prevent containers stacking up.
–privileged Gives the docker container access to /dev/
–net=host Lets network interfaces appear the same inside and outside of the docker container.
–name {name} Give a name to the running instance so you can identify and attach to it by name.
-v {outside}:{inside}:rw Mounts a directory outside the container to a directory inside the container.
-w {working_dir} Set the working directory inside the container.


If you have issues, check the two systemd services provided by voxl-docker-support. Most likely you just need to reboot.

yocto:/# systemctl status docker-start
● docker-start.service
   Loaded: loaded (/etc/systemd/system/docker-start.service; enabled; vendor preset: enabled)
   Active: active (running) since Thu 1970-01-01 00:00:06 UTC; 11min ago

yocto:/# systemctl status docker-prepare
● docker-prepare.service
   Loaded: loaded (/etc/systemd/system/docker-prepare.service; enabled; vendor preset: enabled)
   Active: inactive (dead) since Thu 1970-01-01 00:00:36 UTC; 11min ago
  Process: 3691 ExecStart=/usr/bin/ (code=exited, status=0/SUCCESS)
 Main PID: 3691 (code=exited, status=0/SUCCESS)