1 of 33

Docker

Home

Welcome to the bfren Docker ecosystem

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

Alpine

The base image for the bfren ecosystem, containing Alpine Linux and various helper executables.

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.

Alpine Version

Tags

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

Environment Variables

Name

Values

Description

Default

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

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/):

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

Option 2: `/etc/crontabs/root`

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

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 if you don't want to break the cron further down the line.

Templating with esh

The image comes pre-installed with , 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.

Alpine: Executables

Various helper executables for providing standard output and simplifying common tasks.

Output

bf-debug

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

Arguments

Text to output
[Optional] Script / executable name

Usage

bf-done

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

Arguments

[Optional] Script / executable name

Usage

bf-e

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

Arguments

Namespace (default value for other output helper executables is 'bf')
ANSI colour code (see e.g. )
Text to output

Usage

bf-echo

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

Arguments

Text to output
[Optional] Script / executable name

Usage

bf-error

Echoes "$1: $2" to stdout in red with prefix (see ), 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

Text to output
[Optional] Script / executable name

Usage

bf-notok

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

Arguments

Text to output
[Optional] Script / executable name

Usage

bf-ok

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

Arguments

Text to output
[Optional] Script / executable name

Usage

Helpers

bf-adduser

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

Arguments

User and group name
[Optional] User ID (default: 1000)
[Optional] Group ID (default: UID)

Usage

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-clear

Clears contents of /tmp and apk cache.

Usage

bf-esh

Calls esh in a consistent manner.

Arguments

Path to input (template) file
Path to output (generated) file

Usage

bf-image

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

Usage

bf-install

Run install /tmp/install and then perform cleanup (see ). 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.

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

Folder path / file glob to delete.

Usage

bf-rnd

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

Arguments

[Optional] Number of characters to return

Usage

bf-test-url

Uses wget to test URL $1.

Arguments

URL to test

Usage

bf-tz

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

Arguments

Valid timezone (e.g. Europe/London)

Usage

Note the change in time on line 12.

Alpine S6

The base image for much of the bfren ecosystem, containing Alpine Linux installed with the S6 Overlay.

(GitHub) (Docker Hub)

Acknowledgements

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

Alpine S6: Executables

Various helper executables for interacting with S6 and the container environment.

Output

bf-svc-finish

Debian

The base image for the bfren ecosystem, containing Alpine Linux and various helper executables.

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.

Debian Version

Tags

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 .

Debian: Executables

Various helper executables for providing standard output and simplifying common tasks.

See Alpine: Executables.

Debian S6

Another base image for the bfren ecosystem, containing Debian installed with the S6 Overlay.

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 .

Debian S6: Executables

Various helper executables for interacting with S6 and the container environment.

See Alpine S6: Executables.

Base Images

Apache PHP

Base Apache + PHP image with MySQL enabled.

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

Port

Description

Volumes

Volume

Purpose

ASP.NET

.NET and ASP.NET runtimes pre-installed (versions 3.1, 5.0, and 6.0).

Source files (GitHub) Container images (Docker Hub)

Acknowledgements

Comes pre-installed with the ASP.NET runtime and all required dependencies.

Tags

.NET Version

Tags

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

Ports

Port

Description

Volumes

Volume

Purpose

Environment Variables

Name

Values

Description

Default

ASP.NET: Executables

Various helper executables for interacting with your .NET application.

Helpers

aspnet-restart

Restarts ASP.NET application.

Usage

aspnet-start

Starts ASP.NET application.

If you try to start an application that is already running you will get an error as it won't be able to bind to port 5000. You should never need to use this executable as it is called when the container starts.

Usage

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

healthcheck

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

Usage

ClamAV

ClamAV set up to run in daemon mode over the default port (3310).

FTPS

Very Secure FTP (vsftpd) supporting TLS file transfer.

MariaDB

Latest stable releases of MariaDB with automated backups.

MariaDB: Executables

Nginx

Super lightweight Nginx image with various helper configuration files.

Nginx: Helpers

Nginx: Executables

Nginx PHP

Nginx base image with PHP (7.3, 7.4, and 8.0).

Nginx PHP: Executables

Nginx Proxy

Automated proxy server using Nginx base image and the getssl script.

Nginx Proxy: Executables

Nginx WebDAV

Nginx base image with WebDAV extensions.

PHP

PHP installed by itself to be used in CLI mode.

PostgreSQL

Latest stable releases of PostgreSQL with automated backups.

PostgreSQL: Executables

Redis

Latest redis cache server running in daemon mode over the default port (6379).

Applications

FreeScout

Ready-to-go FreeScout helpdesk with all PHP dependencies.

FreshRSS

Ready-to-go FreshRSS news reader with all PHP dependencies.

