Skip to content

README.md

Latest commit

 

History

History
189 lines (146 loc) · 10.9 KB

README.md

File metadata and controls

189 lines (146 loc) · 10.9 KB

coman

Lint and Test Release

Compute Manager for managing HPC compute

Installation

Linux

$ curl -LO https://github.com/SwissDataScienceCenter/coman/releases/latest/download/coman-Linux-x86_64-musl.tar.gz
# tar -xzf coman-Linux-x86_64-musl.tar.gz -C /usr/local/bin/
# chmod +x /usr/local/bin/coman

Macos

$ curl -LO https://github.com/SwissDataScienceCenter/coman/releases/latest/download/coman-Darwin-x86_64.tar.gz
# tar -xzf coman-Darwin-x86_64.tar.gz -C /usr/local/bin/
# chmod +x /usr/local/bin/coman

Windows

Run as Admin:

# Download the ZIP file
Invoke-WebRequest -Uri "https://github.com/SwissDataScienceCenter/coman/releases/latest/download/coman-Windows-aarch64.zip" -OutFile "coman-Windows-aarch64.zip"

# Extract the ZIP file
Expand-Archive -Path "coman-Windows-aarch64.zip" -DestinationPath ".\coman_temp" -Force

# Move the binary to C:\Program Files\coman
New-Item -ItemType Directory -Path "C:\Program Files\coman" -Force
Move-Item -Path ".\coman_temp\coman.exe" -Destination "C:\Program Files\coman\coman.exe" -Force

# Permanent PATH addition (requires Administrator privileges)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Program Files\coman", "Machine")

# Clean up temporary files
Remove-Item -Path "coman-Windows-aarch64.zip" -Force
Remove-Item -Path ".\coman_temp" -Recurse -Force

Usage

Coman can be used in two ways, one is as a normal CLI tool the other is as an interactive terminal UI (TUI).

Logging in

To use Coman, you need to log in to CSCS.

For this you need go to the CSCS Developer portal and go to Applications CSCS Dev Portal

After logging in with your CSCS credentials, pick the DefaultApplication CSCS Dev Portal

Click on Production Keys CSCS Dev Portal

Then click on Generate Keys at the bottom, without changing any settings. CSCS Dev Portal

You should now have a Consumer Key (Client id in Coman) and a Consumer Secret (Client Secret in Coman) CSCS Dev Portal

Run coman cscs login and provide the Client id and Client secret when prompted. Both are securely stored in your operating systems secure storage and don't need to be entered again. You also don't need to repeat this step unless your keys change.

CLI

To create a Coman config for a project/folder, run

$ coman init <folder>

This creates a coman.toml file that you can customize with settings if you wish.

Select what system you want to run on

$ coman cscs system ls # this lists systems you can see.
┌───────┬────────────────────────────┐
│ name  │ services_health            │
├───────┼────────────────────────────┤
│ eiger │ ╔══════════════╦═════════╗ │
│       │ ║ service_type ║ healthy ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Scheduler    ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Ssh          ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╚══════════════╩═════════╝ │
├───────┼────────────────────────────┤
│ daint │ ╔══════════════╦═════════╗ │
│       │ ║ service_type ║ healthy ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Scheduler    ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Ssh          ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╠══════════════╬═════════╣ │
│       │ ║ Filesystem   ║ true    ║ │
│       │ ╚══════════════╩═════════╝ │
└───────┴────────────────────────────┘
$ coman cscs system set daint

To execute a job on CSCS, run a command like

$ coman cscs job submit -i ubuntu:latest -- echo test

This will run the command echo test using the ubuntu:latest docker image and default settings. See coman cscs job submit -h for more options.

You can list your jobs using

$ coman cscs job list
┌─────────┬────────────────┬──────────┬──────────┬────────────────────────────┬────────────────────────────┐
│ id      │ name           │ status   │ user     │ start_date                 │ end_date                   │
├─────────┼────────────────┼──────────┼──────────┼────────────────────────────┼────────────────────────────┤
│ 2104427 │ job-name       │ Finished │ user     │ 2025-11-19 12:13:26 +01:00 │ 2025-11-19 12:13:55 +01:00 │
└─────────┴────────────────┴──────────┴──────────┴────────────────────────────┴────────────────────────────┘

Get details for a job with

$ coman cscs job get <id>
┌───────────────┬────────────────────────────────────────────────────────┐
│ Id            │ 2127021                                                │
├───────────────┼────────────────────────────────────────────────────────┤
│ Name          │ job-name                                               │
├───────────────┼────────────────────────────────────────────────────────┤
│ Start Date    │ 2025-11-24 10:15:50 +01:00                             │
├───────────────┼────────────────────────────────────────────────────────┤
│ End Date      │ 2025-11-24 10:17:32 +01:00                             │
├───────────────┼────────────────────────────────────────────────────────┤
│ Status        │ Finished                                               │
├───────────────┼────────────────────────────────────────────────────────┤
│ Status Reason │ None                                                   │
├───────────────┼────────────────────────────────────────────────────────┤
│ Exit Code     │ 0                                                      │
├───────────────┼────────────────────────────────────────────────────────┤
│ stdin         │ /dev/null                                              │
├───────────────┼────────────────────────────────────────────────────────┤
│ stdout        │ /capstor/scratch/cscs/rgrubenm/coman/slurm-2127021.out │
├───────────────┼────────────────────────────────────────────────────────┤
│ stderr        │                                                        │
└───────────────┴────────────────────────────────────────────────────────┘

Get the logs from a job

$ coman cscs job log <id>

TUI

To run the TUI, simply run coman without any arguments:

TUI screenshot

The TUI should be pretty self-explanatory. It gives an overview of your jobs on the selected system, refreshed every couple of seconds, lets you see the logs and all the other functionality of the CLI, just in an interactive way.