baseimagedefs.yml

---

#
# Definitions for docker-baseimage.
#
# This file is used as data source to generate README.md and unRAID template
# files from Jinja2 templates.
#

baseimage:
  name: baseimage
  title: >-
    A minimal docker baseimage to ease creation of long-lived application
    containers
  description: |-
    This is a docker baseimage that can be used to create containers for any
    long-lived application.
  gui: false
  history:
    - version: 3.6.5
      date: 2025-02-01
      changes:
        changed:
          - 'Increased the default service ready timeout from 5 seconds to 10 seconds and allow runtime adjustment via environment variable.'
    - version: 3.6.4
      date: 2024-12-06
      changes:
        added:
          - 'Image based on Alpine 3.21.'
        changed:
          - 'Rebuild against latest distro images to get security fixes.'
    - version: 3.6.3
      date: 2024-08-07
      changes:
        added:
          - 'Image based on Debian 12.'
          - 'Image based on Ubuntu 24.04.'
        changed:
          - 'Rebuild against latest distro images to get security fixes.'
    - version: 3.6.2
      date: 2024-07-28
      changes:
        fixed:
          - 'Some logged messages related to environment variable loading were not properly prefixed.'
    - version: 3.6.1
      date: 2024-07-26
      changes:
        fixed:
          - 'Return code of environment variable loading script was not handled properly.'
    - version: 3.6.0
      date: 2024-07-22
      changes:
        added:
          - 'The amount of time allowed to services to gracefully terminate is configurable via the `SERVICES_GRACETIME` environment variable.'
          - 'Variables can be added to environment of a service via the `environment_extra` parameter.'
          - 'Image based on Alpine Linux 3.20.'
        removed:
          - 'Helper script to install glibc on Alpine Linux based images.'
          - 'Image based on Alpine 3.14 (reached end of support on 2023-05-01).'
          - 'Image based on Alpine 3.15 (reached end of support on 2023-11-01).'
        fixed:
          - 'During package mirror setup, make sure to keep permissions of copied files.'
    - version: 3.5.3
      date: 2023-12-20
      changes:
        added:
          - 'Image based on Alpine Linux 3.19.'
        changed:
          - 'Rebuild against latest distro images to get security fixes.'
    - version: 3.5.2
      date: 2023-11-17
      changes:
        fixed:
          - 'When using a very high user or group ID, the helper that takes ownership of a directory would fail.'
    - version: 3.5.1
      date: 2023-11-10
      changes:
        fixed:
          - 'Packages installation at runtime could fail on Ubuntu/Debian due to missing user/group.'
    - version: 3.5.0
      date: 2023-11-08
      changes:
        added:
          - 'Mirror for packages installation can be set via the `PACKAGES_MIRROR` environment variable.'
        changed:
          - 'Improved the way the `take-ownership` script is working.'
        fixed:
          - 'Readiness and minimum running time checks should not be done for a service defined with an interval.'
          - 'Raise an error when a synched service fails to start.'
          - 'Minimum running time check of a service was using an incorrect way to verify if process is still alive.'
    - version: 3.4.7
      date: 2023-05-16
      changes:
        added:
          - 'Image based on Alpine Linux 3.18.'
          - 'Image based on Ubuntu 22.04.'
        changed:
          - 'Rebuild against latest distro images to get security fixes.'
        removed:
          - 'Image based on Alpine 3.13 (reached end of support on 2022-11-01).'
          - 'Image based on Debian 9 (reached end of life on 2022-07-01).'
    - version: 3.4.6
      date: 2023-03-03
      changes:
        fixed:
          - 'Issue during initialization of Linux users and groups when the `GROUP_ID` is also part of `SUP_GROUP_IDS`.'
    - version: 3.4.5
      date: 2023-02-13
      changes:
        fixed:
          - 'Limit the maximum number of opened files on system having a very large, unlimited value. This prevents unnecessary waste of CPU resources and time for applications trying to close all possible file descriptors.'
    - version: 3.4.4
      date: 2023-02-09
      changes:
        fixed:
          - 'Issue handling internal supplementary group IDs by the default `sgid` service file.'
    - version: 3.4.3
      date: 2023-01-30
      changes:
        fixed:
          - 'Helper that takes ownership of a directory not handling correctly names with end-of-line character.'
          - 'The logrotate status file permissions was not set automatically during startup.'
          - 'Strings `y` and `n` were not considered as valid boolean values.'
    - version: 3.4.2
      date: 2023-01-06
      changes:
        changed:
          - 'Recursivity can be disabled when using the helper taking ownership of a directory.'
          - 'Supplementary group IDs can also be provided by the container itself via `SUP_GROUP_IDS_INTERNAL` environment variable.'
        fixed:
          - 'Validation of supplementary group IDs.'
    - version: 3.4.1
      date: 2023-01-03
      changes:
        fixed:
          - 'Prevent the logmonitor to be blocked by a notification backend by running it asynchronously.'
    - version: 3.4.0
      date: 2023-01-01
      changes:
        added:
          - 'Service for logrotate.'
        changed:
          - 'Declaration of files to be monitored by the logmonitor has been moved to the notification''s definitions.'
        fixed:
          - 'Conversion of a service''s interval non-numeric value.'
    - version: 3.3.3
      date: 2022-12-10
      changes:
        fixed:
          - 'Force the value of the `PATH` environment variable. Any value configured during creation of the container should not affect operation of the container.'
    - version: 3.3.2
      date: 2022-12-01
      changes:
        fixed:
          - 'Helper that takes ownership of a directory was not compatible with all shells.'
    - version: 3.3.1
      date: 2022-12-01
      changes:
        fixed:
          - 'Helper that takes ownership of a directory not handling correctly names with spaces.'
          - 'Handling of a service''s `workdir` ending with an end-of-line character.'
    - version: 3.3.0
      date: 2022-11-26
      changes:
        added:
          - 'Init script to set permissions on `/tmp`.'
        removed:
          - 'Baseimage based on Debian 8 (reached its end of life on June 30 2020).'
    - version: 3.2.0
      date: 2022-11-24
      changes:
        added:
          - 'Image based on Alpine 3.17.'
          - 'Helper to take ownership of a directory.'
          - 'Helper to determine if a boolean value is true or false.'
          - 'Internal environment variables are automatically loaded when logging in to the container.'
        changed:
          - 'Baseimage''s binaries have been relocated to `/opt/base/bin`.'
          - 'Adjusted `PATH` environment variable to include `/opt/base/bin`.'
    - version: 3.1.6
      date: 2022-11-07
      changes:
        fixed:
          - 'logmonitor: do not re-process status files that didn''t change.'
          - 'logmonitor: fixed handling of debouncing value `0` (infinite).'
    - version: 3.1.5
      date: 2022-11-03
      changes:
        fixed:
          - 'Crash that occurs when no monotonic clock is available.'
    - version: 3.1.4
      date: 2022-11-01
      changes:
        fixed:
          - 'Re-added `LANG` Docker environment variable that was present in previous versions.'
    - version: 3.1.3
      date: 2022-10-28
      changes:
        fixed:
          - 'Truncation of long application name in informational box.'
    - version: 3.1.2
      date: 2022-10-21
      changes:
        fixed:
          - 'A umask value of `0000` was not properly applied.'
    - version: 3.1.1
      date: 2022-10-21
      changes:
        changed:
          - 'Include the Docker image platform in the informational box printed during container startup.'
        fixed:
          - 'Logmonitor crash on arm64 platform.'
    - version: 3.1.0
      date: 2022-10-16
      changes:
        added:
          - 'The `INSTALL_PACKAGES_INTERNAL` internal environment variable.'
        fixed:
          - 'Value of the `UMASK` environment variable defined in the Dockerfile.'
    - version: 3.0.3
      date: 2022-10-10
      changes:
        fixed:
          - 'Issue where taking ownership of `/config` containing no file would fail.'
    - version: 3.0.2
      date: 2022-10-10
      changes:
        fixed:
          - 'Issue taking ownership of `/config` when one of its subfolder is mapped to a network share.'
          - 'Make sure to always set supplementary groups of services, even if the list is empty.'
    - version: 3.0.1
      date: 2022-10-07
      changes:
        fixed:
          - 'Defined parameters for the `app` service were not passed to `startapp.sh`.'
    - version: 3.0.0
      date: 2022-10-05
      changes:
        added:
          - 'Multi-arch support of baseimages.'
          - 'Baseimage based on Alpine Linux 3.16.'
        changed:
          - 'Size of Docker images has been reduced.'
          - 'S6 overlay has been replaced with a simpler init system and process supervisor.'
          - 'Simplified and improved the container startup and shutdown sequences.'
          - 'Definition of services are more flexible and powerful.'
          - 'Definition of environment variables are more flexible and powerful.'
          - 'Environment variables are automatically passed to init scripts and services.'
          - 'Environment variables can be public or internal ones.'
          - 'Improved management of service dependencies.'
          - 'The log monitor has been rewritten in C.'
          - 'Improved logging to container''s log.'
          - 'Multiple miscellaneous improvements.'
          - 'Make sure to read the documentation to understand how to adjust applications built with version 2.x of the baseimage.'
        removed:
          - 'Baseimages based on Alpine Linux 3.10, 3.11 and 3.12.'
          - 'Glibc version of Alpine Linux Docker images. Glibc can instead be installed manually with the provided install script.'
          - 'The `with-contenv` script: its usage is no longer needed.'
    - version: 2.4.6
      date: 2021-12-29
      changes:
        - 'Updated installed packages to get latest security fixes.'
        - 'Added images based on Alpine 3.13, 3.14 and 3.15.'
        - 'Added images based on Debian 11.'
        - 'Added images based on Ubuntu 20.04.'
        - 'Removed support for images based on Alpine 3.5, 3.6, 3.7, 3.8 and 3.8.'
    - version: 2.4.5
      date: 2021-04-01
      changes:
        - 'Updated installed packages to get latest security fixes.'
    - version: 2.4.4
      date: 2020-06-25
      changes:
        - 'Upgraded glibc to version 2.31 on Alpine Linux images with glibc integrated.'
        - 'Updated installed packages to get latest security fixes.'
    - version: 2.4.3
      date: 2019-10-04
      changes:
        - 'Updated installed packages to get latest security fixes.'
        - 'Make sure the tzdata is installed.'
    - version: 2.4.2
      date: 2019-04-24
      changes:
        - 'Updated installed packages to get latest security fixes.'
    - version: 2.4.1
      date: 2018-09-18
      changes:
        - 'Updated installed packages to get latest security fixes.'
    - version: 2.4.0
      date: 2018-08-13
      changes:
        - 'Added baseimage based on Ubuntu 18.04.'
    - version: 2.3.0
      date: 2018-07-06
      changes:
        - 'Added images based on Alpine Linux 3.8.'
        - 'Added images based on Debian 9.'
    - version: 2.2.8
      date: 2018-04-12
      changes:
        - 'Fixed architecture of ubuntu baseimage: it is meant to be 64-bit.'
    - version: 2.2.7
      date: 2018-04-03
      changes:
        - 'Upgraded s6-overlay to version 1.21.4.0.'
        - 'Wait for a limited time when terminating a service.'
        - 'Set and create the XDG_RUNTIME_DIR directory.'
    - version: 2.2.6
      date: 2018-03-02
      changes:
        - 'Fixed issue where log monitor states were not cleared during container startup.'
    - version: 2.2.5
      date: 2018-02-02
      changes:
        - 'Restored timezone support in Alpine Linux images with glibc.'
        - 'Fixed issue in `add-pkg` helper where a package could be incorrectly detected as installed.'
    - version: 2.2.4
      date: 2018-01-22
      changes:
        - 'Fixed the `LANG` environment variable not being set properly.'
    - version: 2.2.3
      date: 2018-01-12
      changes:
        - 'For Alpine Linux images with glibc, automatically update dynamic linker''s cache after new libraries are installed.'
    - version: 2.2.2
      date: 2018-01-10
      changes:
        - 'Adjusted the way ownership of /config is taken to better support cases where the folder is mapped to a network share.'
    - version: 2.2.1
      date: 2018-01-04
      changes:
        - 'Upgraded S6 overlay to version 1.21.2.2.'
        - 'Upgraded glibc to version 2.26 (Alpine Linux glibc images).'
    - version: 2.2.0
      date: 2017-12-06
      changes:
        - 'Added images based on Alpine Linux 3.7.'
    - version: 2.1.4
      date: 2017-11-19
      changes:
        - 'Upgraded S6 overlay to version 1.21.2.1.'
    - version: 2.1.3
      date: 2017-11-06
      changes:
        - 'Upgraded S6 overlay to version 1.21.2.0.'
        - 'Use a more efficient way to monitor status files.'
    - version: 2.1.2
      date: 2017-10-31
      changes:
        - 'Fixed an issue where a self-disabled service could be restarted.'
    - version: 2.1.1
      date: 2017-10-28
      changes:
        - 'Fixed race condition where container''s exit code would not be the expected one.'
    - version: 2.1.0
      date: 2017-10-27
      changes:
        - 'Upgraded S6 overlay to version 1.21.1.1.'
        - 'Enhanced integration of service dependencies functionality.'
        - 'Added a simple log monitor.'
    - version: 2.0.0
      date: 2017-10-04
      changes:
        - 'Added better support for service dependencies.'
        - '2:Services startup order is automatically determined.'
        - '2:Services are stopped in reverse order.'
        - '2:The application''s service is always started last.'
        - '2:The following elements are no longer needed and have been removed:'
        - '3:`s6-svrunning` and `s6-waitdeps` programs.'
        - '3:Pre-stage3 with pre-finish scripts support.'
        - '2:Note that these changes can break building and/or execution of containers based on v1.x of this baseimage.'
    - version: 1.1.6
      date: 2017-09-19
      changes:
        - 'Restore default `/etc/shadow` during container startup.'
    - version: 1.1.5
      date: 2017-09-08
      changes:
        - 'Fixed duplicated entries in /etc/passwd and /etc/group that were created after a restart of the container.'
    - version: 1.1.4
      date: 2017-09-06
      changes:
        - 'Fixed timezone support on alpine-glibc images.'
    - version: 1.1.3
      date: 2017-08-12
      changes:
        - 'Upgraded S6 overlay to version 1.20.0.0.'
    - version: 1.1.2
      date: 2017-07-31
      changes:
        - 'Clear the environment of the container during startup.'
        - 'Clear the `/tmp` folder during startup.'
    - version: 1.1.1
      date: 2017-07-28
      changes:
        - 'Make sure to remove the container shutdown indication during startup. This fixes the behavior of `KEEP_APP_RUNNING` variable after a restart of the container.'
    - version: 1.1.0
      date: 2017-07-17
      changes:
        - 'The following environment variables from the *XDG Base Directory Specification* are now set. Applications following this specification will have their configuration and data stored under `/config`.'
        - '2:XDG_DATA_HOME=/config/xdg/data'
        - '2:XDG_CONFIG_HOME=/config/xdg/config'
        - '2:XDG_CACHE_HOME=/config/xdg/cache'
    - version: 1.0.0
      date: 2017-07-14
      changes:
        - 'Initial release. This baseimage can be used to build containers running long-lived applications that don''t require an X environment. It is the result of the split of the baseimage `jlesage/baseimage-gui`, from which all non-GUI related stuff has been moved into this new baseimage.'

