Configuration#

This page is for anyone writing or editing deployment configuration. It documents every field of the files you author and how they nest. The field tables are curated by hand from the Pydantic models in src/deploy_tools/models, so a change to those models needs a change here too; the schema reference renders the same fields mechanically from the generated JSON schemas. For the meaning of individual terms, see the glossary.

What you author#

You author two kinds of file: a single settings.yaml, and one Release file, <name>/<version>.yaml, per Module version. The schema reference covers which schema validates which and how to point your editor at them.

They are structured as follows:

settings.yaml
  └── default_versions

<name>/<version>.yaml               one Release file per Module version
  ├── deprecated: false             lifecycle flag
  └── module
      ├── name                      Module name
      ├── version                   Module version
      ├── description               shown by `module whatis`
      ├── env_vars                  variables set on load
      ├── dependencies              other Modules to load first
      └── applications              one or more, each with an app_type of:
          ├── apptainer             container image + entrypoints
          ├── shell                 a bash script
          └── binary                a downloaded, hash-checked executable

Those last three are the values app_type can take rather than fields of their own — see the three application types below.

A Release file#

Each Release file has two fields:

Field	Purpose
`module`	The Module being released (below).
`deprecated`	Whether this version is deprecated. Defaults to `false` — see the release lifecycle.

A Module#

A Module is the unit an end user loads. It carries:

Field	Purpose
`name`	The name an end user loads it by.
`version`	The version an end user loads it by.
`description`	Shown by `module whatis <name>`.
`env_vars`	Environment variables set when the Module is loaded.
`dependencies`	Other Modules loaded first, optionally version-pinned.
`applications`	One or more applications providing the executables (below).
`load_script`	Extra commands run when the Module is loaded — see below.
`unload_script`	Extra commands run when the Module is unloaded — see below.
`allow_updates`	Permit in-place changes to this version — see the guard rails.
`exclude_from_defaults`	Keep this version out of automatic default selection — see default versions.

env_vars — each entry is a name/value pair:

Field	Purpose
`name`	The variable to set.
`value`	The value to set it to.

dependencies — each entry names another Module:

Field	Purpose
`name`	The Module to load first.
`version`	The version to pin to. If omitted, that Module’s default version is resolved at load time.

load_script and unload_script are injected raw into the generated Modulefile. They are for advanced cases the other fields cannot cover — check with a deploy-tools admin before using them.

The three application types#

Every entry under applications sets app_type to select one of three kinds; a single Module can mix them.

`app_type`	Provides
`apptainer`	Commands that run inside a container image
`shell`	A single executable running a bash script
`binary`	A downloaded executable added to the path

The demo example-module-apps Module combines an Apptainer app with a Shell app:

module:
  name: example-module-apps
  version: "0.1"
  description: Demonstration of a module configuration folder

  env_vars:
    - name: OTHER_VALUE
      value: Test message OTHER_VALUE from example-module-folder

  applications:
    - app_type: apptainer

      container:
        path: docker://ghcr.io/apptainer/lolcow
        version: latest

      entrypoints:
        - name: cowsay-hello
          command: cowsay
          options:
            command_args: Hello

        - name: show-directory
          command: ls
          options:
            command_args: -al /host_tmp

      global_options:
        mounts:
          - /tmp:/host_tmp:ro

    - app_type: shell

      name: test-echo-module-folder
      script:
        - echo $OTHER_VALUE

Apptainer#

One container image with one or more entrypoints, each mapping an executable name to a command run inside the container.

Field	Purpose
`container`	The image to use (below).
`entrypoints`	The executables provided (below).
`global_options`	Options applied to every entrypoint.

container — splits the image reference into path:version:

Field	Purpose
`path`	The image URL, excluding the version or tag. `docker`, `shub`, `oras` and `https` schemes are accepted.
`version`	The image version or tag.

entrypoints — each entry is one executable:

Field	Purpose
`name`	The executable provided.
`command`	The command to run inside the container. Defaults to `name`.
`options`	Options applied to this entrypoint only.

options and global_options — both take the same fields:

Field	Purpose
`apptainer_args`	Arguments passed to Apptainer when launching the container.
`command_args`	Arguments passed to the command being run.
`mounts`	Mount points as `host_path[:container_path[:opts]]`, where `opts` is `ro` or `rw` (default `rw`).
`host_binaries`	Host binaries, found on the current `PATH`, to mount into the container at `/usr/bin/<name>`.

Shell#

A single executable running a bash script.

Field	Purpose
`name`	The executable provided.
`script`	The lines of bash it runs.

Binary#

An executable downloaded, hash-checked and added to the path.

Field	Purpose
`name`	The executable provided.
`url`	Where the binary is downloaded from.
`hash`	The expected hash of the download.
`hash_type`	`sha256`, `sha512`, `md5`, or `none` to skip the check.

The demo argocd Module uses one:

module:
  name: argocd
  version: v2.14.10
  description: Demonstration of binary download

  applications:
    - app_type: binary
      name: argocd
      url: https://github.com/argoproj/argo-cd/releases/download/v2.14.10/argocd-linux-amd64
      hash_type: sha256
      hash: d1750274a336f0a090abf196a832cee14cb9f1c2fc3d20d80b0dbfeff83550fa

Settings#

settings.yaml holds deployment-wide settings. It currently has a single field, default_versions, mapping a Module name to the version handed to module load <name> when no version is given:

default_versions:
  dls-pmac-control: "0.1"

How that choice is resolved — and how to keep a version out of automatic selection — is covered in default version resolution.