Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
ClamAV set up to run in daemon mode over the default port (3310).
Very Secure FTP (vsftpd) supporting TLS file transfer.
Latest stable releases of MariaDB with automated backups.
Super lightweight Nginx image with various helper configuration files.
Nginx base image with PHP (7.3, 7.4, and 8.0).
Automated proxy server using Nginx base image and the getssl script.
Nginx base image with WebDAV extensions.
PHP installed by itself to be used in CLI mode.
Latest stable releases of PostgreSQL with automated backups.
Latest redis cache server running in daemon mode over the default port (6379).
Ready-to-go FreeScout helpdesk with all PHP dependencies.
Ready-to-go FreshRSS news reader with all PHP dependencies.
Ready-to-go WordPress helpdesk with all PHP dependencies.
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...
(unless otherwise stated). Copyright (c) 2020-2022 bfren (unless otherwise stated).
Various helper executables for interacting with S6 and the container environment.
Outputs service closing down debug message and optionally terminates all running services. Usually used in /etc/services.d/xxx/finish file to show
-s X outputs a message that service "X" is shutting down
-t terminates all other services as well
Clears contents of /etc/bf/src.
Run all scripts within a cron directory.
-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
Adds a container environment variable called $1 with value $2.
Variable name
Variable value
Forwards errors logged in $2 to Docker logs; if $2 is not set, disables service $1.
Service name.
Absolute path to log file.
Uses S6 to control the service named $2.
Control action: 'disable', 'restart', 'start', 'stop'
Service name
Terminates all running services - usually used in /etc/services.d/xxx/finish file - which also closes down (and potentially restarts) the whole container.
Various helper executables for providing standard output and simplifying common tasks.
Text to output
[Optional] Script / executable name
[Optional] Script / executable name
Echoes $3 to stdout in colour $2 with prefix:
"[$1] %Y-%m-%d %H:%M:%S".
Namespace (default value for other output helper executables is 'bf')
Text to output
[Optional] Script / executable name
Text to output
[Optional] Script / executable name
Text to output
[Optional] Script / executable name
Text to output
[Optional] Script / executable name
Echoes "$1: $2" to stdout in green with prefix.
Text to output
[Optional] Script / executable name
Create user with id $2, group with id $3, both with name $1, and no password.
User and group name
[Optional] User ID (default: 1000)
[Optional] Group ID (default: UID)
Changes ownership and/or permissions of file / directory glob.
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
Clears contents of /tmp and apk cache.
Calls esh in a consistent manner.
Path to input (template) file
Path to output (generated) file
Display name and version of the current image, and a link to the GitHub repository.
This is the basic structure of Dockerfiles based on the Alpine S6 image, copying overlay and then running the standard installation.
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 /!).
Folder path / file glob to delete.
Generates a string of random letters and numbers of length $1.
[Optional] Number of characters to return
Uses wget to test URL $1.
URL to test
Sets the container's timezone to $1. (Installs tzdata package, changes timezone and then removes tzdata).
Valid timezone (e.g. Europe/London)
Note the change in time on line 12.
Re-applies attributes and permissions defined in /etc/fix-attrs.d. Based on code from .
Echoes "$1: $2" to stdout in grey with prefix (see ) - but only if BF_DEBUG is set to "1".
Echoes 'done.' to stdout in green with prefix (see ).
ANSI colour code (see e.g. )
Echoes "$1: $2" to stdout in default colour with prefix (see ).
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).
Like echoes "$1: $2" to stdout in red with prefix, but doesn't end execution of calling script.
Run install /tmp/install and then perform cleanup (see ). Within the ecosystem this would normally be used in a Dockerfile
The base image for the bfren ecosystem, containing Alpine Linux and various helper executables.
(GitHub) (Docker Hub)
The is a version of the S6 supervisor which has various useful features for containers and managing services.
See .
(GitHub) (Docker Hub)
Based on the for PHP 5.6.40 with Apache and mysql extension installed.
(GitHub) (Docker Hub)
is a cut-down distribution of designed specifically for use in containers.
is a lightweight templating engine using POSIX-compatible syntax.
See .
10 (buster)
debian10, debian10-x, debian10-x.x, debian10-x.x.x
11 (bullseye)
debian11, debian11-x, debian11-x.x, debian11-x.x.x
12 (bookworm)
debian12, debian12-x, debian12-x.x, debian12-x.x.x
sid
debiansid, debiansid-x, debiansid-x.x, debiansid-x.x.x
.NET and ASP.NET runtimes pre-installed (versions 3.1, 5.0, and 6.0).
3.1
net3, net3.1, net3.1.21
5.0
net5, net5.0, net5.0.12
6.0
latest, net6, net6.0, net6.0.0
In addition, you can add -dev and -beta suffixes to access development / test builds (see Docker Hub for further details).
5000
Serves HTTP content from your application.
/app/live
Contains live application files.
/app/publish
ASPNET_ASSEMBLY
string
The filename of the assembly to execute.
None - required
ASPNETCORE_URLS
string
Default value binds web server to port 5000 - should not normally need to be changed.
DOTNET_RUNNING_IN_CONTAINER
'true' or 'false'
This should always be set to true - it tells dotnet that it is running in a container environment.
'true'
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
'true' or 'false'
'true'
The base image for the bfren ecosystem, containing Alpine Linux and various helper executables.
x.x and x.x.x refer to the bfren image versions.
3.12
alpine3.12, alpine3.12.9, alpine3.12-x.x, alpine3.12-x.x.x
3.13
alpine3.13, alpine3.13.7, alpine 3.13-x.x, alpine3.13-x.x.x
3.14
alpine3.14, alpine3.14.3, alpine3.14-x.x, alpine3.14-x.x.x
3.15
latest, alpine3, alpine3.15, alpine3.15.0, alpine3.15-x.x, alpine3.15-x.x.x
edge
alpineedge, alpineedge-x.x, alpineedge-x.x.x
In addition, you can add -dev and -beta suffixes to access development / test builds (see Docker Hub for further details).
BF_DEBUG
0 or 1
Set to 0 to disable debug log output messages.
1
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.
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.
/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/):
/etc/crontabs/rootIf you want more control over your cron tasks you can create a normal crontab file:
All dynamic configuration files in the bfren ecosystem are built using esh, and the default location for those templates is /etc/bf/templates.
Various helper executables for providing standard output and simplifying common tasks.
Various helper executables for interacting with S6 and the container environment.
Various helper executables for interacting with your .NET application.
Restarts ASP.NET application.
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.
Stops ASP.NET application, switches live and published code, and terminates the container (you will need to have the restart policy set to 'always').
The base image for much of the bfren ecosystem, containing Alpine Linux installed with the S6 Overlay.
The image comes with the S6 Overlay and all its dependencies.
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.
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):
/etc/fix-attrs.d/ - set required permissions
/etc/cont-init.d/ - run initialisation scripts
/etc/services.d/ - register the services you want to be supervised
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
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.
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.)
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.
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.
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:
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.
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..
(GitHub) (Docker Hub)
Comes pre-installed with the and all required dependencies.
Publish updated files to this directory and use to make it go live.
See and .
(GitHub) (Docker Hub)
is a tiny distribution of Linux designed specifically for use in containers.
is a lightweight templating engine using POSIX-compatible syntax.
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 .)
It's pretty obvious how frequently they run! An example of this method can be found in the image.
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.
The image comes pre-installed with , a simple shell-based templating engine. It is extremely lightweight, and very easy to use.
See .
See .
Uses to request the URL set by ASPNETCORE_URLS and exits with code 0 if response is HTTP 200 OK.
(GitHub) (Docker Hub)
The is a version of the S6 supervisor which has various useful features for containers and managing services.
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.
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 .
For example, in the image the following two scripts run in this stage:/etc/cont-init.d/10-initial # downloads the latest virus definitions
So, for example, in the image, the main service is nginx itself, but there are also two services to manage logging.
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.
BF_CRON_LOG_LEVEL
0-8
Cron log level (0 is most verbose).
8