alpine-s6

MultiArch Alpine Linux + S6 Init System.

This image serves as a base image for applications / services that need an init system to launch the process(es) and pass the proper signals when interacted with the containers.

Based on Alpine Linux (v3.22) from the base image with the s6 init system overlayed on it. Versioned accordingly with releases from /just-containers/s6-overlay.

Get the Image¶

Docker Hub

Pull the image from Docker Hub.


docker pull woahbase/alpine-s6

Image Tags

The image is tagged respectively for the following architectures,

latest tag is annotated as multiarch so pulling without specifying any architecture tags should fetch the correct image for your architecture. Same goes for any of the version tags.

non-x86_64 images used to contain the embedded qemu-user-static binary which has been redundant for a while, and is being deprecated starting with our Alpine Linux v3.22 base-image release, see qemu-user-static or the more recent binfmt instead for running multi-arch containers.

Run¶

Run bash in the container to get a shell, or switch the entrypoint to /usershell to get a user-scoped shell.

shelluser-scoped shell


docker run --rm --name docker_s6 woahbase/alpine-s6 /bin/bash


docker run --rm -it --name docker_s6 --entrypoint /usershell woahbase/alpine-s6 /bin/bash

Multi-Arch Support

If you want to run images built for other architectures on the same host (e.g. a x86_64 machine), you will need to have the specific binary format support configured on your host machine before running the image (otherwise you get an exec format error). Here's how,

binfmtqemu-user-static

For recent images, we can use tonistiigi's binfmt image to register binary execution support for the target architecture, like the following,


docker run --rm --privileged tonistiigi/binfmt --install <architecture>

Architecture is that of the image we're trying to run, can be arm64 for aarch64, arm for both armv7l and armhf, or amd64 for x86_64. See binfmt.

Previously, multiarch, had made it easy for us by packing qemu into an image, so we could just run


docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

However, that image (see qemu-user-static) seems to have fallen behind in updates, and with newer images the binfmt method is preferable.

Now images built for other architectures will also be executable. This is optional though, without the above, you can still run the image that is specifically made to support your host architecture.

Configuration¶

We can customize the runtime behaviour of the container with the following environment variables.

ENV Vars	Default	Description
S6_NEEDED_PACKAGES	empty string	Space-separated list of extra APK packages to install on start. E.g. `"curl git tzdata"`
PUID	1000	Id of `${S6_USER}`.
PGID	1000	Group id of `${S6_USER}`.
S6_USER	alpine	(Preset) Default non-root user for services to drop privileges to.
S6_USERHOME	/home/alpine	(Preset) HOME directory for `${S6_USER}`.
S6_USERGROUPS	empty string	Comma-separated list of groups to add `${S6_USER}` to. E.g. `"audio,video,tty"`, groups must exist.
S6_USERPASS	unset	Password for `${S6_USER}`.
FILEURL_`varname`	unset	If set to `<url>\|<optional /file/path>`, will download `url` to `/file/path`. See URL to File. (since 3.2.1.0)
HGID_`groupname`	unset	Update (or create) `groupname` with non-zero positive integer `gid` (to match with host). E.g `HGID_VIDEO=995` will change (or create if not exists) `gid` of `video` group to `995`. (since 3.2.0.0)
SECRET__`varname`	unset	If set to a filepath, the contents of file are loaded in the environment variable `varname` (Note the double underscores). See Secrets.
TRUSTED_CERTS	unset	Space-or-comma-separated certificate files, those are merged into the root (or `nssdb`) certificate store. See Custom Certificates. (since 3.2.1.0_20250516)
TRUSTED_SITES	unset	Space-or-comma-separated server names, the certificates are fetched are merged into the root (or `nssdb`) certificate store. See Custom Certificates. (since 3.2.1.0_20250516)

Did you know?

You can check your own UID/GID by running the command id in a terminal.

But wait!! There's more...

Secrets¶

