Quickstart with containers

Containers

This guide installs Slurm-web with OCI container images using docker run or podman run. This path is generic and versatile; it is recommended for running containers in production and custom orchestration (systemd, Kubernetes, your own Compose file).

Requirements

Slurm JWT authentication

Generate random Slurm JWT signing key with restrictive permissions:

# dd if=/dev/random of=/var/spool/slurm/jwt_hs256.key bs=32 count=1
# chown slurm:slurm /var/spool/slurm/jwt_hs256.key
# chmod 0600 /var/spool/slurm/jwt_hs256.key

Edit main Slurm and SlurmDBD configuration to enable JWT alternative authentication:

AuthAltTypes=auth/jwt
AuthAltParameters=jwt_key=/var/spool/slurm/jwt_hs256.key

Restart slurmctld and slurmdbd services to update configuration:

# systemctl restart slurmctld slurmdbd
More links

Install slurmrestd

Slurm-web extracts Slurm information from the REST API provided its slurmrestd daemon. This daemon must be installed on the host. The installation method depends on the origin of Slurm packages deployed on the cluster:

  • SchedMD RPM packages

  • EPEL

  • SchedMD Deb packages

  • Debian

On clusters deployed with SchedMD official RPM packages, install slurmrestd daemon with this command:

# dnf install slurm-slurmrestd
Please refer to SchedMD official Slurm installation guide for more help.

On clusters deployed with RPM packages from EPEL community, install slurmrestd daemon with this command:

# dnf install slurm-slurmrestd

On clusters deployed with SchedMD official Deb packages, install slurmrestd daemon with this command:

# apt install slurm-smd-slurmrestd
Please refer to SchedMD official Slurm installation guide for more help.

On clusters deployed with RPM packages from Debian community, install slurmrestd with this command:

# apt install slurmrestd

Setup slurmrestd

Create /etc/systemd/system/slurmrestd.service.d/slurm-web.conf drop-in configuration override for slurmrestd service:

[Service]
# Unset vendor unit ExecStart and Environment to avoid cumulative definition
ExecStart=
Environment=
Environment="SLURM_JWT=daemon"
ExecStart=/usr/sbin/slurmrestd $SLURMRESTD_OPTIONS -a rest_auth/jwt unix:/run/slurmrestd/slurmrestd.socket
RuntimeDirectory=slurmrestd
RuntimeDirectoryMode=0755
User=slurmrestd
Group=slurmrestd
DynamicUser=yes
With this configuration, slurmrestd listens for incoming connections on Unix socket with jwt authentication method. It is also possible to configure slurmrestd to listen on TCP/IP socket. Please refer to slurmrestd configuration page for more details.

Make systemd reload units changes on disk:

# systemctl daemon-reload

Enable and start slurmrestd service:

# systemctl enable --now slurmrestd.service

To check slurmrestd daemon is properly running with JWT authentication, run this command:

# export $(scontrol token)
# curl -H X-SLURM-USER-TOKEN:$SLURM_JWT --unix-socket /run/slurmrestd/slurmrestd.socket http://slurm/slurm/v0.0.41/diag
{
   "meta": {
     "plugin": {
      "type": "openapi\/slurmctld",
      "name": "Slurm OpenAPI slurmctld",
      "data_parser": "data_parser\/v0.0.41",
      "accounting_storage": "accounting_storage\/slurmdbd"
    },
   }
  …
}

In case of failure, please refer to troubleshooting guide for help.

More links

Pull images

Pull the published images from GitHub Container Registry (GHCR):

  • Docker

  • Podman

$ docker pull ghcr.io/rackslab/slurm-web-agent:latest
$ docker pull ghcr.io/rackslab/slurm-web-gateway:latest
$ podman pull ghcr.io/rackslab/slurm-web-agent:latest
$ podman pull ghcr.io/rackslab/slurm-web-gateway:latest
Pin images to a release tag (for example ghcr.io/rackslab/slurm-web-agent:v7.0.0) instead of latest for reproducible deployments.

Storage layout

