This started out as a project to learn Docker and have control over the versions of the various pieces of FOSS I use. But I hope you find the ecosystem as useful as I do!

The instructions assume a working knowledge of shell programming, Docker, and Docker Compose. Like most documentation they are also a work in progress...

Licence

MIT (unless otherwise stated). Copyright (c) 2020-2022 bfren (unless otherwise stated).

Source files (GitHub) Container images (Docker Hub)

Acknowledgements

Docker Alpine is a tiny distribution of Linux designed specifically for use in containers.

esh is a lightweight templating engine using POSIX-compatible syntax.

Tags

x.x and x.x.x refer to the bfren image versions.

In addition, you can add -dev and -beta suffixes to access development / test builds (see Docker Hub for further details).

Environment Variables

Packages

If you need to build the image with a different timezone to the default ("Europe/London"), you can do so by setting the TZ ARG, or by installing the tzdata package. (Please note this is only possible if you are building the image yourself - otherwise you will need to use bf-tz.)

As well as the standard repositories, the edge repos are tagged with @edgemain and @edgecomm. This means you can, for example, do apk add curl@edgemain or apk add php8@edgecomm to add the edge versions of packages.

Cron

This image contains only one service: cron, which is enabled by default. If you want to add scripts or executables to the cron you have two options.

Option 1: /etc/periodic/

The simplest way to add tasks to the cron in Alpine Linux is to place an executable file in one of the directories under /etc/periodic/ (remember to set the executable attribute in /etc/fix-attrs.d/):

$ ls /etc/periodic/
1min    15min    daily    hourly    monthly    weekly

It's pretty obvious how frequently they run! An example of this method can be found in the Nginx PHP image.

Option 2: /etc/crontabs/root

If you want more control over your cron tasks you can create a normal crontab file:

$ head -n 1 /etc/crontabs/root
0 */8 * * * db-backup > /dev/null 2>&1

However, if you do this, remember you will be overriding the default file when your /overlay/ is copied over the image files, so you need to include the default directives if you don't want to break the cron further down the line.

Templating with esh

The image comes pre-installed with esh, a simple shell-based templating engine. It is extremely lightweight, and very easy to use.

All dynamic configuration files in the bfren ecosystem are built using esh, and the default location for those templates is /etc/bf/templates.

See Alpine: Executables.

Source files (GitHub) Container images (Docker Hub)

Acknowledgements

The S6 Overlay is a version of the S6 supervisor which has various useful features for containers and managing services.

Environment Variables, Packages, Layout

See Alpine S6.

(GitHub) (Docker Hub)

Acknowledgements

The is a version of the S6 supervisor which has various useful features for containers and managing services.

Environment Variables

Packages

The image comes with the S6 Overlay and all its dependencies.

Layout

The most important concept in these images is the /overlay/ directory, which is copied from the source over the top of the image. You can use whatever structure you like within that.

So, for example, the edge repositories are added via the /overlay/etc/apk/repositories file, which is copied over the top of the base image filesystem by the Dockerfile command COPY ./overlay /.

You can add any files you want to the image this way.

S6 Startup

Every time the container starts, the S6 Overlay runs the same series of scripts. These allow you to ensure that there is a consistent environment for your service.

The sequence is as follows (all should be contained within the /overlay/ directory):

1. /etc/fix-attrs.d/ - set required permissions

2. /etc/cont-init.d/ - run initialisation scripts

3. /etc/services.d/ - register the services you want to be supervised

The S6 Overlay does more before and after all this - additional information can be found in . These three folders are where you will most often hook into the container processes.

Permissions

For me, permissions are one the most powerful and most frustrating features of Linux. These are set by adding files to /overlay/etc/fix-attrs.d/. Good practice is to prefix these files with a number so you have control over the order in which they are loaded. For example:

• First we have the absolute path to the file or directory to set permissions for

• Next we have true or false whether or not to recurse (obviously meaningless for a file)

• Then we have the owner of the file or directory

• Finally we have the permissions, first fmode (file permissions) and then dmode (directory permissions). I find the extremely useful for generating these.

