The site file templates#

eb-pipeline init writes a site file from one of two built-in templates. Each is a complete site file that check finds valid, with placeholder values only: names in angle brackets, such as <build-user>, and paths and names, such as /opt/eb and small-lab, that stand for the site’s own. The examples on this page come from docs/examples/templates.sh.

eb-pipeline init --list
small-cluster    Slurm, one CPU target; no EESSI, inode quota or licences
eessi-site       Slurm, CPU and GPU targets on an EESSI site layer, with quota, caches and licences

Template

Targets

Phases it turns on, besides preflight and build

small-cluster

cpu

logs

eessi-site

cpu-a, cpu-b, gpu-a, gpu-b

licences, shard, sources, admission, caches and logs

init --template NAME prints the template, and init --template NAME --out FILE writes it to FILE:

eb-pipeline init --template small-cluster --out small-cluster.toml
eb-pipeline check --site small-cluster.toml
INFO [init] -: wrote template small-cluster to small-cluster.toml
INFO [check] small-lab: site file is valid

init refuses a file that exists, and exits 2, as it does for an unknown template or none:

eb-pipeline init --template small-cluster --out small-cluster.toml
ERROR [main] -: cannot create small-cluster.toml: File exists (os error 17)

small-cluster#

A Slurm cluster with one CPU node type, and none of the European Environment for Scientific Software Installations (EESSI), an inode quota or licences. Each command of a run starts with srun and the launch arguments of its role, from [phase_defaults], and the build of a line runs with the EasyBuild module loaded. A failed line keeps its EasyBuild log, and a run rotates the log tree with eb-keep-logs rotate --compress-after 60.

# A small Slurm cluster: one CPU node type, no EESSI, no inode quota, no licences.
# Every value is a placeholder.
schema_version = 1
kind = "site"

[site]
name = "small-lab"
build_account = "easybuild"
default_group = "easybuild"
stack_generation = "2026a"

[scheduler]
kind = "slurm"
launch = "srun"
job_name_template = "{project}-{build}-{phase}"

# Inside an allocation, srun without a task count starts one task per
# allocated task; every role asks for one.
[phase_defaults]
plan = "-p batch -N 1 --ntasks-per-node=1 -c 1 -t 15:00"
short = "-p batch -N 1 --ntasks-per-node=1 -c 1 -t 15:00"
build = "-p batch -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00"
cpu = "-p batch -N 1 --ntasks-per-node=1 -c 16 -t 1-00:00:00"
cache = "-p batch -N 1 --ntasks-per-node=1 -c 1 -t 15:00"

[[targets]]
name = "cpu"
build_lists = ["lab-2026a.list"]
default = true

[filesystems]
scratch = "/scratch/easybuild"
tmp = "/scratch/easybuild/tmp"
build_path = "/scratch/easybuild/build"
source_paths = ["/opt/eb/sources"]
install_root = "/opt/eb/2026a"
log_root = "/opt/eb/2026a/logs"

[modules]
init = ["EasyBuild"]

[logs]
keep_failed = true

[logs.rotate]
compress_after_days = 60

eessi-site#

A site that installs into its own layer on top of EESSI, with two CPU and two GPU node types. Its targets install where EESSI-extend puts a site installation for their cpu_target and accel_target. The GPU target gpu-a keeps only the lines of a list that are for it, and wraps the commands of its CPU-only prerequisites in a route command, which build them with the hardware variables of another class. A run admits each unit against an inode quota, shards the list, prefetches sources without the robot, writes module caches for cpu-a and gpu-a, rebuilds installed modules through eb-staged-rebuild with a state root per target, and checks that each licensed package has a group, a version threshold or an exemption.

eb-pipeline init --template eessi-site --out eessi-site.toml
eb-pipeline check --site eessi-site.toml
eb-pipeline targets --site eessi-site.toml
INFO [init] -: wrote template eessi-site to eessi-site.toml
INFO [check] cluster-a: site file is valid
cpu-a
cpu-b
gpu-a
gpu-b
# A site that extends EESSI: several CPU and GPU node types, inode admission,
# per-target module caches. Every value is a placeholder.
schema_version = 1
kind = "site"

[site]
name = "cluster-a"
build_account = "<build-user>"
default_group = "<build-user>"
stack_generation = "<generation>"

