1      Introduction

1.1                What Are Docker Containers / Microservices

Docker Containers / Microservices have revolutionized the way that cloud services are developed and deployed, significantly improving the economics of service development, deployment and compute power required to provide cloud services compared to virtual machines.

Rather than virtualizing the underlying hardware requiring the overhead (disk space, CPU resources) of an operating system in every virtual machine providing a group of services, docker virtualizes the host operating system which is shared by all docker containers on a host system. The virtual machine versus docker approaches to providing services is contrasted below.

Figure 1: Containers Versus VMs

Microservices refers to the ability of docker containers to communicate with each other, each providing some service which can be combined with other services to form very large, scalable applications. An analogy is combining musicians (containers) to form an orchestra (large group of integrated services). The microservices can be distributed among many compute nodes, geographically distributed and load balanced, or reside on a single machine, such as SecureOffice. It is also possible to use multiple SecureOffice installations with docker to provide diverse services or large, scalable applications.

1.2                Further Reading

There is a huge amount of reference material in the internet regarding Docker containerization. Rather than repeat, a few pertinent links are provided below.

Since internet links go stale with time, use these search terms: "docker versus virtual machines", "docker overview", "docker containers", "docker <application you are looking for>".

What is Docker and why is it so darn popular?

Docker Overview

Docker Containers vs. Virtual Machines

Docker (WikiPedia)

Virtual Machine (WikiPedia)

2      Docker and SecureOffice

The SecureOffice docker package (premium content) integrates containerd, docker-ce and docker-compose with the OpenWrt configuration, initscript and DNS methodology, automating most of the steps required to run docker containers under SecureOffice.

The default docker image / container repository is Docker Hub. Available containers / images (over 100,000) can be browsed in the Docker Hub repository.

One very useful / popular docker application is NextCloud, a secure personal file and information repository, making your files, contacts, email, bookmarks, passwords and much more accessible anywhere using PC's, phones and tablets (free clients). Instructions for using Nextcloud with SecureOffice are provided in the NextCloud HowTo.

Another very useful / popular docker application is hassio (Home Assistant Supervised) for home automation to control / monitor your home locally or remotely using various remote clients for PC's, tablets and phones. Instructions for using hassio with SecureOffice are provided in the Home Assistant HowTo.

2.1                Docker Environment Within SecureOffice

Docker is tightly integrated with SecureOffice, in the following manner:

All docker networks are bridged to the SecureOffice LAN, which means all docker containers have full access to SecureOffice network resources and SecureOffice has full access to container network resources. This is determined by the "bridge" entry in docker config file "/etc/docker/daemon.json". Changing this is highly discouraged and requires expert skills in OpenWrt and docker networking.

Since all docker images have access to the SecureOffice LAN this means that docker images requiring external network service support such as database (SqLite, Mariadb, PostgreSQL), MQTT (mosquito), webserver (Nginx), LetsEncrypt can use local services, eliminating redundancy and waste of resources.

Normally, IP addresses within networked docker containers are orthogonal (independent of) host LAN addresses. Further, the IP addresses assigned to docker containers are not easily controlled but are predictable. This means, when docker containers are bridged to the OpenWrt LAN, duplicate IP address conflicts may occur, unless an IP address numbering plan is used to avoid conflicts.

2.2                Docker IP Address Management

IP addressees for containers are allocated (by docker) on a first come, first served basis. This means, as containers are spun up (in same order as directory listed in "/etc/config/docker"), the first container is allocated <LAN address + 1>, second container, <LAN address + 2>, etc. This means that a block of IP addresses at starting at <LAN address + 1>must be left free for containers. Methods to achieve this are discussed in IP Address Numbering Plan.

Normally, container IP addresses are not accessible via name lookup (DNS) from the host system. SecureOffice / docker, as containers are spun up, dynamically adds container IP address / host name (from container config) entries to the DNS table, allowing access to containers by their hostname. So, a container configured with hostname "nextcloud" can be accessed by "ping nextcloud" from a device on the local LAN. This is important for container addressing by Nginx webserver, for example. Without this feature, knowing and managing container IP addressing would be cumbersome.

3      Using Docker Images

3.1                Docker Pre-Requisites

Docker is a premium package, with dependencies requiring a subscription to the SecureOffice custom package repository for installation. A valid license for the Docker premium package is also required.

Docker images can easily consume several gigabytes each. Ensure that you have adequate storage available. If not, install an additional hard disk, or replace the system disk with a larger disk.

Ensure that whatever disk is mounted at "home/data" has enough space for all intended docker images and data before installing docker or images. If not, choose one of the following options:

• Copy the contents of "/home/data/" to another, larger disk, change "/etc/config/fstab" to mount the larger disk at "/home/data" at boot. All of "/home/data" will be on the larger disk.
• Create a link to a directory on the larger disk at "/home/data/docker" (remove directory "/home/data/docker" if it exists). All docker images and data will be in the specified directory on the larger disk.
• Edit file "/etc/docker/daemon.json", change the "data-root" entry to point to a directory on a larger disk. All docker images and data will be in the specified directory on the larger disk (not recommended, may have to adapt other paths / docker configuration).

