chainguard-dev / apko

Services and s6 Supervision

This section outlines apko’s support for running multiple processes in a container using the s6 supervision suite. This feature is useful for building containers with complex applications that need to manage multiple processes or services. The s6 supervision suite is a lightweight, powerful tool that can be used to manage processes and services in a container.

Using s6 Supervision

apko provides a way to configure and manage services using s6 supervision via the --services flag. This flag takes a comma-separated list of services to be run. Each service is defined by a name and command, and each service can have several optional attributes:

  • name: The name of the service (required).
  • command: The command to run for the service (required).
  • user: The user to run the service as (optional).
  • group: The group to run the service as (optional).
  • working-dir: The working directory for the service (optional).
  • environment: A list of environment variables to set for the service (optional).
  • pid-file: The path to the PID file for the service (optional).
  • log-file: The path to the log file for the service (optional).
  • restart: Whether the service should be restarted if it crashes (optional, defaults to on-failure).
  • restart-interval: The interval between restart attempts (optional, defaults to 10 seconds).
  • restart-retries: The number of restart attempts before giving up (optional, defaults to 10).
  • stop-signal: The signal to use to stop the service (optional, defaults to SIGTERM).
  • stop-timeout: The timeout in seconds to wait for the service to stop (optional, defaults to 10 seconds).

For example:

apko build --services "service1:command=/bin/bash -c 'sleep 10', service2:command=/usr/bin/nginx -g 'daemon off;'" my-image

This command would build a container with two services: service1 and service2. The service1 service would run the command /bin/bash -c 'sleep 10' and the service2 service would run the command /usr/bin/nginx -g 'daemon off;'.

Service Configuration

The s6 supervision suite is responsible for managing and monitoring the lifecycle of the services within the container. The services are defined in a configuration file within the container at /etc/s6/services. This directory contains individual subdirectories, one for each service, with a run file in each service’s subdirectory. The contents of the run file defines the command to be executed.

s6 Configuration Files

The following directories and files are generated during container build and contain the configuration information for services defined via the --services option:

  • /etc/s6/services: This directory holds the configuration for each service, including the main configuration file.
  • /etc/s6/services/<service-name>: This directory contains the configuration for a particular service, including the run file.
  • /etc/s6/services/<service-name>/run: This file contains the command to be executed for the service.

Here is an example of a configuration file for service1 defined in the command above:

/etc/s6/services/service1/run
          
#!/bin/bash
          exec /bin/bash -c 'sleep 10'

Additional Features

The s6 supervision suite provides several additional features:

  • Logging: s6 can log service output to files.
  • Restarting: s6 can automatically restart services that crash.
  • Stopping: s6 can gracefully stop services.

Examples

Here are some additional examples of how to use the --services option:

  • Running multiple services with different configurations:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', service2:command=/usr/bin/nginx -g 'daemon off;', service3:command=/usr/bin/redis-server, service4:command=/usr/bin/mysql -u root -p" my-image

  • Running a service with a specific user and group:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', user=nginx, group=nginx" my-image

  • Running a service with a specific working directory:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', working-dir=/var/www/html" my-image

  • Running a service with specific environment variables:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', environment=MY_VAR=value, ANOTHER_VAR=another_value" my-image

  • Running a service with a specific PID file:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', pid-file=/var/run/service1.pid" my-image

  • Running a service with a specific log file:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', log-file=/var/log/service1.log" my-image

  • Running a service with a specific restart policy:

    apko build --services "service1:command=/bin/bash -c 'sleep 10', restart=always" my-image

References