WordPress

Ready-to-go WordPress helpdesk with all PHP dependencies.

Alpine: Executables

Various helper executables for providing standard output and simplifying common tasks.

Output

bf-debug

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

Arguments

Text to output
[Optional] Script / executable name

Usage

bf-done

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

Arguments

[Optional] Script / executable name

Usage

bf-e

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

Arguments

Namespace (default value for other output helper executables is 'bf')
ANSI colour code (see e.g. )
Text to output

Usage

bf-echo

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

Arguments

Text to output
[Optional] Script / executable name

Usage

bf-error

Echoes "$1: $2" to stdout in red with prefix (see ), 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

Text to output
[Optional] Script / executable name

Usage

bf-notok

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

Arguments

Text to output
[Optional] Script / executable name

Usage

bf-ok

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

Arguments

Text to output
[Optional] Script / executable name

Usage

Helpers

bf-adduser

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

Arguments

User and group name
[Optional] User ID (default: 1000)
[Optional] Group ID (default: UID)

Usage

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-clear

Clears contents of /tmp and apk cache.

Usage

bf-esh

Calls esh in a consistent manner.

Arguments

Path to input (template) file
Path to output (generated) file

Usage

bf-image

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

Usage

bf-install

Run install /tmp/install and then perform cleanup (see ). 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.

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

Folder path / file glob to delete.

Usage

bf-rnd

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

Arguments

[Optional] Number of characters to return

Usage

bf-test-url

Uses wget to test URL $1.

Arguments

URL to test

Usage

bf-tz

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

Arguments

Valid timezone (e.g. Europe/London)

Usage

Note the change in time on line 12.

Docker

Home

hashtagLicence

Alpine

hashtagAcknowledgements

hashtagTags

hashtagEnvironment Variables

hashtagPackages

hashtagCron

hashtagOption 1: /etc/periodic/

hashtagOption 2: /etc/crontabs/root

hashtagTemplating with esh

Alpine: Executables

hashtagOutput

hashtagbf-debug

hashtagArguments

hashtagUsage

hashtagbf-done

hashtagArguments

hashtagUsage

hashtagbf-e

hashtagArguments

hashtagUsage

hashtagbf-echo

hashtagArguments

hashtagUsage

hashtagbf-error

hashtagArguments

hashtagUsage

hashtagbf-notok

hashtagArguments

hashtagUsage

hashtagbf-ok

hashtagArguments

hashtagUsage

hashtagHelpers

hashtagbf-adduser

hashtagArguments

hashtagUsage

hashtagbf-ch

hashtagArguments

hashtagUsage

hashtagbf-clear

hashtagUsage

hashtagbf-esh

hashtagArguments

hashtagUsage

hashtagbf-image

hashtagUsage

hashtagbf-install

hashtagUsage

hashtagbf-rmrf

hashtagArguments

hashtagUsage

hashtagbf-rnd

hashtagArguments

hashtagUsage

hashtagbf-test-url

hashtagArguments

hashtagUsage

hashtagbf-tz

hashtagArguments

hashtagUsage

Alpine S6

hashtagAcknowledgements

Alpine S6: Executables

hashtagOutput

hashtagbf-svc-finish

Debian

hashtagAcknowledgements

hashtagTags

hashtagEnvironment Variables, Packages, Cron & Templating

Debian: Executables

Debian S6

hashtagAcknowledgements

hashtagEnvironment Variables, Packages, Layout

Debian S6: Executables

Base Images

Apache PHP

hashtagAcknowledgements

Licence

Acknowledgements

Tags

Environment Variables

Packages

Cron

Option 1: `/etc/periodic/`

Option 2: `/etc/crontabs/root`

Templating with esh

Output

bf-debug

Arguments

Usage

bf-done

Arguments

Usage

bf-e

Arguments

Usage

bf-echo

Arguments

Usage

bf-error

Arguments

Usage

bf-notok

Arguments

Usage

bf-ok

Arguments

Usage

Helpers

bf-adduser

Arguments

Usage

bf-ch

Arguments

Usage

bf-clear

Usage

bf-esh

Arguments

Usage

bf-image

Usage

bf-install

Usage

bf-rmrf

Arguments

Usage

bf-rnd

Arguments

Usage

bf-test-url

Arguments

Usage

bf-tz

Arguments

Usage

Acknowledgements

Output

bf-svc-finish

Acknowledgements

Tags

Environment Variables, Packages, Cron & Templating

Acknowledgements

Environment Variables, Packages, Layout

Acknowledgements

Ports

Volumes

Acknowledgements

Tags

Ports

Volumes

Environment Variables

Helpers

aspnet-restart

Usage

aspnet-start

Usage