User Login      + Register  

Table_of_Contents

1      Introduction

1.1                What Are Docker Containers / Microservices

1.2                Further Reading

1.3                Docker and SecureOffice

1.3.1      Docker Environment Within SecureOffice

1.3.2      Docker IP Address Management

2      Using Docker Images

2.1                Docker Pre-Requisites

2.2                NextCloud

2.2.1      NextCloud Pre-Requisites

2.2.2      Configure NextCloud

2.2.3      Start Nextcloud Container

2.2.4      Access NextCloud via Dedicated Domain

2.2.5      Access NextCloud via Subdomain

2.2.6      Final Nextcloud Configuration

List of Figures

Figure 1:       Containers Versus VMs

Figure 2:       NextCloud Configuration

Figure 3:       NextCloud Login

Figure 4:       NextCloud Logged In

Figure 5:       Nextcloud Virtual Domain

Figure 6:       Nextcloud Subdomain Config Snippet

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".

What is Docker and why is it so darn popular?

Docker Overview

Docker Containers vs. Virtual Machines

Docker (WikiPedia)

Virtual Machine (WikiPedia)

1.3                Docker and SecureOffice

The SecureOffice docker-ce (docker, community edition) package (premium content) integrates standard docker-ce with the OpenWrt configuration, initscript and DNS methodology, automating most of the steps required to run docker images 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 next section.

1.3.1      Docker Environment Within SecureOffice

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

All docker images 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.

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

1.3.2      Docker IP Address Management

IP addressees for containers are allocated (by docker) on a first come, first server basis. This means, as containers are spun up (in same order as enabled in "/etc/config/docker"), the first container is allocated <lan address + 1>, second, <lan address + 2>, etc. This means that a block of IP addresses 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 DHCP from the host system. SecureOffice / docker, as containers are spun up, dynamically adds container IP address / host name (from container config) entries to the DHCP table, allowing access to containers by their hostname. So, a container configured with hostname "nextcloud" can be accessed "ping nextcloud". This is important for container addressing by nginx webserver, for example. Without this feature, knowing and managing container IP addressing would be cumbersome.

2      Using Docker Images

2.1                Docker Pre-Requisites

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

It is assumed SecureOffice is already installed and configured with an active domain, DNS and SSL certificates. Since docker-ce is a premium package, a subscription to the SecureOffice premium package repository is required.

To install docker-ce, at a command prompt, enter:"opkg update; opkg install docker-ce"

The default location for storing docker images and files is "/home/data/docker", determined by the "data-root" entry in docker configuration file "/etc/docker/daemon.json". Insure that whatever disk is mounted at "home/data" has enough space for all intended docker images and data. 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 at link to a directory on the larger disk at "/home/data/docker" (remove existing docker directory). 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.

2.2                NextCloud

The importance of protecting YOUR information from third parties (including cloud providers) and limiting access to those you trust cannot be overstated. This means self-hosting a file share / sync service. The premium application for this is nextcloud (! Follow link).

Once NextCloud is installed and configured for SecureOffice, it is a standard installation and, all nextcloud documentation regarding adding features, configuration and usage may be used.

2.2.1      NextCloud Pre-Requisites

The NextCloud docker image requires database support. The image, by default (no configuration) internally uses mysql, which has very poor performance. The default configuration of nextcloud (comes with docker-ce package) uses the postgresql database, which must be installed on SecureOffice..

To install postgresql, at a command prompt, enter:"opkg update; opkg install pgsql-server"

2.2.2      Configure NextCloud

The default docker configuration file "/etc/config/docker", with a section for nextcloud is shown below. It must be altered to fit your environment before first run, otherwise, the container must be fully removed and re-installed. This is because the included environment variables are only used during first run of the image to create internal configuration. Additional environment variables (such as email settings) take effect at each run.

Further information regarding nextcloud image configuration / usage can be found in the nextcloud configuration guide.

# Reference: https://docs.docker.com/engine/reference/commandline/run/

# or: docker run --help

# Images ('option image') are from from https://hub.docker.com

# 'option xxxx' are single options, cannot be repeated

# 'list xxxx' are options that can be repeated multiple times

# Cannot have spaces in list parameters, replace with ',', replaced with ' ' by init script

# Multiple container sections supported

 

config container 'nextcloud' # Arbitrary container name

option enable '0' # '0' or '1'

option image 'nextcloud' # From docker hub

option hostname 'nextcloud' # DNS name for host (ping hostname)

option run_cmd '' # Command for image to run at startup

option run_cmd_args '' # Arguments for image startup command

list ports "8080:80" # Port mapping (-p <host port>:<container port>)

