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...
MIT (unless otherwise stated). Copyright (c) 2020-2022 bfren (unless otherwise stated).
Various helper executables for providing standard output and simplifying common tasks.
Echoes "$1
: $2
" to stdout
in grey with prefix (see bf-e) - but only if environment variable BF_DEBUG
is set to "1".
Text to output
[Optional] Script / executable name
Echoes 'done.' to stdout
in green with prefix (see bf-ok).
[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')
ANSI colour code (see e.g. here)
Text to output
[Optional] Script / executable name
Echoes "$1
: $2
" to stdout
in default colour with prefix (see bf-e).
Text to output
[Optional] Script / executable name
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).
Text to output
[Optional] Script / executable name
Like bf-error echoes "$1
: $2
" to stdout
in red with prefix, but doesn't end execution of calling script.
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")
-r
if -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.
Run install /tmp/install
and then perform cleanup (see bf-clear). Within the ecosystem this would normally be used in a Dockerfile
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.
The base image for the bfren ecosystem, containing Alpine Linux and various helper executables.
Source files (GitHub) Container images (Docker Hub)
Docker Alpine is a tiny distribution of Linux designed specifically for use in containers.
esh is a lightweight templating engine using POSIX-compatible syntax.
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).
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.
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/
):
It's pretty obvious how frequently they run! An example of this method can be found in the Nginx PHP image.
/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 default directives if you don't want to break the cron further down the line.
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
.
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
My rule of thumb is that the first image uses 0-based files. Then the next uses 1-based files, then 2-based, etc. As S6 loads these files alphabetically, this practice ensures base permissions and configuration is always done first.
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..
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.
Alpine Version | Tags |
---|---|
Name | Values | Description | Default |
---|---|---|---|
(GitHub) (Docker Hub)
The is a version of the S6 supervisor which has various useful features for containers and managing services.
Name | Values | Description | Default |
---|
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.
Re-applies attributes and permissions defined in /etc/fix-attrs.d
. Based on code from .
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
BF_DEBUG
0 or 1
Set to 0 to disable debug log output messages.
1
| 0-8 | Cron log level (0 is most verbose). | 8 |
Another base image for the bfren ecosystem, containing Debian installed with the S6 Overlay.
Source files (GitHub) Container images (Docker Hub)
The S6 Overlay is a version of the S6 supervisor which has various useful features for containers and managing services.
See Alpine S6.
Various helper executables for providing standard output and simplifying common tasks.
See Alpine: Executables.
The base image for the bfren ecosystem, containing Alpine Linux and various helper executables.
Source files (GitHub) Container images (Docker Hub)
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.
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).
See Alpine.
Various helper executables for interacting with S6 and the container environment.
Debian Version | Tags |
---|---|
See .
(GitHub) (Docker Hub)
Based on the for PHP 5.6.40 with Apache and mysql
extension installed.
Port | Description |
---|
Volume | Purpose |
---|
(GitHub) (Docker Hub)
Comes pre-installed with the and all required dependencies.
.NET Version | Tags |
---|
Port | Description |
---|
Volume | Purpose |
---|
Name | Values | Description | Default |
---|
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
| Serves HTTP content (Apache requires permissions for user 1000, e.g. |
| From base image: files are served from this directory. |
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 |
| Serves HTTP content from your application. |
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').
Uses bf-test-url to request the URL set by ASPNETCORE_URLS
and exits with code 0 if response is HTTP 200 OK
.
| Contains live application files. |
|
| string | The filename of the assembly to execute. | None - required |
| string | Default value binds web server to port 5000 - should not normally need to be changed. |
| 'true' or 'false' | This should always be set to true - it tells dotnet that it is running in a container environment. | 'true' |
| 'true' or 'false' | 'true' |
Publish updated files to this directory and use to make it go live.
See and .