To use docker-secrets that are available inside the container as pre-exported environment variables, we can specify the variable as SECRET__variablename with the path to the secret-file set as the value, and at runtime the helper-script should read and export the secret as the value of variablename. These environment variables are available to any scope that uses container-env (with-contenv).

Custom Certificates¶

To install and trust your own certificates into the container, whether obtained from a third party or especially when self-signed, we can use the helper-script (since 3.2.1.0_20250516) to merge the certificate files listed in TRUSTED_CERTS environment variable (or fetch those from servers listed in TRUSTED_SITES using openssl) into the root certificate store (requires ca-certificates), or any nssdb database (requires nssdb-tools for certutil / pk12util).

Custom Certificate defaults and examples

These environment variable control how the custom certificates are updated into the store.

ENV Vars	Default	Description
S6_CERTDIR	/usr/local/share/certificates	Directory where the certificates are copied or downloaded.
S6_CACERTDIR	/usr/local/share/ca-certificates	(Preset) Directory where the CA certificates are (checked and if success) moved into, before merge. This ensures we don't end up adding non-CA certificates in the root certificate store.
S6_CACERT_INCLUDE_NONCA	unset	Set to `true` to enable including non-ca-certificate files into root certificate store. Rather insecure, but gets rid of most `unable to get local issuer certificate` errors during develop/test. Use with caution, definitely not in production and only with certificates that you really trust, but for some odd reason cannot provide the issuer-CA-Cert for them, or have signed them yourself.
S6_CERTUPDATE	unset	Enabled when atleast one certificate is located, set to `1` to force-refresh the store.
NSS_DBDIR	unset	Path to `nssdb` database dir. E.g. `/home/alpine/.pki/nssdb` or `/etc/pki/nssdb`. Required for nss-specific tasks to run.
NSS_DEFAULT_DB_TYPE	sql	Format of `nssdb`, legacy ones used to be `dbm`.
NSS_DBDIR_OWNER	unset	To apply ownership to the database, set it to e.g. `root:root`, if unset, but the path in inside `${S6_USER}`-homedir, it defaults to `alpine:${PGID}`.
NSS_TRUST	P,P,,	Default trust for server certificates when installing in `nssdb`.
NSS_CATRUST	CT,C,C,	Default trust for CA certificates when installing in `nssdb`.

The environment variables TRUSTED_CERTS and TRUSTED_SITES are space-or-comma-separated lists of file (or directory) path and server[:port-optional] (port defaults to 443) addresses respectively. E.g.


TRUSTED_CERTS="/crts/cert1.ca.crt /crts/cert2.crt /crts/cert3.pfx"


TRUSTED_SITES="example.com test.net:443 hello.world.local:64801"

The required packages may or may not be installed depending on the image, for the latter, they can be installed at runtime by adding them in the S6_NEEDED_PACKAGES variable. Recommended to preserve-and-remount the certificate stores for subsequent runs to reduce the mutable surface area.

URL to File¶

To fetch a file (or a .tar.gz archive) from your local file-server (or any public URL) into the container, use the environment variable FILEURL_variablename helper-script (since 3.2.1.0). This will fetch the file from the specified URL, optionally put the file in specified filepath (in /defaults if not specified). If the URL points to a .tar.gz archive, it is unpacked in the specified directory.

URL-to-File defaults and few examples

These environment variable control how the file is downloaded and unpacked.

ENV Vars	Default	Description
S6_FILEURL_DEFDIR	/defaults/	Default directory where the file is downloaded/unpacked when no filepath is specified.
S6_FILEURL_DEFOWNER	root:root	Default owner/group for a downloaded file. Does not apply to unpacked archives by default, set `S6_FILEURL_FIXOWNER_UNPACK` to a non-empty string e.g. `1` to enable for unpacked archives.
S6_FILEURL_DEFPERMS	0644	Default permissions for a downloaded file. Does not apply to unpacked archives.
S6_FILEURL_DELIMITER	`\|`	Delimiter to separate the `url` and `/file/path`.
S6_FILEURL_RETRIES	5	Number of retries for fetching a file, sleeps `5` seconds between retries.
S6_FILEURL_STRIPCOMPONENTS	0	For stripping directories when unpacking a downloaded archive.
S6_FILEURL_TMPDIR	/tmp/	Directory where the temporary file is downloaded before moving into proper place.