Agent and gateway read configuration from /etc/slurm-web/ and secrets from /var/lib/slurm-web/ inside containers. Those paths are fixed; what varies is how you persist files on the host.

This guide stores files on the host under the same paths as inside containers:

Host Container path Purpose

/etc/slurm-web/

/etc/slurm-web/

Configuration files

/var/lib/slurm-web/

/var/lib/slurm-web/

Secrets (session and JWT signing keys)

Create a slurm-web system user on the host and the secrets directory:

$ sudo useradd --system --user-group --home-dir /var/lib/slurm-web --create-home slurm-web
$ sudo chown -R slurm-web:slurm-web /var/lib/slurm-web

Create the configuration directory:

$ sudo mkdir -p /etc/slurm-web
$ sudo chown -R root:slurm-web /etc/slurm-web
$ sudo chmod 0750 /etc/slurm-web

The docker / podman commands below use the slurm-web host account.

For rootless Podman, named volumes and other storage alternatives, see the containers reference installation guide.

Initial setup

Create agent configuration file /etc/slurm-web/agent.ini to set the cluster name and slurmrestd URI, for example:

[service]
cluster=nova

[slurmrestd]
uri=http://SLURMRESTD_HOST:6820

Replace nova with your cluster name and SLURMRESTD_HOST with a hostname or address reachable from the agent container.

Create gateway configuration file /etc/slurm-web/gateway.ini with at least:

[agents]
url=http://AGENT_HOST:5012

Replace AGENT_HOST in [agents] url with the hostname or IP where the agent container is reachable from the gateway.

More links

Slurm-web secret keys

Before starting gateway services, generate two secret files with the slurm-web CLI: a gateway session secret to secure server-side login state during authentication flows, and a JSON Web Token (JWT) signing key for authentication between Slurm-web components. Both files must be stored in the persistent storage mounted at /var/lib/slurm-web/ in agent and gateway containers — see Storage layout.

Generate the gateway session secret key (default /var/lib/slurm-web/session.key) with:

  • Docker

  • Podman

$ docker run --rm \
     --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-gateway:latest gen-session-key
INFO ⸬ Running slurm-web gen-session-key
INFO ⸬ Generated session key file /var/lib/slurm-web/session.key
$ podman run --rm \
    --userns=keep-id --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-gateway:latest gen-session-key
INFO ⸬ Running slurm-web gen-session-key
INFO ⸬ Generated session key file /var/lib/slurm-web/session.key

Generate the JWT signing key (default /var/lib/slurm-web/jwt.key) with:

  • Docker

  • Podman

$ docker run --rm \
     --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-gateway:latest gen-jwt-key
INFO ⸬ Running slurm-web gen-jwt-key
INFO ⸬ Generating JWT private key file /var/lib/slurm-web/jwt.key
$ podman run --rm \
    --userns=keep-id --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-gateway:latest gen-jwt-key
INFO ⸬ Running slurm-web gen-jwt-key
INFO ⸬ Generating JWT private key file /var/lib/slurm-web/jwt.key
More links

Slurm JWT siging key

For Slurm-web authentication to slurmrestd, copy the Slurm JWT signing key into the agent secrets directory as slurmrestd.key:

# cp /var/spool/slurm/jwt_hs256.key /var/lib/slurm-web/slurmrestd.key

Restrict access to this sensitive file with read permission to the slurm-web system user only:

# chown slurm-web:slurm-web /var/lib/slurm-web/slurmrestd.key
# chmod 400 /var/lib/slurm-web/slurmrestd.key
With this configuration, Slurm-web agent automatically generates its tokens with short lifespan for authentication to slurmrestd. As an alternative, Slurm-web supports static tokens. Please refer to slurmrestd configuration page for more details.

To test Slurm-web agent and slurmrestd service configuration parameters, you can run slurm-web connect-check command. It tries to send HTTP request to slurmrestd with Slurm-web agent configuration parameters and reports the status. For example:

  • Docker

  • Podman

$ docker run --rm \
     --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/agent.ini:/etc/slurm-web/agent.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-agent:latest connect-check
