1.2 Further Reading
List of Figures
Figure 1: Containers Versus VMs
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.
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>".
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.
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.
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.
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.
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.
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:
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.
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.
SecureOffice docker supports docker-ce and docker-compose configuration / image control.
The difference between docker-ce and docker-compose based image configuration is:
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.
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:
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.
If a container is not starting properly (container name does not appear in command "docker ps" output), the log output can be inspected.
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: