The deployment area

The deployment area is the directory tree that deploy-tools writes into. It is normally a shared filesystem location that end users put on their MODULEPATH, so its layout is important to the end user. This page explains what lives where, and why.

Layout

Everything below is created and maintained by deploy-tools; nothing in the area is meant to be edited by hand.

<deployment root>/
├── deployment.yaml          # snapshot of the deployed configuration
├── modules/                 # Modules Area — the built files for every Module
│   └── <name>/<version>/
│       ├── modulefile        # the Environment Modules (Tcl) file
│       ├── entrypoints/      # the executables added to PATH on module load
│       ├── module.yaml       # this Module's configuration snapshot
│       └── sif_files/        # Apptainer images, when the Module uses any
├── modulefiles/             # Modulefiles Folder — placed on MODULEPATH
│   └── <name>/
│       ├── <version>         # absolute symlink into modules/<name>/<version>/modulefile
│       └── .version          # records the default version (see below)
├── deprecated/
│   └── modulefiles/         # Deprecated Folder — optionally on MODULEPATH
│       └── <name>/<version>  # symlink for a deprecated Module version
└── build/                   # transient build area (default location)

The split between the Modules Area (modules/) and the Modulefiles Folder (modulefiles/) is the central design choice. The Modules Area holds the real files for every version that has been deployed and not removed, both live and deprecated. The Modulefiles Folder holds only a thin tree of symlinks, one per version, pointing at the corresponding modulefile. Users put only the modulefiles directories on their MODULEPATH, making each Module visible to module avail and module load.

Deprecation is therefore cheap and reversible: the built files never move, only the symlink moves between modulefiles/ and deprecated/modulefiles/. See the release lifecycle for the full set of transitions.

The build area

Modules are first assembled under the build area (build/ by default), then moved into the Modules Area. The move is a filesystem rename, which is atomic only when source and destination are on the same filesystem — hence the default build area sits inside the deployment root. Building and deploying separately means a half-built Module is never visible: either the rename succeeds and the whole version appears, or nothing changes.

The transient build/ directory and the large Apptainer sif_files/ images are deliberately kept out of the deployment area’s git history (see snapshots and the compare safety net). They are reference-only data used by the compare command, not something to revert to.

Why modulefiles embed absolute paths

A generated modulefile adds its Module’s executables to the user’s path with one line:

prepend-path PATH "<deployment root>/modules/<name>/<version>/entrypoints"

That path is absolute, so a deployment area cannot be relocated after the fact. This is a deliberate trade-off.

A path relative to the modulefile does not work. Environment Modules sources the file through the symlink under modulefiles/ without resolving it first ([info script] / ModulesCurrentModulefile report the link path). A relative path would be interpreted relative to the link’s location — which changes when a Module is deprecated and the link moves to a different location in the tree, silently breaking it.

This allows us to use two separate modulefiles/ folders, corresponding to live and deprecated modules, without needing to edit modulefiles after initial creation.