✅ connection successful! (cluster: hpc, slurm: 25.11.0, api: 0.0.44)
$ podman run --rm \
    --userns=keep-id --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/agent.ini:/etc/slurm-web/agent.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-agent:latest connect-check
✅ connection successful! (cluster: hpc, slurm: 25.11.0, api: 0.0.44)

First Access

Slurm-web is now ready to start!

Start the agent and gateway containers:

  • Docker

  • Podman

$ docker run -d --name slurm-web-agent \
    -p 5012:5012 \
     --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/agent.ini:/etc/slurm-web/agent.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-agent:latest

$ docker run -d --name slurm-web-gateway \
    -p 5011:5011 \
     --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/gateway.ini:/etc/slurm-web/gateway.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-gateway:latest
$ podman run -d --name slurm-web-agent \
    -p 5012:5012 \
    --userns=keep-id --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/agent.ini:/etc/slurm-web/agent.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-agent:latest

$ podman run -d --name slurm-web-gateway \
    -p 5011:5011 \
    --userns=keep-id --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/gateway.ini:/etc/slurm-web/gateway.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    ghcr.io/rackslab/slurm-web-gateway:latest

Connect your browser to the gateway on http://localhost:5011. You should see the dashboard of the configured cluster:

slurm web policy admin

By default, the docker run / podman run commands above publish the gateway on port TCP/5011 of the container host. Adjust the -p option to expose a different host port.

The [ui] host value must match the URL used in the browser, including scheme, host, port and path. Define it in gateway.ini when Slurm-web is exposed on a different public URL:

[ui]
host=http://HOSTNAME_OR_IP:5011

Actual values depend on your DNS hostname or the public IP address of the host.

Slurm-web is now available on: http://HOSTNAME_OR_IP:5011

Please refer to gateway configuration reference documentation for more details.
In case of failure, please refer to troubleshooting guide for help.
More details

Going Further

Slurm-web is now running. The following optional sections help you improve performance, secure access, customize authorization and enable advanced features.

In-memory Cache

Slurm-web has a transparent caching feature which can use Redis (or any compatible alternative) in-memory database to cache Slurm responses.

It is highly recommended to setup cache on Slurm-web agent to significantly reduce the amount of repetitive requests sent to Slurm and reduce its load.

Start Redis container alongside the agent:

  • Docker

  • Podman

$ docker run -d --name slurm-web-redis \
    -p 6379:6379 \
    docker.io/library/redis:7-alpine
$ podman run -d --name slurm-web-redis \
    -p 6379:6379 \
    docker.io/library/redis:7-alpine

Edit agent configuration file /etc/slurm-web/agent.ini to enable cache:

[cache]
enabled=yes
It is also possible to setup a remote Redis server, configure a password to access a server secured in protected mode or adjust cache timeouts. More details in cache section of agent configuration file.

Restart the agent component to apply the new configuration:

  • Docker

  • Podman

$ docker restart slurm-web-agent
$ podman restart slurm-web-agent
More details

User Authentication

To restrict access to the dashboard, enable authentication on the gateway and choose either LDAP or OpenID Connect (OIDC). Only one method is active per deployment.

See authentication documentation for an overview and setup guides:

Authorization Policy

At this stage, the agent is running with default authorization policy. You can create a file /etc/slurm-web/policy.ini to define your custom RBAC fine-grain policy with specific roles.

Follow Authorization policy reference documentation to learn the policy file format, review examples and choose the actions granted to each role.

More details

RacksDB database

Slurm-web can use RacksDB to generate advanced interactive graphical representations of datacenters racks with the compute nodes. For this feature, RacksDB database must be defined with your HPC cluster infrastructure. This is actually quick and easy based on the examples provided.

Some requirements must be fulfilled in this database:

  • The infrastructure must have the same name as the cluster previously declared in agent configuration file.

  • The compute tag must be assigned to all compute nodes declared in Slurm configuration.

You can choose another tag name but you must declare it in racksdb section of agent configuration, for example:

[racksdb]
tags=blade

Stop and remove the existing agent container before starting it again with the new /var/lib/racksdb read-only volume argument:

  • Docker

  • Podman

