This Docker image is designed to be used as a base for containerized applications.

• MCStreetguy/Carrier – Just another Docker base image
  • Usage
    • Fix ownership and permissions
      • Examples
    • Execute initialization tasks
    • Creating service scripts
    • Execute finalization tasks
    • Environment variables
      • Services
      • Inside init or finish scripts
    • Dropping privileges
  • Overview
    • Init Stages
    • Customizing Behaviour
  • Reference
    • Binaries
      • /sbin/package
      • /bin/deeplog
      • /bin/mirrorlog
      • /bin/deeperr
      • /bin/mirrorerr
      • /bin/prefixlog
      • /bin/execdir
      • /bin/execenv
      • /usr/bin/containerip
      • /usr/bin/hostip
      • /usr/bin/awaits
    • Environment
      • HOSTIP
      • CONTAINERIP

Just specify the image tag inside your Dockerfile FROM directive:

FROM mcstreetguy/carrier:latest

You may choose from the following available tags, to restrict the underlying OS:

(* this version of alpine is no longer maintained, you should upgrade soon!)

As the image mainly relies on just-containers/s6-overlay, their usage instructions apply here too.

You may provide text files inside /etc/fix-attrs.d, containing instructions for setting file permissions. Each line has to contain the following information:

path recurse account fmode dmode

Whereas path specifies the absolute path to work on, recurse (either true or false) specifies if the path should be crawled recursively, account specifies the owner and optionally group for the found files and directories, fmode is a four-digit octal unix permission code set on files and dmode is a four-digit octal unix permission code set on directories.