list links '' # Other images to link (--link <other image name>)

# Environment variables for image (-e <VAR=VALUE)

# These variables are only used for initial image install

# To change them (a) remove container, start fresh or (b) alter /home/data/docker/volumes/nextcloud/_data/config/config.php

list env 'POSTGRES_PASSWORD=postgres'

list env 'POSTGRES_USER=postgres'

list env 'POSTGRES_DB=nextcloud'

list env 'POSTGRES_HOST=<your_lan_address>'

list env 'NEXTCLOUD_ADMIN_USER=admin'

list env 'NEXTCLOUD_ADMIN_PASSWORD=admin'

list env 'NEXTCLOUD_TRUSTED_DOMAINS="<your_lan_address>,<your_lan_address_+1>,<your_domain_name>"'

# End install variables

# Directory mapping (-v <container directory>:<host directory>)

list volume 'nextcloud:/var/www/html'

list volume 'db:/var/lib/mysql'

list parms '' # Extra parameters, verbatum as expected by 'docker run'

option log_stderr '0' # Log container stderr to syslog

option log_stdout '0' # Log container stdout to syslog

Figure 2: NextCloud Configuration

Using the nano editor, alter the following values, then save the file:

  • "enable": '1" to enable container.
  • "hostname": the image internal and external (to SecureOffice) DNS name of the container. Leave at default.
  • "ports": Leave at default, or comment ('#'), depending how the container will be accessed (nginx, reverse proxy). These are the port mappings for the image. To reference the image using localhost, use "127.0.0.1:8080". See "Nginx Configuration" for further details.
  • "'POSTGRES_PASSWORD", "'POSTGRES_USER": Leave at defaults unless you changed them.
  • "NEXTCLOUD_ADMIN_USER", "NEXTCLOUD_ADMIN_PASSWORD": These should be changed.
  • "NEXTCLOUD_TRUSTED_DOMAINS": Change per your LAN address and domain. Assuming default LAN address with domain example.com, this entry becomes (quotes included): "192.168.10.1,192.168.10.2,www.example.com".These values determine valid addresses (security) for accessing the container.
  • The "volume"settings are to map internal nextcloud container directories to your external filesystem, providing persistent storage for data and configuration. This allows the container to be updated without losing settings or configuration. It is strongly recommended not to change these.
  • The "log_stderr" and "log_stdout"settings are used for debug. Setting them to '1' will log to SecureOffice syslog. This is recommended for first run, until configuration is complete to debug any errors.
  • Leave all other settings at default values.

2.2.3      Start Nextcloud Container

Enable and start the docker daemon: At a command prompt, enter: "/etc/init.d/dockerd enable; /etc/init.d/dockerd start".

Enable and start docker container(s). At a command prompt, enter: "/etc/init.d/docker enable; /etc/init.d/docker start".

At first run, it will take some time for docker to download and configure the nextcloud container. Assuming the log_std* values were set to '1', progress can be viewed (console) by entering "logread -f". A successful run will contain: "Command line: apache2 -D FOREGROUND", else some error message which must be debugged before proceeding. Enter CTRL+c (together) to exit logread. Enter "ping nextcloud" to confirm the container is communicating.

At this point, the nextcloud can only be accessed from your local LAN at addresses: http://<lan address>:8080> or http://<lan address + 1>:80 (no https either). Using a browser from a PC on your LAN, enter one of the previous addresses. You should see the NextCloud login page, below:

Figure 3: NextCloud Login

Login to NextCloud with the username and password configured above. You should see the nextcloud start page, below:

Figure 4: NextCloud Logged In

If satisfied with http (no https) and private NextCloud access from local LAN only (perhaps over VPN), skip the following internet access sections and proceed to final NextCloud configuration.

2.2.4      Access NextCloud via Dedicated Domain

Use this nginx configuration to access nextcloud at a dedicated domain, for example "www.joescloud.net"

The general approach (and pre-requisites) for serving a site at a dedicated domain is in the Nginx HowTo documentation. Assuming the perquisites such as domain, internet DNS, SSL certificates (can be included with primary site certificate) are met, do the following, substituting desired domain for "joescloud.net":

Copy "/etc/nginx/vhosts/example.conf" to "/etc/nginx/vhosts/joescloud.conf"

Alter the above file, saving when done according to the example below:

# Change example.com to your_other_site DNS name

# Change IP address (192.168.10.2) to IP address of server on LAN.

# Uncomment (remove #) everything below