For example,

Value of FILEURL_(variablename)	Action
`https://test.site/a.txt`	Get `a.txt` in `/defaults`.
`https://test.site/a.txt\|/srv/`	Get `a.txt` in `/srv`.
`https://test.site/a.txt\|/srv/b.txt`	Get `a.txt` contents in `/srv/b.txt`.
`https://test.site/c.tar.gz`	Get and unpack `c.tar.gz` in `/defaults`.
`https://test.site/c.tar.gz\|/srv/`	Get and unpack `c.tar.gz` in `/srv`.
`https://test.site/c.tar.gz\|/srv/d.tar.gz`	Get `c.tar.gz` as `/srv/d.tar.gz` but don't unpack it.

There are some limitations, it uses busybox wget so authentications are not supported (although retries are) so use it with a hint of caution, and it only supports unpacking for .tar.gz archives. The variable-name has no effect at the moment, but for the value, remember to specify only full-paths (beginning with a /) for filepaths, and end with a / to distinguish between files and directories.

Usershell¶

Docker images by default, do not provide a easy way to dynamically drop privileges to a user before executing CMD definitions, it is not always feasible to hardcode those in the Dockerfile and it becomes more complex with the additional initialization stages that s6 introduces. To ease this problem, in addition to the /init entrypoint script that s6 brings, another alternate init-script is added at /usershell that run the initialization stage tasks as root, and then execute the CMD as a not-root user. This way, images that set their entrypoint to /usershell have all the benefits of s6, but the CMD that is run, is run by ${S6_USER} (by default alpine). Checkout any of the images tagged usershell for an example.

Build Your Own¶

Feel free to clone (or fork) the repository and customize it for your own usage, build the image for yourself on your own systems, and optionally, push it to your own public (or private) repository.

Here's how...

Setting up¶

Before we clone the /repository, we must have Git, GNU make, and Docker (optionally, with buildx plugin for multi-platform images) setup on the machine. Also, for multi-platform annotations, we might require enabling experimental features of Docker.

Now, to get the code,

Github

Clone the repository with,


git clone https://github.com/woahbase/alpine-s6
cd alpine-s6

To get a list of all available targets, run


make help

Always Check Before You Make!

Did you know, we could check what any make target is going to execute before we actually run them, with


make -n <targetname> <optional args>

Build and Test¶

To create the image for your architecture, run the build and test target with


make build test

For building an image that targets another architecture, it is required to specify the ARCH parameter when building. e.g.

aarch64armhfarmv7li386ppc64leriscv64s390xx86_64


make build test ARCH=aarch64


make build test ARCH=armhf


make build test ARCH=armv7l


make build test ARCH=i386


make build test ARCH=ppc64le


make build test ARCH=riscv64


make build test ARCH=s390x


make build test ARCH=x86_64

Build Parameters

All images have a few common build parameters that can be customized at build time, like

ARCH

The target architecture to build for. Defaults to host architecture, auto-detected at build-time if not specified. Also determines if binfmt support is required before build or run and runs the regbinfmt (or inbinfmt for recent images) target automatically. Possible values could be aarch64, armhf, armv7l, or x86_64.

BUILDDATE

The date of the build. Can be used to create separate tags for images. (format: yyyymmdd)

DOCKERFILE

The dockerfile to use for build. Defaults to the file Dockerfile, but if per-arch dockerfiles exist, (e.g. for x86_64 the filename would be Dockerfile_x86_64) that is used instead.

TESTCMD

The command to run for testing the image after build. Runs in a bash shell.

VERSION

The version of the app/tool, may need to be preset before starting the build (e.g. for binaries from github releases), or extracted from the image after build (e.g. for APK or pip packages).

