newbe36524/hpc-console repository overview

⁠HPC Console

HPC Console is a web app for viewing HPC cluster status, monitoring Slurm jobs, reviewing workload history, and browsing account folders. The web app and API run together in one container.

⁠Features

• Cluster Status: view node hardware, partitions, and queue status.
• Task Monitor: inspect pending, running, and recently finished jobs.
• Workload History: review cluster load and job wait-time trends.
• Folders: browse HPC folders and view entry sizes.
• Submit Task: explore the task-submission interface. Submission is currently simulated and does not send jobs to Slurm.

Without an HPC connection, the app uses sample data. With an HPC connection, it reads cluster and job information over SSH using read-only Slurm commands.

⁠Run locally with the Docker Hub image

Install and start Docker, then use the Docker Hub account newbe36524 that publishes the image:

docker run --rm -p 8000:8000 newbe36524/hpc-console:latest

Docker downloads the image if it is not already on your machine. If the repository is private, run docker login first.

Open http://localhost:8000⁠. The image starts in demo mode without HPC credentials. The API documentation is at http://localhost:8000/docs⁠.

⁠Configuration

Settings come from environment variables or from a .env file. Environment variables take precedence over the .env file. A blank value counts as unset. Create your .env from the tracked template:

cp .env.example .env

.env is git-ignored and never copied into the image. .env.example lists every setting with a comment. These are the ones to set first:

Without an HPC connection, docker run starts the console in demo mode with sample data. Compose always connects to the HPC, so it stops before starting when HPC_CONSOLE_HPC_HOST or HPC_CONSOLE_HPC_USER is blank.

⁠Run with Docker Compose

The Compose file in this repository, docker-compose.yml, uses the Compose Specification. It has no top-level version: key, so do not add one. Use Docker Compose v2 (docker compose). The file was checked with Docker Compose v5.6.1.

From the repository root:

cp .env.example .env                    # then set HPC_CONSOLE_HPC_HOST and HPC_CONSOLE_HPC_USER
mkdir -p hpc-cache hpc-history          # create the data folders yourself, so your user owns them
docker compose config --quiet           # check the file and the .env values
docker compose up -d --build

Open http://127.0.0.1:8000⁠, or the port set by HPC_CONSOLE_PUBLISHED_PORT. The container always listens on port 8000 inside. The console serves only after the startup connection check to the HPC passes. Read the logs with docker compose logs -f if it does not start. The service uses restart: unless-stopped, so it starts again after a reboot or a crash, and a stop from docker compose stop is kept.

⁠Data storage

The console keeps one database, a SQLite file, and one cache file. Compose maps both folders from the repository root into the container:

• Both folders are git-ignored and excluded from the image build.
• Compose sets the two HPC_CONSOLE_*_DIR variables, so leave them blank in .env. To store the data elsewhere, change the host side of the volumes entries in docker-compose.yml, and keep the container side.
• Both folders must be writable by HPC_CONSOLE_UID and HPC_CONSOLE_GID. If the history folder is not writable, or Docker creates it as root, the history stays in memory with a warning and is lost on restart.
• A history file recorded for another HPC account or host is not mixed in. The console keeps the history in memory instead, with a warning, and leaves that file unchanged.
• To back up the history, stop the container and copy workload-history.sqlite3. You can also copy it while the container runs with sqlite3 workload-history.sqlite3 ".backup copy.sqlite3". Copy the history file on its own, not the whole cache folder.

⁠Run from source

Requirements: Python 3.12 or newer, Node.js 24 or newer, and npm.

⁠Start the backend

From the repository root:

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
python -m app

The API listens on http://127.0.0.1:8000.

⁠Start the frontend

In a second terminal, from the repository root:

cd frontend
npm ci
npm run dev

Open http://localhost:5173⁠. Vite forwards API requests to the backend on port 8000. Interactive API documentation is available at http://127.0.0.1:8000/docs⁠.

Both services use simulated data by default. To connect the backend to Slurm, create backend/.env with HPC_CONSOLE_HPC_HOST, HPC_CONSOLE_HPC_USER, and HPC_CONSOLE_HPC_KEY_PATH. Set all three together and provide a trusted host key with HPC_CONSOLE_HPC_KNOWN_HOSTS_PATH if it is not in the system known-hosts files. The key must be unencrypted. The backend checks the SSH connection at startup.