Docker

Docker

Slurm-web publishes OCI images for the agent and gateway on GitHub Container Registry (GHCR). Docker can run these images directly with docker run, or with the reference Compose stack using docker compose.

For full walkthroughs, see Quickstart with containers and Quickstart with Compose.

Images

  • ghcr.io/rackslab/slurm-web-agent — cluster agent

  • ghcr.io/rackslab/slurm-web-gateway — web gateway and UI

Use the latest tag for evaluation or a release tag matching a git tag (for example v7.0.0).

docker run

This section describes how to run Slurm-web with standalone docker run commands: persistent storage layout, file ownership requirements and the typical commands used to start and check the agent and gateway containers.

Storage layout

Agent and gateway read configuration from /etc/slurm-web/ and secrets from /var/lib/slurm-web/ inside containers. Those paths are fixed; the container command decides where the data is stored on the host.

For production-style run commands, keep the same paths on the host:

Host Container path Purpose

/etc/slurm-web/

/etc/slurm-web/

agent.ini, gateway.ini

/var/lib/slurm-web/

/var/lib/slurm-web/

session.key, jwt.key, slurmrestd.key

Slurm-web containers run as an unprivileged user. With bind mounts, the numeric UID and GID from the host are preserved, so the container process must run with the UID/GID that owns writable files on the host.

Create a slurm-web system user on the host and let the operating system allocate its UID/GID for 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

Then run Slurm-web containers with:

--user $(id -u slurm-web):$(id -g slurm-web)

As an alternative to bind mounts, you can use Docker/Podman named volumes for persistent data. The in-container paths stay the same; only the -v source changes. For example, create a secrets volume:

$ docker volume create slurmweb-secrets

Then replace the secrets bind mount:

-    -v /var/lib/slurm-web:/var/lib/slurm-web \
+    -v slurmweb-secrets:/var/lib/slurm-web \

If you also use a named volume for configuration, create and populate it with agent.ini and gateway.ini, then mount it at /etc/slurm-web/. Copy slurmrestd.key into the secrets volume with a one-shot run before starting the agent.

Deploy

For a complete deployment walkthrough with run commands, see Quickstart with containers.

Pull the images:

$ docker pull ghcr.io/rackslab/slurm-web-agent:latest
$ docker pull ghcr.io/rackslab/slurm-web-gateway:latest

Typical commands:

$ docker run -d --name slurm-web-agent [OPTIONS] ghcr.io/rackslab/slurm-web-agent:latest
$ docker run -d --name slurm-web-gateway [OPTIONS] ghcr.io/rackslab/slurm-web-gateway:latest
$ docker run --rm [OPTIONS] ghcr.io/rackslab/slurm-web-agent:latest connect-check

Docker Compose

The reference mono-cluster Compose stack is defined in containers/compose.yaml in the source repository (agent, gateway, optional Redis and Prometheus).

Download compose.yaml into your working directory:

$ curl -fsSL -o compose.yaml https://raw.githubusercontent.com/rackslab/Slurm-web/main/containers/compose.yaml

Storage layout

The reference stack keeps configuration and secrets next to compose.yaml for a self-contained evaluation:

Host (project dir) Container path Purpose

./conf/

/etc/slurm-web/

agent.ini, gateway.ini, optional Prometheus config

./keys/

/var/lib/slurm-web/

session.key, jwt.key, slurmrestd.key

Create the project layout with:

$ mkdir -p conf keys

With bind mounts, the container process must run with a UID/GID allowed to write in the host ./keys/ directory. The reference Compose file uses LOCAL_UID and LOCAL_GID to set this runtime user, so define these variables with the host owner of ./keys/ (typically your login user) for compose run, compose up and compose restart commands:

$ LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose up -d

You can also replace bind mounts with named volumes. For example, replace the secrets bind mount:

 services:
   agent:
     volumes:
-      - ./keys:/var/lib/slurm-web
+      - slurmweb-keys:/var/lib/slurm-web
   gateway:
     volumes:
-      - ./keys:/var/lib/slurm-web
+      - slurmweb-keys:/var/lib/slurm-web
 volumes:
+  slurmweb-keys:
   prometheus-data:

The compose run commands then write generated secrets into the volume. Copy slurmrestd.key into the volume with a one-shot compose run or run before starting the stack.

Deploy

For a complete deployment walkthrough with the reference stack, see Quickstart with Compose.

Pull the images:

$ docker compose pull

Typical commands:

$ LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose run --rm gateway gen-jwt-key
$ LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose run --rm gateway gen-session-key
$ LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose up -d
$ LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) docker compose run --rm agent connect-check

Environment variables

Optional environment variables for long-running services:

Variable Description

SLURMWEB_BIND

Gunicorn bind address (default 0.0.0.0:5012 for agent, 0.0.0.0:5011 for gateway)

SLURMWEB_WORKERS

Number of Gunicorn worker processes (default 4)
More links