REGISTRY

The registry to push to, defaults to the Docker Hub Registry (docker.io) or any custom registry that is set via docker configurations. Does not need to be changed for local or test builds, but to override, either pass it by setting an environment variable, or with every make command.

ORGNAME

The organization (or user) name under which the image repositories exist, defaults to woahbase. Does not need to be changed for local or test builds, but to override, either pass it by setting an environment variable, or with every make command.

The image may also require custom parameters (like binary architecture). Before you build, check the makefile for a complete list of parameters to see what may (or may not) need to be set.

BuildX and Self-signed certificates

If you're using a private registry (a-la docker distribution server) with self-signed certificates, that fail to validate when pulling/pushing images. You will need to configure buildx to allow insecure access to the registry. This is configured via the config.toml file. A sample is provided in the repository, make sure to replace YOUR.PRIVATE.REGISTRY with your own (include port if needed).

Make to Run¶

Running the image creates a container and either starts a service (for service images) or provides a shell (can be either a root-shell or usershell) to execute commands in, depending on the image. We can run the image with


make run

But if we just need a root-shell in the container without any fance pre-tasks (e.g. for debug or to test something bespoke), we can run bash in the container with --entrypoint /bin/bash. This is wrapped in the makefile as


make shell

Nothing vs All vs Run vs Shell

By default, if make is run without any arguments, it calls the target all. In our case this is usually mapped to the target run (which in turn may be mapped to shell).

There may be more such targets defined as per the usage of the image. Check the makefile for more information.

Push the Image¶

If the build and test steps finish without any error, and we want to use the image on other machines, it is the next step push the image we built to a container image repository (like /hub), for that, run the push target with


make push

If the built image targets another architecture then it is required to specify the ARCH parameter when pushing. e.g.

aarch64armhfarmv7li386ppc64leriscv64s390xx86_64


make push ARCH=aarch64


make push ARCH=armhf


make push ARCH=armv7l


make push ARCH=i386


make push ARCH=ppc64le


make push ARCH=riscv64


make push ARCH=s390x


make push ARCH=x86_64

Pushing Multiple Tags

With a single make push, we are actually pushing 3 tags of the same image, e.g. for x86_64 architecture, they're namely

alpine-s6:x86_64

The actual image that is built.

alpine-s6:x86_64_${version}

It is expected that the application is versioned when built or packaged, it can be specified in the tag, this makes pulling an image by tag possible. Usually this is obtained from the parameter VERSION, which by default, is set by calling a function to extract the version string from the package installed in the container, or from github releases. Can be skipped with the parameter SKIP_VERSIONTAG to a non-empty string value like 1.

alpine-s6:x86_64_${version}_${builddate}

When building multiple versions of the same image (e.g. for providing fixes or revisions), this ensures that a more recent push does not fully replace a previously pushed image. This way, although the architecture and version tags are replaced, it is possible to roll back to the previously built image by build date (format yyyymmdd). This value is obtained from the BUILDDATE parameter, and if not essential, can be skipped by setting the parameter SKIP_BUILDDATETAG to a non-empty string value like 1.

Pushing To A Private Registry

If you want to push the image to a custom registry that is not pre-configured on your system, you can set the REGISTRY variable either on the build environment, or as a makefile parameter, and that will be used instead of the default Docker Hub repository. Make sure to have push access set up before you actually push, and include port if needed. E.g.


export REGISTRY=your.private.registry:5000
make build test push

or


make build test push REGISTRY=your.private.registry:5000

Annotate Manifest(s)¶

For single architecture images, the above should suffice, the built image can be used in the host machine, and on other machines that have the same architecture too, i.e. after a push.

But for use-cases that need to support multiple architectures, there's a couple more things that need to be done. We need to create (or amend if already created beforehand) a manifest for the image(s) that we built, then annotate it to map the images to their respective architectures. And for our three tags created above we need to do it thrice.