You can have as many of these as you wish, and you can reapply them at any point by using .

Initialisation

After the permissions are set, the scripts in /etc/cont-init.d/ are run. Here you might want to run installation routines, create configuration files, etc.

For example, in the image the following two scripts run in this stage:/etc/cont-init.d/10-initial # downloads the latest virus definitions

Notice that in this example the files begin 10- and 11- as mentioned earlier.

(It does mean there can't be more than ten initialisation scripts per image, but frankly if there are more we need to ask the question, is the image trying to do too much? A key principle of Docker is that an image should do one thing.)

Services

All the services you want to be managed by S6 go in /etc/services.d/. The name of the next directory will be the name of the service, e.g. cron. Within that the minimum you need is a file named run, which contains the script necessary to start your service.

Here is the run file from the cron service of this image:

As you can see, it doesn't have to be complex! The trick with this particular example is the -f flag which tells the cron daemon to run in the foreground. If it ran in the background, S6 wouldn't be able to supervise it. This is something to watch out for when creating your own services.

You can have as many services as you want - however the main point of Docker is to separate services into their own 'contained' environments. Therefore I try to keep the discipline of one 'main' service, and only adding 'supporting' services beyond that.

So, for example, in the image, the main service is nginx itself, but there are also two services to manage logging.

Note that service directories are not given a number prefix - they will run in any order. S6 does have ways of making a service wait for another service to start, but it's complex and very fiddly. Plus, if something needs to happen before your service starts, it should probably go in /etc/cont-init.d/ instead.

In your main service directory, I suggest also including a finish file:

This is also from the cron service of this image, but you'll see it in the main service directory of all the bfren images. What this does is tell S6 to close down all the services gracefully when this one quits, and then stop the container. You don't have to do this, but it's good practice to ensure a safe closedown of your container services when one of them crashes.

It means you may want to set restart to unless-stopped instead of always, or you could end up with a never-ending loop of a container starting, crashing, restarting, crashing, etc.

Container Environment

One of the most useful tricks when using S6 is to make use of the following directive to import all environment variables into the current script:

This is an example from the image (in fact it is the contents of the 11-updater file we looked at earlier). One of that image's environment variables is FRESHCLAM_PER_DAY which allows you to define how many times a day you want freshclam to run.

You do not get Docker's environment variables in scripts by default however, so you need to use the S6 helper function with-contenv (with container environment). Then you can access all the environment variables you want.

Have fun!

And that's it! There is a lot more to it if you want to get complicated - I suggest you read the S6 documentation if you want to go deeper..

Source files (GitHub) Container images (Docker Hub)

Acknowledgements

Debian Slim is a cut-down distribution of Debian designed specifically for use in containers.

esh is a lightweight templating engine using POSIX-compatible syntax.

Tags

x.x and x.x.x refer to the bfren image versions.

In addition, you can add -dev and -beta suffixes to access development / test builds (see Docker Hub for further details).

Environment Variables, Packages, Cron & Templating

See Alpine.

Helpers

aspnet-restart

Restarts ASP.NET application.

Usage

$ aspnet-restart
[bf] 2021-09-19 18:00:00 | restart: Restarting application.
[bf] 2021-09-19 18:00:00 | bf-svc: Restarting service 'aspnet'.

aspnet-start

Starts ASP.NET application.

Usage

$ aspnet-start
[bf] 2021-09-19 18:00:00 | start: Starting ASP.NET application.
[bf] 2021-09-19 18:00:00 | start:  .. /app/live/ASPNET_ASSEMBLY.

aspnet-switch-terminate

Stops ASP.NET application, switches live and published code, and terminates the container (you will need to have the restart policy set to 'always').

Usage

$ aspnet-switch-terminate
[bf] 2021-09-19 18:00:00 | bf-svc: Disabling service 'aspnet'.
[bf] 2021-09-19 18:00:00 | switch: Switching code...
[bf] 2021-09-19 18:00:00 | switch:  .. moving live files to src.OCPFfa
[bf] 2021-09-19 18:00:00 | switch:  .. moving published files to /app/live
[bf] 2021-09-19 18:00:00 | switch:  .. moving live files to /app/publish
[bf] 2021-09-19 18:00:00 | switch: done.
[bf] 2021-09-19 18:00:00 | bf-env: BF_TERMINATING=1.
[bf] 2021-09-19 18:00:00 | bf-svc-terminate: Terminating all services.

healthcheck

Uses bf-test-url to request the URL set by ASPNETCORE_URLS and exits with code 0 if response is HTTP 200 OK.

Usage

$ healthcheck
[bf] 2021-09-19 18:00:00 | healthcheck: Loading http://localhost:5000. (bf-test-url)
Connecting to localhost:5000 (127.0.0.1:5000)
remote file exists

Output

bf-svc-finish

Outputs service closing down debug message and optionally terminates all running services. Usually used in /etc/services.d/xxx/finish file to show

Arguments

• -s X outputs a message that service "X" is shutting down

• -t terminates all other services as well

Usage

$ bf-svc-finish -s cron
[bf] 2021-09-23 10:21:52 | cron/finish: Service closing down.

$ bf-svc-finish -s cron -t
[bf] 2021-09-19 18:00:00 | cron/finish: Service closing down.
[bf] 2021-09-19 18:00:00 | bf-env: BF_TERMINATING=1.
[bf] 2021-09-19 18:00:00 | bf-svc-terminate: Terminating all services.
[bf] 2021-09-19 18:00:00 | cron-log/finish: Service closing down.
[cont-finish.d] executing container finish scripts...
[cont-finish.d] 00-clear: executing...
[bf] 2021-09-19 18:00:00 | 00-clear: Clearing /tmp... (bf-clear)
[bf] 2021-09-19 18:00:00 | 00-clear: done. (bf-clear)
[bf] 2021-09-19 18:00:00 | 00-clear: Clearing caches... (bf-clear)
[bf] 2021-09-19 18:00:00 | 00-clear: done. (bf-clear)
[cont-finish.d] 00-clear: exited 0.
[cont-finish.d] done.
[s6-finish] waiting for services.
[s6-finish] sending all processes the TERM signal.
[s6-finish] sending all processes the KILL signal and exiting.

Helpers

bf-clear-src

Clears contents of /etc/bf/src.

Usage

$ bf-clear-src
[bf] 2021-09-19 18:00:00 | bf-clear-src: Clearing /etc/bf/src...
[bf] 2021-09-19 18:00:00 | bf-clear-src: done.

bf-cron

Run all scripts within a cron directory.

Arguments

• -h Show usage

• -q Run quietly (otherwise it will output that the cron is being run to the logs - individual scripts may still send output)

• DIRECTORY - the directory within /etc/periodic to run

Usage

$ bf-cron 1min
[bf] 2021-09-19 18:00:00 | bf-cron: /etc/periodic/1min.

$ bf-cron -q 1min
// scripts are run with no output

bf-env

Adds a container environment variable called $1 with value $2.

Arguments

1. Variable name

2. Variable value

Usage

$ bf-env "DOCS" "Docker Docs"
[bf] 2021-09-19 18:00:00 | bf-env: DOCS=Docker Docs.

bf-fix-attrs

Re-applies attributes and permissions defined in /etc/fix-attrs.d. Based on code from S6 Overlay.

Usage

$ bf-fix-attrs
[bf] 2021-09-19 18:00:00 | bf-fixattrs: Applying ownership & permissions fixes...
[bf] 2021-09-19 18:00:00 | bf-fixattrs: 00-alpine-s6: applying...
[bf] 2021-09-19 18:00:00 | bf-fixattrs: 00-alpine-s6: exited 0.
[bf] 2021-09-19 18:00:00 | bf-fixattrs: done.

bf-forward

Forwards errors logged in $2 to Docker logs; if $2 is not set, disables service $1.

Arguments

1. Service name.

2. Absolute path to log file.

Usage

$ bf-forward cron-log /var/log/cron.log
[bf] 2021-09-19 18:00:00 | [bf] 2021-09-23 09:57:59 | cron-log/run: Forwarding cron-log - /var/log/cron.log. (bf-forward)

bf-svc

Uses S6 to control the service named $2.

Arguments

1. Control action: 'disable', 'restart', 'start', 'stop'

2. Service name

Usage

$ bf-svc restart cron
[bf] 2021-09-19 18:00:00 | bf-svc: Restarting service 'cron'.
[bf] 2021-09-19 18:00:00 | cron/finish: Service closing down.
[bf] 2021-09-19 18:00:00 | cron/run: Starting cron.
crond: crond (busybox 1.33.1) started, log level 8

bf-svc-terminate

Terminates all running services - usually used in /etc/services.d/xxx/finish file - which also closes down (and potentially restarts) the whole container.

Usage

$ bf-svc-terminate
[bf] 2021-09-19 18:00:00 | bf-env: BF_TERMINATING=1.
[bf] 2021-09-19 18:00:00 | bf-svc-terminate: Terminating all services.
[bf] 2021-09-19 18:00:00 | cron/finish: Service closing down.
[bf] 2021-09-19 18:00:00 | cron-log/finish: Service closing down.
[cont-finish.d] executing container finish scripts...
[cont-finish.d] 00-clear: executing...
[bf] 2021-09-19 18:00:00 | 00-clear: Clearing /tmp... (bf-clear)
[bf] 2021-09-19 18:00:00 | 00-clear: done. (bf-clear)
[bf] 2021-09-19 18:00:00 | 00-clear: Clearing caches... (bf-clear)
[bf] 2021-09-19 18:00:00 | 00-clear: done. (bf-clear)
[cont-finish.d] 00-clear: exited 0.
[cont-finish.d] done.
[s6-finish] waiting for services.
[s6-finish] sending all processes the TERM signal.
[s6-finish] sending all processes the KILL signal and exiting.

(GitHub) (Docker Hub)

Acknowledgements

Comes pre-installed with the and all required dependencies.

Tags

In addition, you can add -dev and -beta suffixes to access development / test builds (see Docker Hub for further details).

Ports

Volumes

Environment Variables

Source files (GitHub) Container images (Docker Hub)

Acknowledgements

Based on the official PHP image for PHP 5.6.40 with Apache and mysql extension installed.

Ports

Volumes

Output

bf-debug

Echoes "$1: $2" to stdout in grey with prefix (see bf-e) - but only if environment variable BF_DEBUG is set to "1".

Arguments

1. Text to output

2. [Optional] Script / executable name

Usage

$ bf-debug "Hi"
[bf] 2021-09-19 18:00:00 | Hi # (in grey)

$ bf-debug "Hi" "alpine-s6/docs"
[bf] 2021-09-19 18:00:00 | alpine-s6/docs: Hi # (in grey)

bf-done

Echoes 'done.' to stdout in green with prefix (see bf-ok).

Arguments

1. [Optional] Script / executable name

Usage

$ bf-done
[bf] 2021-09-19 18:00:00 | done. # (in green)

$ bf-done "alpine-s6/docs"
[bf] 2021-09-19 18:00:00 | alpine-s6/docs: done. # (in green)

bf-e

Echoes $3 to stdout in colour $2 with prefix: "[$1] %Y-%m-%d %H:%M:%S".

Arguments

1. Namespace (default value for other output helper executables is 'bf')

2. ANSI colour code (see e.g. here)

3. Text to output

4. [Optional] Script / executable name

Usage

$ bf-e "docs" "\e[91m" "Hi"
[docs] 2021-09-19 18:00:00 | Hi # (in red)

$ bf-e "docs" "\e[92m" "Hi" "alpine-s6"
[docs] 2021-09-19 18:00:00 | alpine-s6: Hi # (in green)

bf-echo

Echoes "$1: $2" to stdout in default colour with prefix (see bf-e).

Arguments

1. Text to output

2. [Optional] Script / executable name

Usage

$ bf-echo "Hi"
[bf] 2021-09-19 18:00:00 | Hi # (in black / white)

$ bf-echo "Hi" "docs"
[bf] 2021-09-19 18:00:00 | docs: Hi # (in black / white)

bf-error

Echoes "$1: $2" to stdout in red with prefix (see bf-e), and returns 1. This will end execution of the calling script if you use, e.g. set -euo pipefail at the top of your scripts (recommended).

Arguments

1. Text to output

2. [Optional] Script / executable name

Usage

$ bf-error "Die"
[bf] 2021-09-19 18:00:00 | Die # (in red)

$ bf-error "Die" "docs"
[bf] 2021-09-19 18:00:00 | docs: Die # (in red)

bf-notok

Like bf-error echoes "$1: $2" to stdout in red with prefix, but doesn't end execution of calling script.

Arguments

1. Text to output

2. [Optional] Script / executable name

Usage

$ bf-notok "Error"
[bf] 2021-09-19 18:00:00 | Error # (in red)

$ bf-notok  "Error" "docs"
[bf] 2021-09-19 18:00:00 | docs: Error # (in red)

bf-ok

Echoes "$1: $2" to stdout in green with prefix.

Arguments

1. Text to output

2. [Optional] Script / executable name

Usage

$ bf-ok "Hi"
[bf] 2021-09-19 18:00:00 | Hi # (in green)

$ bf-ok  "Hi" "docs"
[bf] 2021-09-19 18:00:00 | docs: Hi # (in green)

Helpers

bf-adduser

Create user with id $2, group with id $3, both with name $1, and no password.

Arguments

1. User and group name

2. [Optional] User ID (default: 1000)

3. [Optional] Group ID (default: UID)

Usage

$ bf-adduser "fred"
[bf] 2021-09-19 18:00:00 | bf-adduser: Adding user and group 'fred'...
[bf] 2021-09-19 18:00:00 | bf-adduser: done. 'fred'... # (in green)
$ cat /etc/passwd
...
fred:x:1000:1000:Linux User,,,:/home/fred:/bin/ash

$ bf-adduser "fred" 1001
[bf] 2021-09-19 18:00:00 | bf-adduser: Adding user and group 'fred'...
[bf] 2021-09-19 18:00:00 | bf-adduser: done. 'fred'... # (in green)
$ cat /etc/passwd
...
fred:x:1001:1001:Linux User,,,:/home/fred:/bin/ash

$ bf-adduser "fred" 1002 1003
[bf] 2021-09-19 18:00:00 | bf-adduser: Adding user and group 'fred'...
[bf] 2021-09-19 18:00:00 | bf-adduser: done. 'fred'... # (in green)
$ cat /etc/passwd
...
fred:x:1002:1003:Linux User,,,:/home/fred:/bin/ash

bf-ch

Changes ownership and/or permissions of file / directory glob.

Arguments

Required (one or both):

• -o X use chown to set ownership to "X"

• -m Y use chmod to set permissions to "Y"

Optional:

• -t f|d apply only to files ("f") or directories ("d")

• -rif -t is not specified, applies action recursively to all files and directories

Usage

$ bf-ch -o "fred" -m 777 -t f /tmp
[bf] 2021-09-19 18:00:00 | bf-ch: Applying chown fred to /tmp.
[bf] 2021-09-19 18:00:00 | bf-ch:  .. type f.
[bf] 2021-09-19 18:00:00 | bf-ch: Applying chmod 777 to /tmp.
[bf] 2021-09-19 18:00:00 | bf-ch:  .. type f.

$ bf-ch -o "fred" -m 777 -r /tmp
[bf] 2021-09-19 18:00:00 | bf-ch: Applying chown fred to /tmp.
[bf] 2021-09-19 18:00:00 | bf-ch:  .. recursively.
[bf] 2021-09-19 18:00:00 | bf-ch: Applying chmod 777 to /tmp.
[bf] 2021-09-19 18:00:00 | bf-ch:  .. recursively.

bf-clear

Clears contents of /tmp and apk cache.

Usage

$ bf-clear
[bf] 2021-09-19 18:00:00 | bf-clear: Clearing /tmp...
[bf] 2021-09-19 18:00:00 | bf-clear: done.
[bf] 2021-09-19 18:00:00 | bf-clear: Clearing caches...
[bf] 2021-09-19 18:00:00 | bf-clear: done.

bf-esh

Calls esh in a consistent manner.

Arguments

1. Path to input (template) file

2. Path to output (generated) file

Usage

$ bf-esh /path/to/template /path/to/output
[bf] 2021-09-19 18:00:00 | bf-esh: /path/to/output created.

bf-image

Display name and version of the current image, and a link to the GitHub repository.

Usage

$ bf-image
[bf] 2021-09-19 18:00:00 | bf-image: bfren alpine 1.2.0.
[bf] 2021-09-19 18:00:00 | bf-image: https://github.com/bfren/docker-alpine.

bf-install

Run install /tmp/install and then perform cleanup (see bf-clear). Within the ecosystem this would normally be used in a Dockerfile

Usage

This is the basic structure of Dockerfiles based on the Alpine S6 image, copying overlay and then running the standard installation.

FROM bfren/alpine-s6:alpine3.14

COPY ./overlay /

RUN bf-install

bf-rmrf

Runs rm -rf $1 safely: doing nothing if $1 is empty. This is handy if the path you are deleting is contained in a variable (it effectively stops rm -rf /!).

Arguments

1. Folder path / file glob to delete.

Usage

$ bf-rmrf ""
[bf] 2021-09-19 18:00:00 | bf-rmrf: Cannot remove ''.

bf-rmrf /tmp/*
[bf] 2021-09-19 18:00:00 | bf-rmrf: Removing /tmp/*.

bf-rnd

Generates a string of random letters and numbers of length $1.

Arguments

1. [Optional] Number of characters to return

Usage

$ bf-rnd
7ceeezFaFzbuaHujA2ST2s3ACPAnAEoUqqVXBcdk

$ bf-rnd 10
D8ORzTX56m

$ RND=$(bf-rnd)
$ echo ${RND}
cm1HuNlkQwbqd5TeApoHsxfYE6X1MWxKnuiBbjFr

bf-test-url

Uses wget to test URL $1.

Arguments

1. URL to test

Usage

$ bf-test-url https://fake.url
[bf] 2021-09-19 18:00:00 | bf-test-url: Loading https://fake.url.
wget: bad address 'fake.url'

$ bf-test-url https://bbc.co.uk
[bf] 2021-09-19 18:00:00 | bf-test-url: Loading https://bbc.co.uk.
Connecting to bbc.co.uk (151.101.0.81:443)
Connecting to www.bbc.co.uk (212.58.237.254:443)
remote file exists

bf-tz

Sets the container's timezone to $1. (Installs tzdata package, changes timezone and then removes tzdata).

Arguments

1. Valid timezone (e.g. Europe/London)

Usage

Note the change in time on line 12.

$ bf-tz UTC
[bf] 2021-09-19 18:00:00 | bf-tz: Installing tzdata packages.
fetch https://dl-cdn.alpinelinux.org/alpine/v3.14/main/x86_64/APKINDEX.tar.gz
fetch https://dl-cdn.alpinelinux.org/alpine/v3.14/community/x86_64/APKINDEX.tar.gz
fetch https://dl-cdn.alpinelinux.org/alpine/edge/main/x86_64/APKINDEX.tar.gz
fetch https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz
(1/2) Installing tzdata (2021a-r0)
(2/2) Installing .tz (20210923.092854)
Executing busybox-1.33.1-r3.trigger
OK: 9 MiB in 17 packages
[bf] 2021-09-19 18:00:00 | bf-tz: Setting timezone to UTC...
[bf] 2021-09-19 17:00:00 | bf-tz: Removing tzdata packages.
(1/2) Purging .tz (20210923.092854)
(2/2) Purging tzdata (2021a-r0)
Executing busybox-1.33.1-r3.trigger
OK: 6 MiB in 15 packages
[bf] 2021-09-19 17:00:00 | bf-tz: done.

$ cat /etc/localtime
TZif2
UTCTZif2
UTC
UTC0

See Alpine S6: Executables.