(see also: https://github.com/just-containers/s6-overlay#fixing-ownership--permissions)

/etc/fix-attrs.d/01-mysql-data-dir:

/var/lib/mysql true mysql 0600 0700

/etc/fix-attrs.d/02-mysql-log-dirs:

/var/log/mysql-error-logs true nobody,32768:32768 0644 2700
/var/log/mysql-general-logs true nobody,32768:32768 0644 2700
/var/log/mysql-slow-query-logs true nobody,32768:32768 0644 2700

You may provide scripts inside /etc/cont-init.d, which will be executed after permissions have been fixed. These can contain initialization tasks and will be run each time the container starts.
If used for installation scripts that should only run once, make sure to check for the first run manually!
The scripts can be written in any language as long as you provide a shebang at the beginning. Commonly this would be either /bin/bash as interpreter or the /bin/execlineb interpreter for s6-execline scripting language.

(see also: https://github.com/just-containers/s6-overlay#executing-initialization-andor-finalization-tasks)

Creating supervised, long-lived services for your container is as easy as creating a directory with it's name inside /etc/services.d/ and create a run file in it.
That file is expected to be a script and execute the service in some way.
It may not terminate unless the service itself terminates, thus it has to run in foreground!
As before, this script has to provide a shebang with some interpreter for it's contents.

Services are automatically restarted by the s6 supervisor, unless you provide an optional finish script file in the service directory. If such a script is present, it will be executed as soon as the run script terminates and will bring the container down afterwards (i.e. makes the init system proceed to the shutdown stage). If you only want to prevent the restart of any service, it may contain only an exit 0 statement (which is valid in both bash and execline).

If you would like to know more about the possibilities of services beyond the shown common usage, consult the s6 servicedir documentation.

(see also: https://github.com/just-containers/s6-overlay#writing-a-service-script and https://github.com/just-containers/s6-overlay#writing-an-optional-finish-script)

In the same way as we provided intialization tasks before, we may provide such scripts inside /etc/cont-finish.d/ to create a finalization task, which is executed during early shutdown stage.

(see also: https://github.com/just-containers/s6-overlay#executing-initialization-andor-finalization-tasks)

To make your script have environment variables available, you need to modify your sheband a little bit. Normally, the entire environment is dropped upon execution to improve security when passing sensitive information through and .env file for example.

It is good practice to provide only the bare minimum of required environment variables to your services. To do so, you may provide the KEEP_ENV environment variable with a space-separated list of variable names to store for later service execution. This may be done using and ENV KEEP_ENV=... statement in your Dockerfile.

Then in your services run script, prepend the following binary to your shebang:

/bin/execenv

The resulting shebang should look like such:

#!/bin/execenv /bin/bash
# or
#!/bin/execenv /bin/execlineb -P

Now the service only has a reduced set of environment variables available. Namely some common system variables and the ones listed in KEEP_ENV.

If your service does not depend on the environment in any way, it is good practice to drop it explicitly.

bash:

#!/bin/bash
exec -c -- myservice

execline:

#!/bin/execlineb -P
/bin/exec -c --
myservice

Inside initialisation or finish tasks you normally want all your configuration to be available. To achieve this you may use the with-contenv helper script:

#!/usr/bin/with-contenv /bin/bash
# or
#!/usr/bin/with-contenv /bin/execlineb -P

When it comes to executing a service, a very good practice is to drop privileges before executing it. This is done easily with the provided helpers in both common scripting languages.

bash:

#!/bin/bash
exec s6-setuidgid daemon myservice

execline:

#!/usr/bin/execlineb -P
s6-setuidgid daemon
myservice

(see also https://github.com/just-containers/s6-overlay#dropping-privileges)

The image is based fully upon Alpine Linux to be as small and fast as possible.
If you are not familiar with Alpine you can find some guides to get you started in the official wiki.

See the respective section in the README of just-containers/s6-overlay for detailled information about the init stages.

You may set any of the following environmental variables on the container to customize some behaviour of the init system:

A wrapper script for the OS-specific package manager (apk under Alpine, apt under Ubuntu). Supports installation, removal, updates and prevention of packages.

USAGE: /sbin/package

Available commands: install Install a package remove Remove/Uninstall a package update Update all or specific packages prevent Prevent the installation, update or removal of a package allow Re-allow the installation, update or removal of a package

# Install a single package
/sbin/package install nano
# Install multiple packages at once
/sbin/package install pkg1 pkg2 pkg3
# Remove a single package
/sbin/package remove nano
# Remove multiple packages at once
/sbin/package remove pkg1 pkg2 pkg3
# Update all packages
/sbin/package update
# Update only one/some packages
/sbin/package update pkg1 pkg2
# Prevent the installation of a package (Ubuntu specific)
/sbin/package prevent spell
# Re-allow the installation of a package (Ubuntu specific)
/sbin/package allow spell

Send output directly to the attached Docker daemon's stdout file descriptor (e.g. the docker-compose container output).
The sent lines are not mirrored to the terminal! See mirrorlog if you need such behaviour. Arguments do not need to be quoted, but it is advised to do so either way.

/bin/deeplog "Hello World!"

You may also pipe output to it directly:

Bash:

some_command_with_output | /bin/deeplog

Execline:

/bin/pipeline { some_command_with_output } /bin/deeplog

Exactly the same as deeplog, except that it also outputs to the invoking shell.

Send output directly to the attached Docker daemon's stderr file descriptor (e.g. the docker-compose container output).
The sent lines are not mirrored to the terminal! See mirrorerr if you need such behaviour. Arguments do not need to be quoted, but it is advised to do so either way.

/bin/deeperr "Hello World!"

You may also pipe output to it directly:

Bash:

some_command_with_output | /bin/deeplog

Execline:

/bin/pipeline { some_command_with_output } /bin/deeplog

Exactly the same as deeperr, except that it also outputs to the invoking shell.

Apply a prefix to pipelined output.

Bash:

some_command_with_output | /bin/prefixlog "My Prefix:"

Execline:

/bin/pipeline { some_command_with_output } /bin/prefixlog "My Prefix:"

Execute each file in a given directory, then exit into another program.
If the given directory could not be found, the script exits with a non-zero code. If a file in the given directory is not executable, it is skipped silently.

/bin/execdir <script_directory> prog...

Execute another program with dropped environment variables. Only variables defined in the KEEP_ENV environment variable (excluding itself) will be loaded into the programs environment.

/bin/execenv prog...

Get the internal IP address of the container.

$ /usr/bin/containerip
172.21.0.1

Get the internal IP address of the host, running the Docker daemon.

$ /usr/bin/hostip
172.21.0.1

Wait for a given service to be reachable, then exit. This is actually the same functionality as described in 'Wait for external service connections' but provided solely to give you the ability of waiting for services whenever this suits your setup best, and not always at the very beginning of the startup process.

$ /usr/bin/awaits google.com 80 60 5
awaiting service at 'google.com:80'...
service not ready yet, retrying in 3 seconds...
# ...
connection to service at 'google.com:80' succeeded.

In the early init stage some default environment variables are written to the system. Find the available variables and respective value explanations below.

Contains the internal IP address of the host, running the docker daemon. This yields the same result as executing /usr/bin/hostip.

Contains the internal IP address of the current container. This yields the same result as executing /usr/bin/containerip.