Metadata-Version: 2.4
Name: foldspace
Version: 1.0.1
Summary: Foldspace enables the scheduling and execution of web services on remote HPC compute nodes, exposing them via SSH tunnels to a local browser. Inspired by Open OnDemand (https://openondemand.org/), it replaces the Apache/Nginx stack with Python scripts and SSH tunnels, allowing any user to run it on any HPC cluster without root privileges. For more details on the client and backend, please check the --help option and visit the official website.
Author-email: Fabio Pitari <f.pitari@cineca.it>, Lucia Rodriguez Muñoz <l.rodriguezmunoz@cineca.it>, Antonio Memmolo <a.memmolo@cineca.it>
Maintainer-email: Fabio Pitari <f.pitari@cineca.it>, Lucia Rodriguez Muñoz <l.rodriguezmunoz@cineca.it>, Antonio Memmolo <a.memmolo@cineca.it>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://gitlab.hpc.cineca.it/interactive_computing/foldspace
Project-URL: Repository, https://gitlab.hpc.cineca.it/interactive_computing/foldspace
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML
Requires-Dist: jinja2
Requires-Dist: rich
Requires-Dist: notify-py
Requires-Dist: paramiko
Requires-Dist: fabric
Requires-Dist: sshtunnel
Requires-Dist: InquirerPy
Requires-Dist: importlib_resources; python_version < "3.10"
Dynamic: license-file

# Foldspace
<div align="center">
   <img src="https://gitlab.hpc.cineca.it/interactive_computing/foldspace/-/raw/08e132fff7f772f8d0636ac6f660d5ca2ebe99cf/pip_package/foldspace/foldspace_logo.png" width="300" height="300">
</div>

Foldspace allows to schedule and run web services on compute nodes of a remote HPC clusters and access them from your local browser. The backend services are mainly (but not necessarily) run via Apptainer/Singularity containers.

The main inspiration for Foldspace is [Open Ondemand](https://openondemand.org/), from which it inherits the main logics as well as part of the codes that it uses on the remote side; Foldspace replaces the Apache + nginx role in Open Ondemand with Python scripts + ssh tunnels, in order to be daemonless. In this way, any user can run backend services (*tools*) from containers in a remote directory (*toolbox*) with no needs of servers running on the HPC cluster (other than sshd).

***

## Install
> 💡**Note:** Foldspace is officially supported on GNU/Linux, MacOS and Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install). Windows Powershell support is still experimental, and BSD systems have not been tested.

You can install the latest Foldspace release in a Python virtual environment[^venv] of your current path using for instance:
```bash
python3 -m venv foldspace_venv # or choose the name you like
source foldspace_venv/bin/activate
pip install --upgrade pip
pip install foldspace
```
If you prefer to use the development version instead, clone the [official repository](#official-repository) and replace `pip install foldspace` with `pip install <pip_package directory path>`[^pipeditable].

## Quick start
A typical general syntax for Foldspace is the following:
```bash
foldspace --user <my username on cluster> --host <url or host in ~/.ssh/config for login nodes> --toolbox <remote path containing the tools> --tool <name of the tool to start> [plus any option for the scheduler submit command]
```
but for some default clusters you can exploit some default settings and ready-to-use toolboxes on the clusters to make this syntax shorter. You can list all the default HPC clusters using the `--list-clusters` option and the avaliable tools remotely with the `--list-tools` option. For instance, to use Foldspace on `<my cluster>` you can run something like this:
```bash
foldspace --user <my username on cluster> --cluster <my cluster> --tool <name of the tool to start> [any sbatch option you like]
```

Please note that using the default clusters might imply to automatically run some script on your local computer to allow the access to the specific cluster[^startup_script] (e.g. to retrieve some ssh certificate needed for the access); if you don't like this behaviour you can skipt this step via the `--no-startup-script` option and perform any preliminary required step manually before using Foldspace.

Here it follows a list of examples to make it clearer; all the examples refers to a generic `<my cluster>` using Slurm as scheduler, containing `jupyter` and `vnc` as tools in the default cluster toolbox:
```bash
# Run Jupyter on `<my cluster>` with default configs (e.g. default partition, default walltime, default account, default resources)
foldspace --user <my user name on my cluster> --cluster <my cluster> --tool jupyter
```
```bash
# Run Jupyter on `<my cluster>` for 3 hours using 4 tasks on `<some partition>` with your account <my account>:
foldspace --user <my user name on my cluster> --cluster <my cluster> --tool jupyter --ntasks 4 --partition <some partition> --account <my account> --time 03:00:00
```
```bash
# Run a VNC remote desktop on `<my cluster>` with default parameters: 
foldspace --user <my user name on my cluster> --cluster <my cluster> --tool vnc
```
```bash
# Run a VNC remote desktop on `<my cluster>` using <some qos> for 30 minutes
foldspace --user <my user name on my cluster> --cluster <my cluster> --tool vnc --qos <some qos> --time 30:00
```
Please check the `--help` option for the full list of options, as well as the documentation of your scheduler[^scheduler] and your cluster for the full set of job submit options.

## Official repository
Foldspace source code is hosted at [this link](https://gitlab.hpc.cineca.it/interactive_computing/foldspace), where you can also find documentation and examples related to the *toolbox* to be hosted remotely.

## Custom toolbox
If you want to build your toolbox with your own tools you can exploit the `--toolbox` option; if coupled with `--cluster` it overwrites the default system value, whereas if you are deploying Foldspace on a different HPC cluster you need to couple it with the `--host` option.

Toolboxes has to be built with a specific structure in order to be compliant with the client package here. Please refer to the original repo for details (see toolboxes/README.md).

## License
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see [here](http://www.gnu.org/licenses/).

## Mantainers
This code is mantained by [HPC department](https://www.hpc.cineca.it/) at [Cineca](https://www.cineca.it/en).

## Authors
[Fabio Pitari](mailto:f.pitari@cineca.it?&subject=Foldspace), [Lucia Rodriguez Muñoz](mailto:l.rodriguezmunoz@cineca.it?&subject=Foldspace), [Antonio Memmolo](mailto:a.memmolo@cineca.it?&subject=Foldspace)

[^venv]: If you are not confident with Python virtual environments you can find a beginner's guide [here](https://realpython.com/python-virtual-environments-a-primer/)
[^pipeditable]: Please avoid the `-e/--editable` option for `pip`, since it is tipically unable to handle package data in setuptools and Foldspace execution would crash
[^startup_script]: You can inspect the scripts content using the `--list-clusters` option
[^scheduler]: For Slurm you can refer to the ["sbatch" command options](https://slurm.schedmd.com/sbatch.html); for PBS you can refer to the ["qsub" command options](https://www.jlab.org/hpc/PBS/qsub.html)
