diff --git a/README.md b/README.md index 1001355..1d391cb 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,189 @@ # coman -[![CI](https://github.com/SwissDataScienceCenter/coman/workflows/CI/badge.svg)](https://github.com/SwissDataScienceCenter/coman/actions) +[![Lint and Test](https://github.com/SwissDataScienceCenter/coman/actions/workflows/test.yaml/badge.svg)](https://github.com/SwissDataScienceCenter/coman/actions/workflows/test.yaml) +[![Release](https://github.com/SwissDataScienceCenter/coman/actions/workflows/release.yaml/badge.svg)](https://github.com/SwissDataScienceCenter/coman/actions/workflows/release.yaml) Compute Manager for managing HPC compute + + +## Installation + +### Linux + +```shell +$ 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 + +```shell +$ 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: + +```powershell +# 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](https://developer.svc.cscs.ch) and go to `Applications` +![CSCS Dev Portal](/assets/cscs_app_1.jpg) + +After logging in with your CSCS credentials, pick the `DefaultApplication` +![CSCS Dev Portal](/assets/cscs_app_2.jpg) + +Click on `Production Keys` +![CSCS Dev Portal](/assets/cscs_app_3.jpg) + +Then click on `Generate Keys` at the bottom, without changing any settings. +![CSCS Dev Portal](/assets/cscs_app_4.jpg) + +You should now have a Consumer Key (`Client id` in Coman) and a Consumer Secret (`Client Secret` in Coman) +![CSCS Dev Portal](/assets/cscs_app_5.jpg) + +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 + +```shell +$ coman init +``` + +This creates a `coman.toml` file that you can customize with settings if you wish. + +Select what system you want to run on + +```shell +$ 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 + +```shell +$ 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 + +```shell +$ 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 +```shell +$ coman cscs job get +┌───────────────┬────────────────────────────────────────────────────────┐ +│ 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 + +```shell +$ coman cscs job log +``` + + +### TUI + +To run the TUI, simply run `coman` without any arguments: + +![TUI screenshot](/assets/tui_1.jpg) + +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. diff --git a/assets/cscs_app_1.jpg b/assets/cscs_app_1.jpg new file mode 100644 index 0000000..87d7426 Binary files /dev/null and b/assets/cscs_app_1.jpg differ diff --git a/assets/cscs_app_2.jpg b/assets/cscs_app_2.jpg new file mode 100644 index 0000000..41853eb Binary files /dev/null and b/assets/cscs_app_2.jpg differ diff --git a/assets/cscs_app_3.jpg b/assets/cscs_app_3.jpg new file mode 100644 index 0000000..901be8f Binary files /dev/null and b/assets/cscs_app_3.jpg differ diff --git a/assets/cscs_app_4.jpg b/assets/cscs_app_4.jpg new file mode 100644 index 0000000..4e13d26 Binary files /dev/null and b/assets/cscs_app_4.jpg differ diff --git a/assets/cscs_app_5.jpg b/assets/cscs_app_5.jpg new file mode 100644 index 0000000..7dfaa3b Binary files /dev/null and b/assets/cscs_app_5.jpg differ diff --git a/assets/screenshot.jpg b/assets/screenshot.jpg deleted file mode 100644 index 5619465..0000000 Binary files a/assets/screenshot.jpg and /dev/null differ diff --git a/assets/tui_1.jpg b/assets/tui_1.jpg new file mode 100644 index 0000000..fd257bd Binary files /dev/null and b/assets/tui_1.jpg differ