$ docker rm -f slurm-web-agent
$ docker run -d --name slurm-web-agent \
    -p 5012:5012 \
     --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/agent.ini:/etc/slurm-web/agent.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    -v /var/lib/racksdb:/var/lib/racksdb:ro \
    ghcr.io/rackslab/slurm-web-agent:latest
$ podman rm -f slurm-web-agent
$ podman run -d --name slurm-web-agent \
    -p 5012:5012 \
    --userns=keep-id --user $(id -u slurm-web):$(id -g slurm-web) \
    -v /etc/slurm-web/agent.ini:/etc/slurm-web/agent.ini:ro \
    -v /var/lib/slurm-web:/var/lib/slurm-web \
    -v /var/lib/racksdb:/var/lib/racksdb:ro \
    ghcr.io/rackslab/slurm-web-agent:latest

By default, RacksDB integration is in auto mode: the agent tries to load the database and schema and disables the feature with a warning in logs if unable to load.

If you don’t need this advanced interactive graphical representations feature and want to suppress the warning in logs, RacksDB integration can be disabled with the following lines in /etc/slurm-web/agent.ini:

[racksdb]
enabled=no
More links

Metrics

Slurm-web offers the possibility to export Slurm metrics in OpenMetrics format and integrate with Prometheus. This feature can be used to store metrics in timeseries databases and draw diagrams of historical data.

This feature is disabled by default.

Create Prometheus configuration on the host:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: slurm
    scrape_interval: 30s
    metrics_path: /metrics
    static_configs:
      - targets: ["AGENT_HOST:5012"]

Save this file as /etc/slurm-web/prometheus.yml and replace AGENT_HOST with the hostname or address where the agent container is reachable from the Prometheus container.

Start Prometheus:

  • Docker

  • Podman

$ docker run -d --name slurm-web-prometheus \
    -p 9090:9090 \
    -v /etc/slurm-web/prometheus.yml:/etc/prometheus/prometheus.yml:ro \
    -v prometheus-data:/prometheus \
    docker.io/prom/prometheus:v2.55.1 \
    --config.file=/etc/prometheus/prometheus.yml \
    --storage.tsdb.path=/prometheus
$ podman run -d --name slurm-web-prometheus \
    -p 9090:9090 \
    -v /etc/slurm-web/prometheus.yml:/etc/prometheus/prometheus.yml:ro \
    -v prometheus-data:/prometheus \
    docker.io/prom/prometheus:v2.55.1 \
    --config.file=/etc/prometheus/prometheus.yml \
    --storage.tsdb.path=/prometheus

Add [metrics] to /etc/slurm-web/agent.ini:

[metrics]
enabled=yes
host=http://PROMETHEUS_HOST:9090
restrict=
  10.0.0.0/8
  172.16.0.0/12
  192.168.0.0/16

Replace PROMETHEUS_HOST with the hostname or address where the Prometheus container is reachable from the agent container.

Restart the agent component to apply the new configuration:

  • Docker

  • Podman

$ docker restart slurm-web-agent
$ podman restart slurm-web-agent
More details

Multi-clusters

Slurm-web is designed to support distributed setup with a central server and multiple clusters. Compared to the steps above, the following changes must be considered:

  1. Install and setup slurmrestd on all clusters.

  2. Install Slurm-web agent on all clusters, colocated on the same hosts as slurmrestd.

  3. Install Slurm-web gateway on the central server.

  4. Setup production HTTP servers with HTTPS (SSL/TLS) for all agents and the gateway.

  5. Set URL of all agents in agents section of gateway configuration.

  6. Generate JWT signing key on central server and deploy this key on all agents servers (same key must be shared by all agents and the gateway).

  7. Deploy the RacksDB database at the default path on all agent servers (auto-loaded on restart).

  8. Deploy custom policy on all agents servers.

  9. Setup in-memory cache on all agents servers.

Et voilà!

1. Slurm-web 7.0.0 actually requires Slurm REST API v0.0.41 available in Slurm 24.05 and above. Please refer to Slurm REST API versions section for more details.