[site.tools.eb_stack]
bin = "/opt/eb-tools/bin/eb-stack"
min_version = "0.7.3"

[site.tools.eb_keep_logs]
bin = "/opt/eb-tools/bin/eb-keep-logs"

[site.tools.eb_staged_rebuild]
bin = "/opt/eb-tools/bin/eb-staged-rebuild"

[scheduler]
kind = "slurm"
launch = "srun"
common_args = ["--mpi=none"]
job_name_template = "{project}-{build}-{phase}"

[scheduler.env]
SLURM_OVERLAP = "1"

[phase_defaults]
plan = "-p <small-partition> -N 1 --ntasks-per-node=1 -c 1 --mem=4G -t 30:00"
short = "-p <small-partition> -N 1 --ntasks-per-node=1 -c 1 --mem=4G -t 5:00"
cache = "-p <small-partition> -N 1 --ntasks-per-node=1 -c 1 --mem=4G -t 5:00"

[[targets]]
name = "cpu-a"
build_lists = ["cpu-a.list"]
eb_optarch = "GCC:-march=<march>"
max_parallel = 128
cpu_target = "x86_64/<vendor>/<uarch>"
site_prefix = "/opt/eb/cpu-a"
# EESSI-extend installs into <site_prefix>/versions/<release>/software/linux/<cpu_target>.
software_root = "/opt/eb/cpu-a/versions/<release>/software/linux/<cpu_target>/software"
modules_root = "/opt/eb/cpu-a/versions/<release>/software/linux/<cpu_target>/modules"
default = true

[targets.phases]
build = "-p <cpu-partition> -N 1 --ntasks-per-node=1 -c 128 -t 2-00:00:00"

[targets.hardware]
vendor_id = "<vendor-id>"
cpu_family = 25
model = 1

[targets.build_types.staging]
eb_optarch = "GCC:-march=<other-march>"

[[targets]]
name = "cpu-b"
build_lists = ["cpu-b.list"]
eb_optarch = "GCC:-march=<march>"
max_parallel = 96
cpu_target = "x86_64/<vendor>/<uarch>"
site_prefix = "/opt/eb/cpu-b"
software_root = "/opt/eb/cpu-b/versions/<release>/software/linux/<cpu_target>/software"
modules_root = "/opt/eb/cpu-b/versions/<release>/software/linux/<cpu_target>/modules"

[targets.phases]
build = "-p <cpu-partition-b> -N 1 --ntasks-per-node=1 -c 96 -t 2-00:00:00"

[[targets]]
name = "gpu-a"
build_lists = ["gpu-a.list"]
eb_optarch = "GCC:-march=<march>"
cuda_compute_capabilities = "9.0"
cpu_target = "x86_64/<vendor>/<uarch>"
accel_target = "accel/nvidia/cc90"
site_prefix = "/opt/eb/gpu-a"
# With EESSI_ACCELERATOR_INSTALL set, EESSI-extend appends /<accel_target> for
# an NVIDIA target, and the roots follow it.
software_root = "/opt/eb/gpu-a/versions/<release>/software/linux/<cpu_target>/software"
modules_root = "/opt/eb/gpu-a/versions/<release>/software/linux/<cpu_target>/modules"

[targets.phases]
build = "-p <gpu-partition> -N 1 --ntasks-per-node=1 -c 72 --gpus-per-node=4 -t 2-00:00:00"
cpu = "-p <small-partition> -N 1 --ntasks-per-node=1 -c 64 --mem=128G -t 2-00:00:00"

[targets.route]
kind = "command"
command = "/opt/eb-tools/bin/cpu-route"
args = ["--runtime", "{runtime_root}", "--ro", "{shares_ro}", "--rw", "{shares_rw}", "--tag", "{target}-{phase}"]
runtime_root = "/opt/eb-tools/route-runtime"
shares_ro = ["{work_dir}"]
shares_rw = ["{phase_dir}", "{log_dir}"]
receipt_digest_env = "ROUTE_RECEIPT_DIGEST"
phases = ["build", "sources"]

[targets.route.env]
ROUTE_LABEL = "{target}-{phase}"

# Lines of a build list can name the targets they are for with a per-line
# option; a line without it is planned for every target.
[targets.select]
option = "--only-targets"
value = "gpu-a"
separator = ","
when_absent = "all"
strip = true

