DOCSEARCHbyAlgolia
Submit Docs

s6-overlay

repository·master·Indexed 26 days ago

https://github.com/just-containers/s6-overlay

A set of scripts and utilities for using s6 as a PID 1 and process supervisor within Docker containers. It enables running multiple processes, managing service dependencies, and handling orderly shutdowns. The project provides architecture-specific and noarch tarballs to implement initialization stages, legacy supervised services in /etc/services.d, and modern s6-rc services in /etc/s6-overlay/s6-rc.d.

Tokens
7.6K
Snippets
13
Records
40
Agent score
87%

What's inside s6-overlay

  1. Understand s6-overlay Init Stages

    master

    s6-overlay operates through three distinct stages during the container lifecycle:

    1. Stage 1 (Setup): Configures the image to execute the supervision tree and prepares the environment for Stage 2.
    2. Stage 2 (Initialization & Service Start):
      • Executes legacy oneshot user scripts in /etc/cont-init.d.
      • Runs user s6-rc services defined in the /etc/s6-overlay/user-bundles.d/user bundle (services are declared in /etc/s6-overlay/s6-rc.d).
      • Starts legacy longrun services from /etc/services.d.
      • Runs user s6-rc services defined in the /etc/s6-overlay/user-bundles.d/user2 bundle.
    3. Stage 3 (Shutdown):
      • Sends TERM signals to legacy longrun services and waits for exit.
      • Brings down s6-rc services in an orderly fashion.
      • Executes finalization scripts in /etc/cont-finish.d.
      • Sends TERM signals to remaining processes, waits, and finally sends KILL signals before exiting.

  2. Quickstart: Install s6-overlay in a Dockerfile

    master

    To use s6-overlay, you need to extract the appropriate tarballs into your image and set /init as the ENTRYPOINT. The overlay is distributed as architecture-specific tarballs (e.g., x86_64) and a noarch tarball for generic scripts.

    Note: Ensure you have xz-utils installed in your base image to extract the .tar.xz files.

    # Use your favorite image
FROM ubuntu
ARG S6_OVERLAY_VERSION=3.2.3.2

RUN apt-get update && apt-get install -y nginx xz-utils
RUN echo "daemon off;" >> /etc/nginx/nginx.conf
CMD ["/usr/sbin/nginx"]

ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-x86_64.tar.xz
ENTRYPOINT ["/init"]

  3. Emulate syslog using syslogd-overlay-noarch

    master

    If your containerized software requires syslog, you can add a small syslogd emulation by extracting the syslogd-overlay-noarch.tar.xz tarball.

    Logs are stored in subdirectories of /var/log/syslogd to allow for automatic rotation without race conditions. For example, the messages log is located at /var/log/syslogd/messages/, with the most recent entries available in the /var/log/syslogd/messages/current file.

  4. Migrating from s6-overlay v2 to v3

    master
    If you are upgrading from v2 to v3, you must review the breaking changes and architectural differences. Significant changes exist in how services are managed and how the init sequence operates. Refer to the dedicated migration guide for specific implementation details.

  5. Install s6-overlay in a Dockerfile

    master

    s6-overlay is distributed as a set of tarballs that must be extracted onto your image. Most users require both the noarch tarball (containing scripts) and the architecture-specific tarball (containing binaries).

    When extracting, you must preserve file permissions by using the -p flag with tar.

    ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-x86_64.tar.xz

  6. Create an s6-rc supervised service

    master

    The modern way to define services is using s6-rc source definition directories in /etc/s6-overlay/s6-rc.d. This allows you to define dependencies between services (e.g., starting A before B).

    To implement a service:

    1. Create a directory in /etc/s6-overlay/s6-rc.d/myapp/.
    2. Create a type file (e.g., longrun or oneshot).
    3. Create a run file containing the execution command.
    4. Add the service to the user bundle by creating an empty file with the same name in /etc/s6-overlay/user-bundles.d/user/contents.d/.
    5. (Optional) Add dependencies by creating an empty file in /etc/s6-overlay/s6-rc.d/myapp/dependencies.d/<dependency_name>.

  7. Set the container exit code for supervised services

    master

    When running a main service as a supervised service, the container won't automatically exit with the service's exit code upon docker stop. To fix this, you must write a finish script for your service.

    Location:

    • Legacy: /etc/services.d/myapp/finish
    • s6-rc: /etc/s6-overlay/s6-rc.d/myapp/finish

    The script receives two arguments:

    1. $1: The exit code of the service (or 256 if killed by an uncaught signal).
    2. $2: The signal number (only if killed by an uncaught signal).

    You must write the desired container exit code to /run/s6-linux-init-container-results/exitcode.

    #!/bin/sh