Did you know?

We can inspect the manifest of any image by running


docker manifest inspect <imagename>:<optional tag, default is latest>

Tag Latest¶

Assuming we built the images for all supported architectures, to facilitate pulling the correct image for the architecture, we can create/amend the latest manifest and annotate it to map the tags :aarch64, :armhf, :armv7l, :i386, :ppc64le, :riscv64, :s390x, :x86_64 to the tag :latest by running


make annotate_latest

How it works

First we create or amend the manifest with the tag latest

createamend


docker manifest create \
woahbase/alpine-s6:latest \
woahbase/alpine-s6:aarch64 \
woahbase/alpine-s6:armhf \
woahbase/alpine-s6:armv7l \
woahbase/alpine-s6:i386 \
woahbase/alpine-s6:ppc64le \
woahbase/alpine-s6:riscv64 \
woahbase/alpine-s6:s390x \
woahbase/alpine-s6:x86_64 \
;


docker manifest create --amend \
woahbase/alpine-s6:latest \
woahbase/alpine-s6:aarch64 \
woahbase/alpine-s6:armhf \
woahbase/alpine-s6:armv7l \
woahbase/alpine-s6:i386 \
woahbase/alpine-s6:ppc64le \
woahbase/alpine-s6:riscv64 \
woahbase/alpine-s6:s390x \
woahbase/alpine-s6:x86_64 \
;

Then annotate the image for each architecture in the manifest with

aarch64armhfarmv7li386ppc64leriscv64s390xx86_64


docker manifest annotate --os linux --arch arm64 \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:aarch64;


docker manifest annotate --os linux --arch arm --variant v6 \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:armhf;


docker manifest annotate --os linux --arch arm --variant v7 \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:armv7l;


docker manifest annotate --os linux --arch 386 \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:i386;


docker manifest annotate --os linux --arch ppc64le \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:ppc64le;


docker manifest annotate --os linux --arch riscv64 \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:riscv64;


docker manifest annotate --os linux --arch s390x \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:s390x;


docker manifest annotate --os linux --arch amd64 \
    woahbase/alpine-s6:latest \
    woahbase/alpine-s6:x86_64;

And finally, push it to the repository using


docker manifest push -p woahbase/alpine-s6:latest

Tag Version¶

Next, to facilitate pulling images by version, we create/amend the image-version manifest and annotate it to map the tags :aarch64_${version}, :armhf_${version}, :armv7l_${version}, :i386_${version}, :ppc64le_${version}, :riscv64_${version}, :s390x_${version}, :x86_64_${version} to the tag :${version} by running


make annotate_version

How it works

First we create or amend the manifest with the tag ${version}

createamend


docker manifest create \
woahbase/alpine-s6:${version} \
woahbase/alpine-s6:aarch64_${version} \
woahbase/alpine-s6:armhf_${version} \
woahbase/alpine-s6:armv7l_${version} \
woahbase/alpine-s6:i386_${version} \
woahbase/alpine-s6:ppc64le_${version} \
woahbase/alpine-s6:riscv64_${version} \
woahbase/alpine-s6:s390x_${version} \
woahbase/alpine-s6:x86_64_${version} \
;


docker manifest create --amend \
woahbase/alpine-s6:${version} \
woahbase/alpine-s6:aarch64_${version} \
woahbase/alpine-s6:armhf_${version} \
woahbase/alpine-s6:armv7l_${version} \
woahbase/alpine-s6:i386_${version} \
woahbase/alpine-s6:ppc64le_${version} \
woahbase/alpine-s6:riscv64_${version} \
woahbase/alpine-s6:s390x_${version} \
woahbase/alpine-s6:x86_64_${version} \
;

Then annotate the image for each architecture in the manifest with

aarch64armhfarmv7li386ppc64leriscv64s390xx86_64


docker manifest annotate --os linux --arch arm64 \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:aarch64_${version};


docker manifest annotate --os linux --arch arm --variant v6 \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:armhf_${version};


