Skip to main content

API Reference

Complete CLI commands and Python API documentation for slurm-factory.

CLI Commands​

slurm-factory​

Main application command with global options.

slurm-factory [OPTIONS] COMMAND [ARGS]...

Global Options:

  • --project-name TEXT - LXD project name for resource creation (env: IF_PROJECT_NAME) [default: slurm-factory]
  • --verbose, -v - Enable verbose output
  • --install-completion - Install shell completion
  • --show-completion - Show shell completion script
  • --help - Show help message and exit

Available Commands:

  • build-slurm - Build a specific Slurm version
  • clean - Clean up Docker containers and images

build-slurm​

Build a specific Slurm version with relocatable packages.

slurm-factory build-slurm [OPTIONS]

Description:

Builds Slurm packages using Docker containers and Spack. Supports multiple OS toolchains, GPU acceleration, and buildcache publishing with GPG signing.

Options:

  • --slurm-version [26.05|25.11|24.11|23.11] - Slurm version to build [default: 25.11]
  • --toolchain TEXT - OS toolchain to use (noble, jammy, resolute, rockylinux10, rockylinux9, rockylinux8) [default: noble]
  • --gpu - Enable GPU support (CUDA/ROCm) - creates larger packages
  • --verify - Enable relocatability verification (for CI/testing)
  • --no-cache - Force a fresh build without using Docker cache
  • --buildcache TEXT - Use buildcache: none (default), all (dependencies + Slurm), deps (only dependencies) [default: none]
  • --publish TEXT - Publish to buildcache: none (default), slurm (Slurm tarball + Spack), spack (Spack only), deps (only dependencies), all [default: none]
  • --enable-hierarchy - Enable Core/Compiler/MPI module hierarchy
  • --signing-key TEXT - GPG key ID for signing buildcache packages (e.g., '0xKEYID')
  • --gpg-private-key TEXT - Base64-encoded GPG private key to import into Docker container for signing
  • --gpg-passphrase TEXT - Passphrase for the GPG private key (if encrypted)
  • --help - Show help message and exit

OS Toolchains:

Each toolchain uses the OS-provided compiler for maximum binary compatibility:

  • resolute: Ubuntu 26.04, GCC 15.2.0, glibc 2.42
  • noble (default): Ubuntu 24.04, GCC 13.3.0, glibc 2.39
  • jammy: Ubuntu 22.04, GCC 11.4.0, glibc 2.35
  • rockylinux10: Rocky Linux 10 / RHEL 10, GCC 14.3.1, glibc 2.39
  • rockylinux9: Rocky Linux 9 / RHEL 9, GCC 11.5.0, glibc 2.34
  • rockylinux8: Rocky Linux 8 / RHEL 8, GCC 8.5.0, glibc 2.28

See Packages for the live cache browser and current support matrix.

Build Types:

  • Default: ~2-5GB, CPU-only with OpenMPI and standard features
  • --gpu: ~15-25GB, includes CUDA/ROCm support for GPU workloads
  • --verify: Enable relocatability verification for CI/testing
  • --no-cache: Force a fresh build without using Docker layer cache

Examples:

# Build default CPU version (25.11, noble)
slurm-factory build-slurm

# Build specific version
slurm-factory build-slurm --slurm-version 24.11

# Build for Ubuntu 22.04
slurm-factory build-slurm --toolchain jammy

# Build for Rocky Linux 9 / RHEL 9
slurm-factory build-slurm --toolchain rockylinux9

# Build for Rocky Linux 8 / RHEL 8
slurm-factory build-slurm --toolchain rockylinux8

# Build with GPU support
slurm-factory build-slurm --gpu

# Build with verification (CI)
slurm-factory build-slurm --verify

# Build without Docker cache
slurm-factory build-slurm --no-cache

# Build with module hierarchy
slurm-factory build-slurm --enable-hierarchy

# Build using remote buildcache for dependencies
slurm-factory build-slurm --buildcache=deps

# Build and publish to buildcache
slurm-factory build-slurm --publish=slurm

# Build and publish only dependencies
slurm-factory build-slurm --publish=deps

# Build and publish with GPG signing
slurm-factory build-slurm --publish=all --signing-key 0xDFB92630BCA5AB71

clean​

Clean up Docker containers and images from slurm-factory builds.

slurm-factory clean [OPTIONS]

Description:

Removes stopped containers by default. Use --full to remove both containers and images for complete cleanup.

Options:

  • --full - Remove Docker images in addition to containers
  • --help - Show help message and exit

Examples:

# Remove stopped containers
slurm-factory clean

# Remove containers and images
slurm-factory clean --full

Configuration​

Environment Variables​

  • IF_PROJECT_NAME - Default project name for Docker containers and resources [default: slurm-factory]
  • SPACK_JOBS - Number of parallel build jobs (optional)

Cache Directories​

slurm-factory uses several cache directories under ~/.slurm-factory/:

~/.slurm-factory/
├── builds/              # Final tarball packages
├── spack-stage/         # Spack build stage cache
├── spack-buildcache/    # Binary package cache (compiled packages)
├── spack-sourcecache/   # Source archive downloads
└── build-debug/         # Build diagnostics and debug artifacts

Build Artifacts​

Build outputs are stored in ~/.slurm-factory/builds/:

~/.slurm-factory/builds/
├── noble/
│   └── 26.05/
│       └── slurm-26.05-noble-amd64-software.tar.gz       # Ubuntu 24.04 build
├── jammy/
│   └── 25.11/
│       └── slurm-25.11-jammy-amd64-software.tar.gz       # Ubuntu 22.04 build
├── resolute/
│   └── 26.05/
│       └── slurm-26.05-resolute-arm64-software.tar.gz    # Ubuntu 26.04 build
├── rockylinux9/
│   └── 25.11/
│       └── slurm-25.11-rockylinux9-amd64-software.tar.gz # Rocky Linux 9 / RHEL 9
└── rockylinux8/
  └── 24.11/
    └── slurm-24.11-rockylinux8-amd64-software.tar.gz # Rocky Linux 8 / RHEL 8

GPG Signing​

All buildcache packages can be signed with GPG for security and integrity.

Signing Options​

When using --publish, you can sign packages with:

  • --signing-key TEXT - GPG key ID (e.g., 0xDFB92630BCA5AB71)
  • --gpg-private-key TEXT - Base64-encoded private key
  • --gpg-passphrase TEXT - Private key passphrase (if encrypted)

Example with Signing​

# Build and publish with GPG signing
slurm-factory build-slurm \
  --slurm-version 25.11 \
  --publish=all \
  --signing-key 0xDFB92630BCA5AB71 \
  --gpg-private-key "$(base64 -w0 < ~/.gnupg/private.key)" \
  --gpg-passphrase "your-passphrase"

Verification​

Packages signed with GPG can be verified by Spack:

# Import GPG keys
spack buildcache keys --install --trust

# Install with automatic signature verification
spack install slurm@25.11

Exit Codes​

  • 0 - Success
  • 1 - General error (build failed, validation error, etc.)
  • 2 - Command-line usage error

Additional Resources​

Exceptions​

  • SlurmFactoryError - Base exception
  • DockerError - Docker operation failures
  • BuildError - Build failures
  • ConfigurationError - Invalid configuration