if test "$1" -eq 256 ; then
  e=$((128 + $2))
else
  e="$1"
fi

echo "$e" > /run/s6-linux-init-container-results/exitcode

  8. Write a finish script to stop the container on service exit

    master

    By default, services in /etc/services.d automatically restart. If you want a service to bring the container down when it exits, you must write a finish script. To stop the container, invoke /run/s6/basedir/bin/halt.

    To pass a specific exit code to the docker run command that launched the container, write the code to /run/s6-linux-init-container-results/exitcode before calling halt.

    ### Example: Always exit with 0
`/etc/services.d/myapp/finish`:
```execline
#!/command/execlineb -S0

foreground { redirfd -w 1 /run/s6-linux-init-container-results/exitcode echo 0 }
/run/s6/basedir/bin/halt

    Example: Exit only if service exits with non-zero status

    /etc/services.d/myapp/finish:

    #!/command/execlineb -S1
if { eltest ${1} -ne 0 -a ${1} -ne 256 }
/run/s6/basedir/bin/halt

  10. Use s6-rc source definitions for services

    master

    While the legacy /etc/cont-init.d, /etc/services.d, and /etc/cont-finish.d methods are still supported, it is recommended to use s6-rc source definitions for better control over service types (oneshot vs longrun) and dependencies.

    Longrun Services

    A longrun service directory should include a run script and optionally a finish script.

    Oneshot Services

    1. Create a type file in the service directory specifying it is a oneshot.
    2. Create an up file. Note: The up file is not a shell script and does not honor shebangs. Instead, place your logic in a separate executable file (e.g., /etc/s6-overlay/scripts/foobar) and have the up file simply contain the path to that executable.

    Registering Services

    To ensure a service starts at container boot, add it to the user bundle by creating a file in /etc/s6-overlay/s6-rc.d/user/contents.d/<service_name>.

    To define dependencies (e.g., making a service depend on base), create the directory /etc/s6-overlay/s6-rc.d/<service_name>/dependencies.d/ and add a file named base inside it.

  11. Install and use s6-overlay via Dockerfile

    master

    To use s6-overlay, extract the provided .tar.xz archives at the root of your image and set your ENTRYPOINT to /init. It is recommended to use Docker's ADD directive to handle the HTTPS URLs for the archives, as this avoids the need for wget or curl in the base image.

    Note: You may need to install xz-utils (e.g., apt install xz-utils or apk add xz) in your base image to allow tar to extract .tar.xz files.

    FROM busybox
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
RUN tar -C / -Jxpf /tmp/s6-overlay-x86_64.tar.xz
ENTRYPOINT ["/init"]

  12. Verify s6-overlay download integrity

    master

    To ensure the integrity of your s6-overlay downloads, use the provided SHA256 checksum files. You can verify the noarch scripts and the architecture-specific binaries using sha256sum -c.

    ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz /tmp
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-noarch.tar.xz.sha256 /tmp
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz /tmp
ADD https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}/s6-overlay-x86_64.tar.xz.sha256 /tmp
RUN cd /tmp && sha256sum -c *.sha256