container:

  # Environment variables.
  environment_variables:
    - name: APP_NAME
      description: Name of the implemented application.
      type: internal
      default: DockerApp
    - name: APP_VERSION
      description: Version of the implemented application.
      type: internal
      default:
    - name: DOCKER_IMAGE_VERSION
      description: Version of the Docker image that implements the application.
      type: internal
      default:
    - name: DOCKER_IMAGE_PLATFORM
      description: Platform (OS / CPU architecture) of the Docker image that implements the application.
      type: internal
      default:
    - name: HOME
      description: Home directory.
      type: internal
    - name: XDG_CONFIG_HOME
      description: >-
        Defines the base directory relative to which user specific configuration
        files should be stored.
      type: internal
      default: /config/xdg/config
    - name: XDG_DATA_HOME
      description: >-
        Defines the base directory relative to which user specific data files
        should be stored.
      type: internal
      default: /config/xdg/data
    - name: XDG_CACHE_HOME
      description: >-
        Defines the base directory relative to which user specific non-essential
        data files should be stored.
      type: internal
      default: /config/xdg/cache
    - name: TAKE_CONFIG_OWNERSHIP
      description: >-
        When set to `0`, ownership of the content of the `/config` directory is
        not taken during startup of the container.
      type: internal
      default: 1
    - name: INSTALL_PACKAGES_INTERNAL
      description: >-
        Space-separated list of packages to install during the startup of the
        container. Packages are installed from the repository of the Linux
        distribution this container is based on.
      type: internal
    - name: SUP_GROUP_IDS_INTERNAL
      description: >-
        Comma-separated list of supplementary group IDs of the application.
        These are merged with the ones that might be supplied by
        `SUP_GROUP_IDS`.
      type: internal
    - name: SERVICES_GRACETIME
      description: >-
        During container shutdown, this defines the amount of time (in
        milliseconds) allowed to services to gracefully terminate before
        sending the KILL signal to everyone.
      type: internal
      default: 5000
    - name: USER_ID
      description: >-
        ID of the user the application runs as. See
        [User/Group IDs](#usergroup-ids) to better understand when this should
        be set.
      type: public
      default: 1000
      unraid_template:
        title: User ID
        description: ID of the user the application runs as.
        default: 99
        display: advanced-hide
        required: true
        mask: false
    - name: GROUP_ID
      description: >-
        ID of the group the application runs as. See
        [User/Group IDs](#usergroup-ids) to better understand when this should
        be set.
      type: public
      default: 1000
      unraid_template:
        title: Group ID
        description: ID of the group the application runs as.
        default: 100
        display: advanced-hide
        required: true
        mask: false
    - name: SUP_GROUP_IDS
      description: >-
        Comma-separated list of supplementary group IDs of the application.
      type: public
    - name: UMASK
      description: >-
        Mask that controls how permissions are set for newly created files and
        folders. The value of the mask is in octal notation. By default, the
        default umask value is `0022`, meaning that newly created files and
        folders are readable by everyone, but only writable by the owner. See
        the online umask calculator at http://wintelguy.com/umask-calc.pl.
      type: public
      default: "0022"
      unraid_template:
        title: Umask
        description: >-
          Mask that controls how file permissions are set for newly created
          files. The value of the mask is in octal notation.
        default: "0000"
        display: advanced
        required: false
        mask: false
    - name: LANG
      description: >-
        Set the [locale](https://en.wikipedia.org/wiki/Locale_(computer_software)),
        which defines the application's language, **if supported**. Format of
        the locale is `language[_territory][.codeset]`, where language is an
        [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes),
        territory is an [ISO 3166 country code](https://en.wikipedia.org/wiki/ISO_3166-1#Current_codes)
        and codeset is a character set, like `UTF-8`. For example, Australian
        English using the UTF-8 encoding is `en_AU.UTF-8`.
      type: public
      default: en_US.UTF-8
    - name: TZ
      description: >-
        [TimeZone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
        used by the container. Timezone can also be set by mapping
        `/etc/localtime` between the host and the container.
      type: public
      default: Etc/UTC
    - name: KEEP_APP_RUNNING
      description: >-
        When set to `1`, the application will be automatically restarted when it
        crashes or terminates.
      type: public
      default: 0
    - name: APP_NICENESS
      description: >-
        Priority at which the application should run. A niceness value of -20
        is the highest priority and 19 is the lowest priority. The default
        niceness value is 0. **NOTE**: A negative niceness (priority increase)
        requires additional permissions. In this case, the container should be
        run with the docker option `--cap-add=SYS_NICE`.
      type: public
      default: 0
      unraid_template:
        title: Niceness (priority)
        description: >-
          Priority at which the application should run. A niceness value of -20
          is the highest priority and 19 is the lowest priority.
          NOTE: Setting a negative value requires additional permissions. Thus,
          "--cap-add=SYS_NICE" must be added to Extra Parameters (shown when
          Advanced View is enabled).
        display: advanced
        required: false
        mask: false
    - name: INSTALL_PACKAGES
      description: >-
        Space-separated list of packages to install during the startup of the
        container.
        {%- if app is not defined %} Packages are installed from the repository of the
        Linux distribution this container is based on.
        {%- else %} List of available packages can be found at {% if app.base_os == 'alpine' %}https://pkgs.alpinelinux.org{% elif app.base_os == 'debian' %}https://www.debian.org/distrib/packages{% elif app.base_os == 'ubuntu' %}https://packages.ubuntu.com{% endif %}.
        {%- endif %} **ATTENTION**: Container functionality can be affected when
        installing a package that overrides existing container files (e.g. binaries).
      type: public
    - name: PACKAGES_MIRROR
      description: >-
        Mirror of the repository to use when installing packages.
        {%- if app is defined %}
        List of mirrors is available at {% if app.base_os == 'alpine' %}https://mirrors.alpinelinux.org{% elif app.base_os == 'debian' %}https://www.debian.org/mirror/list{% elif app.base_os == 'ubuntu' %}https://launchpad.net/ubuntu/+archivemirrors{% endif %}.
        {%- endif %}
      type: public
    - name: CONTAINER_DEBUG
      description: >-
        Set to `1` to enable debug logging.
      type: public
      default: 0

  # Volumes
  volumes:
    - container_path: /config
      host_path_example: /docker/appdata/{{ app.name }}
      description: >-
        This is where the application stores its configuration, states, log and
        any files needing persistency.
      permissions: rw
      include_in_quick_start: true
      unraid_template:
        title: Config Directory
        description: >-
          This is where the application stores its configuration, states, log
          and any files needing persistency.
        default: /mnt/user/appdata/{{ app.name }}
        display: advanced-hide
        required: true
        mask: false
    - container_path: /storage
      host_path_example: /home/user
      description: >-
        This location contains files from your host that need to be accessible
        to the application.
      permissions: "{{ container.storage_permissions }}"
      include_in_quick_start: true
      unraid_template:
        title: Storage
        description: >-
          This location contains files from your host that need to be accessible
          to the application.
        default: /mnt/user
        display: always-hide
        required: true
        mask: false

  # Network ports
  ports: []

  # Devices
  devices: []