docker manifest annotate --os linux --arch arm --variant v7 \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:armv7l_${version};


docker manifest annotate --os linux --arch 386 \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:i386_${version};


docker manifest annotate --os linux --arch ppc64le \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:ppc64le_${version};


docker manifest annotate --os linux --arch riscv64 \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:riscv64_${version};


docker manifest annotate --os linux --arch s390x \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:s390x_${version};


docker manifest annotate --os linux --arch amd64 \
    woahbase/alpine-s6:${version} \
    woahbase/alpine-s6:x86_64_${version};

And finally, push it to the repository using


docker manifest push -p woahbase/alpine-s6:${version}

Tag Build-Date¶

Then, (optionally) we create/amend the ${version}_${builddate} manifest and annotate it to map the tags :aarch64_${version}_${builddate}, :armhf_${version}_${builddate}, :armv7l_${version}_${builddate}, :i386_${version}_${builddate}, :ppc64le_${version}_${builddate}, :riscv64_${version}_${builddate}, :s390x_${version}_${builddate}, :x86_64_${version}_${builddate} to the tag :${version}_${builddate} by running


make annotate_date

How it works

First we create or amend the manifest with the tag ${version}_${builddate}

createamend


docker manifest create \
woahbase/alpine-s6:${version}_${builddate} \
woahbase/alpine-s6:aarch64_${version}_${builddate} \
woahbase/alpine-s6:armhf_${version}_${builddate} \
woahbase/alpine-s6:armv7l_${version}_${builddate} \
woahbase/alpine-s6:i386_${version}_${builddate} \
woahbase/alpine-s6:ppc64le_${version}_${builddate} \
woahbase/alpine-s6:riscv64_${version}_${builddate} \
woahbase/alpine-s6:s390x_${version}_${builddate} \
woahbase/alpine-s6:x86_64_${version}_${builddate} \
;


docker manifest create --amend \
woahbase/alpine-s6:${version}_${builddate} \
woahbase/alpine-s6:aarch64_${version}_${builddate} \
woahbase/alpine-s6:armhf_${version}_${builddate} \
woahbase/alpine-s6:armv7l_${version}_${builddate} \
woahbase/alpine-s6:i386_${version}_${builddate} \
woahbase/alpine-s6:ppc64le_${version}_${builddate} \
woahbase/alpine-s6:riscv64_${version}_${builddate} \
woahbase/alpine-s6:s390x_${version}_${builddate} \
woahbase/alpine-s6:x86_64_${version}_${builddate} \
;

Then annotate the image for each architecture in the manifest with

aarch64armhfarmv7li386ppc64leriscv64s390xx86_64


docker manifest annotate --os linux --arch arm64 \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:aarch64_${version}_${builddate};


docker manifest annotate --os linux --arch arm --variant v6 \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:armhf_${version}_${builddate};


docker manifest annotate --os linux --arch arm --variant v7 \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:armv7l_${version}_${builddate};


docker manifest annotate --os linux --arch 386 \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:i386_${version}_${builddate};


docker manifest annotate --os linux --arch ppc64le \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:ppc64le_${version}_${builddate};


docker manifest annotate --os linux --arch riscv64 \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:riscv64_${version}_${builddate};


docker manifest annotate --os linux --arch s390x \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:s390x_${version}_${builddate};


docker manifest annotate --os linux --arch amd64 \
    woahbase/alpine-s6:${version}_${builddate} \
    woahbase/alpine-s6:x86_64_${version}_${builddate};

And finally, push it to the repository using


docker manifest push -p woahbase/alpine-s6:${version}_${builddate}

That's all folks! Happy containerizing!

Maintenance¶

Sources at Github. Built and tested at home using Buildbot. Images at Docker Hub.

Maintained (or sometimes a lack thereof?) by WOAHBase.

Helped you save a bit of your valuable time and effort that is best spent doing stuff you actually enjoy? If you have some pocket-change to spare, kindly consider helping out.