# CPU-role phases run on a different hardware class.
[targets.hardware]
vendor_id = "<vendor-id>"
cpu_family = 25
model = 1

[targets.cpu_hardware]
vendor_id = "<vendor-id>"
cpu_family = 25
model = 17

[targets.fetch_profile]
mirror = "https://mirror.example.org/sources"
retries = 3

[targets.package_env."<Name>"]
OPTARCH = "<gpu-value>"

[[targets]]
name = "gpu-b"
build_lists = ["gpu-b.list"]
eb_optarch = "GCC:-march=<march>"
cuda_compute_capabilities = "8.0"
cpu_target = "x86_64/<vendor>/<uarch>"
accel_target = "accel/nvidia/cc80"
site_prefix = "/opt/eb/gpu-b"
software_root = "/opt/eb/gpu-b/versions/<release>/software/linux/<cpu_target>/software"
modules_root = "/opt/eb/gpu-b/versions/<release>/software/linux/<cpu_target>/modules"

[targets.phases]
build = "-p <gpu-partition-b> -N 1 --ntasks-per-node=1 -c 32 --gpus-per-node=4 -t 2-00:00:00"

[filesystems]
scratch = "/scratch/<build-user>"
tmp = "/scratch/<build-user>/tmp"
# A build path per target, so that targets can build one easyconfig at once.
build_path = "/scratch/<build-user>/build/{target}"
# EasyBuild downloads a missing source into the first entry. Before targets
# build at once, give them a first entry each, such as
# "/scratch/<build-user>/sources/{target}".
source_paths = ["/opt/eb/sources", "/srv/shared/sources"]
install_root = "/opt/eb"
log_root = "/opt/eb/logs"
shard_dir = "/scratch/<build-user>/shards"
read_only_installdir = true

[admission]
enabled = true
required = true
quota_cmd = "/opt/eb-tools/bin/quota-json"
live_jobs_cmd = "/opt/eb-tools/bin/live-jobs"
lock = "/scratch/<build-user>/admission.lock"
lock_kind = "posix"
reservations = "/scratch/<build-user>/reservations"
margin = 100000
unknown_reserve = 150000
default_footprint = 150000
job_id_env = "SLURM_JOB_ID"
quota_total = 4000000
line_overhead = 1000
attempts = 5
wait_seconds = 60
max_wait_seconds = 600

[shards]
count = 4
planner_exit_unsharded = 3
easyconfigs = ["/opt/eb-tools/easyconfigs"]
installed_modules_dirs = ["/opt/eb/noarch/modules/all"]
installed_modules_dirs_from_env = ["SITE_INSTALLED_MODULES"]

[sources]
prefetch = true
# `--fetch` ignores installed modules, so with the robot every dependency's
# sources are fetched, EESSI's included.
extra_args = ["--disable-robot"]

[modules]
init = ["<eessi-module>/<release>", "EasyBuild", "<eessi-extend-module>"]

[modules.eessi]
site_install = true
bootstrap_modulepath = "/opt/eb/noarch/modules/all"

[modules.package_env."<Name>"]
OPTARCH = "<value>"

[caches]
enabled = true
command = "/opt/eb-tools/bin/write-module-cache"
bindings = "/opt/eb-tools/cache/bindings.json"
init_module = "<default-site-module>"

[[caches.targets]]
target = "cpu-a"
config = "/opt/eb-tools/cache/cpu-a.json"
init_module = "<site-module>"

[[caches.targets]]
target = "gpu-a"
config = "/opt/eb-tools/cache/gpu-a.json"

[logs]
keep_failed = true

[logs.rotate]
compress_after_days = 30
delete_after_days = 365

[rebuild]
staged = true
# A state root, and so a lock, per target, under its site prefix.
state_root = "/opt/eb/{target}/.eb-staged-rebuild"
backend = "auto"
grace_hours = 24
prepare = "/opt/eb-tools/bin/apply-group"

[licences]
enforce = true

[licences.groups]
"<Name1>" = "<group1>"
"<Name2>" = "<group2>"

[licences.below_version]
"<Name2>" = "2.0"

[licences.required]
software = ["<Name1>", "<Name2>"]

[licences.env."<Name1>"]
LICENSE_FILE = "/opt/licences/<Name1>/license.dat"

See also#