hpc-compose

hpc-compose is a single-binary launcher that turns a Compose-like spec into one Slurm job running one or more services through Enroot and Pyxis.

It is intentionally not a full Docker Compose implementation. It focuses on the subset that maps cleanly to one Slurm allocation, plus either single-node services or one allocation-wide distributed service without adding a separate orchestration layer.

What It Is For

• one Slurm allocation per application
• single-node jobs and constrained multi-node distributed runs
• optional helper services pinned to the allocation's primary node
• remote images such as redis:7 or existing local .sqsh images
• login-node image preparation through x-enroot.prepare
• readiness-gated startup across dependent services

What It Does Not Support

• Compose build:
• ports
• networks / network_mode
• Compose restart (use services.<name>.x-slurm.failure_policy instead)
• deploy
• arbitrary multi-node orchestration or partial-node service placement

For the exact first-class vs raw pass-through vs out-of-scope Slurm boundary, see Supported Slurm model.

Install

curl -fsSL https://raw.githubusercontent.com/NicolasSchuler/hpc-compose/main/install.sh | sh

The installer selects the newest GitHub release for the current Linux or macOS machine and installs hpc-compose into ~/.local/bin by default. Manual release downloads remain documented in docs/src/installation.md.

Minimal example

name: hello

x-slurm:
  time: "00:10:00"
  mem: 4G

services:
  app:
    image: python:3.11-slim
    command: python -c "print('Hello from Slurm!')"

hpc-compose submit --watch -f compose.yaml

submit --watch is the normal run. Use validate, inspect, preflight, or prepare as the debugging flow when you are adapting a new spec or isolating a failure.

Documentation

• Published docs: nicolasschuler.github.io/hpc-compose
• Installation: docs/src/installation.md
• Quickstart: docs/src/quickstart.md
• Execution model: docs/src/execution-model.md
• Runbook: docs/src/runbook.md
• Examples: docs/src/examples.md
• Spec reference: docs/src/spec-reference.md
• Supported Slurm model: docs/src/supported-slurm-model.md
• Docker Compose migration: docs/src/docker-compose-migration.md
• Contributor architecture notes: docs/src/architecture.md

Citation

If you use hpc-compose in research, please cite the software. GitHub also exposes the same metadata through the repository citation UI via CITATION.cff.

@software{schuler_hpc_compose_2026,
  author = {Schuler, Nicolas},
  title = {hpc-compose},
  version = {0.1.15},
  year = {2026},
  publisher = {Karlsruhe Institute of Technology (KIT)},
  url = {https://github.com/NicolasSchuler/hpc-compose}
}