server {

listen 80;

listen [::]:80;

server_name joescloud.net *.joescloud.net;

location /.well-known/acme-challenge/ {

default_type "text/plain";

allow all;

alias /var/letsencrypt/;

}

location / {

return 301 https://$host$request_uri;

}

}

server {

listen 443;

listen [::]:443;

server_name joescloud.net *.joescloud.net;

 

location / {

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

# Allow downstream sites to know who's connecting

proxy_set_header X-Forwarded-For $remote_addr;

proxy_set_header X-Forwarded-Proto https;

proxy_pass http://localhost:8080/;

}

}

Figure 5: Nextcloud Virtual Domain

Note: nextcloud is http only and nginx is converting http to https and the converse. This configuration also includes LetsEncrypt support for the domain.

Restart nginx: "etc/init.d/nginx restart" for the changes to take effect. Enter www.<yourdomain> in a web browser. If all is well, you will be redirected to https:// www.<yourdomain>/login and will see the nextcloud login page (Figure 3). Login and, you should see Figure 4.

If all is not well, enable nextcloud logging "log_std* '1'", restart nextcloud ("/etc/init.d/docker/stop; /etc/init.d/docker/start"), enter "logread -f" (to watch error messages) and try to access nextcloud again. Enter CTRL+c (together) to exit logread. Fix any errors.

2.2.5      Access NextCloud via Subdomain

The general approach (and pre-requisites) for serving a site at a subdomain is in the Nginx HowTo documentation. When using subdomains, domain, internet DNS, SSL certificates are already taken care of by the primary domain.

Edit your domain vhost file ("/etc/nginx/vhosts/<domain>.conf") for the domain nextcloud will be a subdomain of, The subdomain name can be anything such as "mycloud". In the example configuration snippet below, it is "nextcloud": Insert everything between the "# other stuff located here" comments in the file. after any existing location blocks or below the "server_name" directive.

 

server {

listen 443;

listen [::]:443;

# other stuff located here

location /nextcloud/ {

#proxy_pass http://127.0.0.1:8080/;

proxy_pass http://nextcloud:80/;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

# Allow downstream sites to know who's connecting

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto https;

#proxy_set_header X-Forwarded-Host $server_name;

}

# other stuff located here

Figure 6: Nextcloud Subdomain Config Snippet

Note: nextcloud is http only and nginx is converting http to https and the converse.

Nextcloud must be configured for a base URL to allow subdomain access. To do so, edit "/home/data/docker/volumes/nextcloud/_data/config/config.php" (default installation) or "<data-root>/volumes/nextcloud/_data/config/config.php", where "data-root" is defined in"/etc/docker/daemon.json".

Alter the line "'overwrite.cli.url' => 'http://localhost'" to read "'overwrite.cli.url' => 'https://www.<your domain>/nextcloud',". Note the single quotes and comma. This instructs nextcloud to create correct links in emails, etc.

Following the above line, add "'overwritewebroot' => '/nextcloud',". Note the single quotes and comma. This instructs nextcloud to serve from the subdomain.

Note: Once nextcloud has been configured to serve from a subdomain, attempting to access from local LAN by <lan address>:8080/nextcloud or <nextcloud IP address>:80/nextcloud will fail (too many redirects). This is an outstanding nextcloud bug.

Restart nextcloud: "/etc/init.d/docker stop; /etc/init.d/docker start" for the changes to take effect.

Restart nginx: "etc/init.d/nginx restart" for the changes to take effect. Enter www.<yourdomain>/<subdomain> in a web browser. If all is well, you will be redirected to https:// www.<yourdomain>/subdomain/login and will see the nextcloud login page (Figure 3). Login and, you should see Figure 4.

If all is not well, enable nextcloud "log_std* '1'", restart nextcloud ("/etc/init.d/docker/stop; /etc/init.d/docker/start"), enter "logread -f" (to watch error messages) and try to access nextcloud again. Enter CTRL+c (together) to exit logread. Fix any errors.

2.2.6      Final Nextcloud Configuration

Using the nextcloud documentation, perform the following tasks:

  • Configure email server in "/etc/config/docker", nextcloud section by adding environment variables using these instructions,. or using the configuration menu.
  • Add an email address for administrator (and all subsequent users) for password recovery purposes
  • Install additional applications. Recommended applications are: Talk, Contacts, Mail, Bookmarks, Passwords
  • Install nextcloud clients for your PC's, tablets and phones.
  • Determine and configure files to share
  • Determine and add users you trust to share files with.
  • Do an internet search for "nextcloud backup", choose and implement preferred method (via script /cron job recommended). This is crucial.
  • Enjoy this fine, extremely useful application.

 

Technologies Used:

Design by: XOOPS UI/UX Team