App Setup Using Docker - FreeWaveTechnologies/ZumIQ GitHub Wiki

This procedure describes the basic steps needed to get an app installed and running in the ZumIQ environment using Docker.

This ony works with firmware versions v1.3.1.1 and later. For earlier firmware versions, use runit instead of Docker. See the wiki page App Setup Using runit.

Why Should You Use Docker?

Docker is an easy way to develop and deploy applications in a containerized environment. Similar to a jail or a virtual machine, Docker isolates your application from other applications on the Zumlink, giving your application its own root file system, with access to all of the Zum's resources, without interference from other applications. Docker is safer than running an application natively on the Zum, protecting the IQ environment from corruption by your or other applications.

Install and Run Docker on the ZumLink or ZumIQ

While the Zum comes with Docker preloaded, it is not installed and running. This is to conserve resources in case a user does not intend to run Docker.

Login to the device as devuser (see Logging In).

Run the Docker installation script:

cd ~/bin
./install-docker.sh
ps -ef | grep docker

If the docker installation was successful, you will see this response to the ps -ef query:

devuser@freewave-ib:~$ ps -ef | grep docker
root       114     1  0 Feb03 ?        00:05:51 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

Installing a Docker app

A wide variety of Docker images are already available for installation from DockerHub. Any image tagged as an ARM image can be installed on the Zum device, as long as it complies with the Zum's memory restrictions.

The ZumLink and ZumIQ have a limited amount of space available for storing Docker images. Models Z9-P2, Z9-PE2, ZIQ-P2 and ZIQ-PE2 can accommodate a USB memory device. If you find yourself with a Docker image too large to fit in the Zum, contact Freewave support about configuring the Zum to utilize a USB memory device for expanded Docker capacity.

The procedures on this page illustrate:

  • how to install a Docker container from DockerHub using just the docker run command,
  • how to install a Docker container using the docker pull command followed by the docker run command,
  • and finally, how to install your own Docker container from a local source such as a PC or local file server.

The first two examples use the classic "Hello World" container on DockerHub. Reviewing the source files for the container on Github may help you in creating your own Docker containers.

1. Using docker run

To install the Hello World container, simply type:

sudo docker run hello-world

(Note that on the Zum, all docker commands must be executed as root, and therefore prefaced with sudo.)

You will see this response:

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
4ee5c797bcd7: Pull complete
Digest: sha256:9572f7cdcee8591948c2963463447a53466950b3fc15a247fcad1917ca215a2f
Status: Downloaded newer image for hello-world:latest

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

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (arm32v7)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

That's all there is to it.

2. Using docker pull followed by docker run

There may be times when you wish to pull the Docker container before running it. In that case, the pull and the run are two separate steps instead of one single step:

sudo docker pull hello-world
sudo docker run hello-world

The output should be similar to that shown in the Using docker run method.

3. Installing and running your own Docker app

While this is not a complicated procedure, it is rather involved. Basically, it consists of four steps:

  1. Create a dockerfile, a recipe that describes how to build the container. The default filename is dockerfile, but it can be any valid filename.
  2. Build the image:
sudo docker build -f <dockerfilename> -t <imagefilename>
  1. Store the image on the Zum. We suggest storing the image in the /ptp or /data directory. These directories are located on a larger partition.
  2. Run the image in a container.
sudo docker run <path-to-imagefilename>

For details on creating the dockerfile, and for more build and run options, see the resources in the For More Information section.

Managing your Docker containers

To list the Docker containers currently stored on the Zum:

sudo docker image ls
# or 
sudo docker images

To list the Docker images currently running on the Zum:

sudo docker container ls
# or
sudo docker ps

To list all Docker images on the Zum, including those not currently running:

sudo docker container ls -a
# or
sudo docker ps -a

To stop a running Docker container, using the hello-world example:

sudo docker stop hello-world

To remove / erase / delete a Docker image from the Zum, using the hello-world example:

sudo docker rm hello-world

For More Information