It is assumed SecureOffice is already installed and configured with an active domain, DNS and SSL certificates. Docker has many dependencies, which requires a subscription to the SecureOffice custom package repository. To install docker, follow the instructions in Install Premium Content, selecting "docker" as the application.

3.2                Directory Location Conventions

The default (convention) location for storing docker images is "/home/data/docker", determined by the "data-root" entry in docker configuration file "/etc/docker/daemon.json".

The default (convention) location for storing persistent docker data (user preferences, configuration, etc) that survives image updates is "/home/data/docker_data/<image name>" which is specified as part of image configuration.

As part of docker installation, directory "/home/data/docker_data" is automatically shared by Samba, which allows Windows, MAC OSX and Linux file browsers to access image configuration files at "\\<LAN address/Dockers/<Image Name>". This greatly simplifies access to image internal configuration files.

It is highly recommended to keep these (convention) directory locations. Changing them may have unintended consequences requiring other (docker, image) configuration changes. Having a standard directory location convention simplifies SecureOffice docker container management. If other directory locations are required, link the standard locations to alternate locations.

3.3                Container Configuration Files

SecureOffice docker supports docker-ce and docker-compose configuration / image control.

The difference between docker-ce and docker-compose based image configuration is:

• docker-ce runs one self-contained, predefined docker image.
• docker-compose assembles multiple docker images to create a composite microservices docker application with individual docker images each performing some part of the overall service.
• SecureOffice docker configuration files are stored in directory "/etc/config/docker/", named "<container name>", with no extension (example: "/etc/config/docker/nextcloud").
• If there is not a companion (in addition to <container name> without extension file) "<container name>.yaml file" in "/etc/config/docker", the container configuration is interpreted and run as a docker-ce (standalone) image. Example: nextcloud.
• If there is a companion "<container name>.yaml" file in "/etc/config/docker", the container configuration is interpreted and run as a docker-compose (composite) image. Example: "hassio, hassio.yaml".

Each container config file has an "enable" entry that determines whether the container is started by "/etc/init.d/docker start". All enabled containers will be started, with no individual container control (except enable) possible.

If it is required (usually not) to start containers in a particular order, this can be accomplished by adding a prefix such as "00_", "01_" to the image configuration file(s) names. Images will be started in order, stating with "00_<image name>".

The command "/etc/init.d/docker stop" stops all docker containers, with no individual container control possible.

3.4                Removing Containers

Some containers only apply their configuration at first run and must be removed for a first run with new configuration. The container must be removed to achieve this.

Completely remove and re-install the container, optionally losing all configuration:

• "/etc/init.d/docker stop" # Stop all running containers
• Optional: save or backup any container configuration files in directory "/home/data/docker_data/<container name>". These files are normally not altered (except for changes due to version update) when a new version of the container is installed.
• "opkg update; opkg remove docker-<container name>" # Uninstall container
• "rm /etc/config/docker/<config file(s)>" # Remove configuration in case opkg did not
• "opkg install docker-<container name>" # Install container
• Alter or restore configuration to suit, enable container
• "/etc/init.d/dockerd restart; /etc/init.d/docker start" # Start new copy of container

3.5                Using Other Docker Containers

Each container at Docker Hub is documented regarding usage and required configuration. Use the SecureOffice NextCloud and Home-Assistant HowTo's for reference configuration files. Create new configuration files(s) to provide the configuration variables and settings required by the docker container of interest. Wherever possible, use locally available SecureOffice resources such as databases.

When successful, announce the container with configuration files in the forum and the SecureOffice team may choose to convert it to a standard docker package.

3.6                Debugging Docker Containers

If a container is not starting properly (container name does not appear in command "docker ps" output), the log output can be inspected.

• Stop all docker containers: "/etc/init.d/docker stop"
• Enable container logging: by setting "option log_stderr" and "option log_stdout" to "1" in configuration file "/etc/config/docker/<container name>"
• Enter "/etc/init.d/docker start; logread -f | grep docker". Docker startup messages will be displayed in the SecureOffice console.
• Enter "CTL+c" (together) to stop logread.
• Use error messages and internet research to determine and fix any issues.

If a container is starting (container name appears in command "docker ps" output), but is behaving improperly, the container logfile can be inspected and / or a command shell can be started within the container to inspect internal container state such as internet connectivity.

Container logfiles should be available in the web GUI (if the container has one) or in a subdirectory of "/home/data/docker_data/<container name>". Use the container logfile error messages and internet research to determine and fix any issues.

If the above methods are not helpful, start a command shell within the container to inspect the container internal state:

• Enter "docker ps". You should see output of the following form: "c66d5e162a04 homeassistant/qemux86-64-homeassistant:0.114.4 "/init" 7 days ago Up 5 days". You are looking for "<container ID>" (first field eg: "c66d5e162a04") in the output for the container of interest. If the container is not running (no entry for container), startup issues (above) need to be resolved prior to proceeding.
• Enter "docker exec -it <container ID> /bin/bash" to get a command prompt within the container. This will allow you to inspect internal state (eg: "ifconfig", "ping yahoo.com", etc) to determine and fix issues.
• To quit the bash session, enter "exit". This will also close your SecureOffice session if using a remote SSH session. You will need to login to SecureOffice again.