Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
Altan Orhon committed Sep 7, 2023
1 parent 094e44b commit b08885c
Showing 1 changed file with 42 additions and 46 deletions.
88 changes: 42 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
hyakvnc
=======
# hyakvnc

Create and manage VNC Slurm jobs on UW HYAK Klone cluster.

Expand All @@ -15,14 +14,14 @@ time.
### Prerequisites

Before running `hyakvnc`, you'll need the following:

- SSH client
- VNC client/viewer
- TigerVNC viewer is recommended for all platforms
- TigerVNC viewer is recommended for all platforms
- HYAK Klone access with compute resources
- VNC Apptainer with TigerVNC server and a desktop environment
- Install additional tools and libraries to the container as required by
programs running within the VNC session.
- xstartup script used to launch a desktop environment
- Install additional tools and libraries to the container as required by programs running within the VNC session.
- `xstartup` script used to launch a desktop environment
- A Python interpreter (version **3.9** or higher)

### Building
Expand All @@ -32,13 +31,14 @@ Before running `hyakvnc`, you'll need the following:
```bash
python3 -V
```

As of 2021-09-30, the default Python 3 interpreter on Klone is version 3.6.8. Because `hyakvnc` requires version 3.9 or higher, it is necessary to specify the path to a Python 3.9 or newer interpreter when installing `hyakvnc`. You can list the Python 3 interpreters you have available with:

```bash
compgen -c | grep '^python3\.[[:digit:]]$'
```

At this time, `klone` supports Python 3.9, which can be run with the command `python3.9`. The following instructions are written with `python3.9` in mind. If you use another version, such as `python3.11`, you will need to substitute `python3.9` with, e.g., `python3.11` in the instructions.
At this time, Klone supports Python 3.9, which can be run with the command `python3.9`. The following instructions are written with `python3.9` in mind. If you use another version, such as `python3.11`, you will need to substitute `python3.9` with, e.g., `python3.11` in the instructions.

```bash
python3.9 -m pip install --upgrade --user pip
Expand All @@ -61,7 +61,7 @@ If successful, then `hyakvnc` should be installed to `~/.local/bin/`.

#### Optional dependencies for development

The optional dependency group`[dev]` in `pyroject.toml` includes dependencies useful for development, including [pre-commit](https://pre-commit.com/) hooks that run in order to commit to the `git` repository.
The optional dependency group `[dev]` in `pyroject.toml` includes dependencies useful for development, including [pre-commit](https://pre-commit.com/) hooks that run in order to commit to the `git` repository.
These apply various checks, including running the `black` code formatter before the commit takes place.

To ensure `pre-commit` and other development packages are installed, run:
Expand All @@ -76,57 +76,53 @@ python3.9 -m pip install --user '.[dev]'

### Creating a VNC session

1. Start a VNC session with the `hyakvnc create` command followed by arguments
to specify the Slurm account and partition, compute resource needs,
reservation time, and paths to a VNC apptainer and xstartup script.
1. Start a VNC session with the `hyakvnc create` command followed by arguments to specify the Slurm account and partition, compute resource needs, reservation time, and paths to a VNC apptainer and xstartup script.

```bash
# example: Starting VNC session on `ece` compute resources for 5 hours on a
# node with 16 cores and 32GB of memory
hyakvnc create -A ece -p compute-hugemem \
-t 5 -c 16 --mem 32G \
--container /path/to/container.sif \
--xstartup /path/to/xstartup
```
```bash
# example: Starting VNC session on `ece` compute resources for 5 hours on a
# node with 16 cores and 32GB of memory
hyakvnc create -A ece -p compute-hugemem \
-t 5 -c 16 --mem 32G \
--container /path/to/container.sif \
--xstartup /path/to/xstartup
```

2. If successful, `hyakvnc` should print a unique port forward command:

```
...
=====================
Run the following in a new terminal window:
ssh -N -f -L AAAA:127.0.0.1:BBBB [email protected]
then connect to VNC session at localhost:AAAA
=====================
```
```text
...
=====================
Run the following in a new terminal window:
ssh -N -f -L AAAA:127.0.0.1:BBBB [email protected]
then connect to VNC session at localhost:AAAA
=====================
```

Copy this port forward command for the following step.
Copy this port forward command for the following step.

3. Set up port forward between your computer and HYAK login node. On your
machine, in a new terminal window, run the the copied command.
3. Set up port forward between your computer and HYAK login node. On your machine, in a new terminal window, run the the copied command.

Following the example, run:
Following the example, run:

```bash
ssh -N -f -L AAAA:127.0.0.1:BBBB [email protected]
```
```bash
ssh -N -f -L AAAA:127.0.0.1:BBBB [email protected]
```

Alternatively, for PuTTY users, navigate to
PuTTY Configuration->Connection->SSH->Tunnels, then set:
- source port to `AAAA`
- destination to `127.0.0.1:BBBB`
Alternatively, for PuTTY users, navigate to `PuTTY Configuration->Connection->SSH->Tunnels`, then set:
- source port to `AAAA`
- destination to `127.0.0.1:BBBB`

Press `Add`, then connect to Klone as normal. Keep this window open as it
maintains a connection to the VNC session running on Klone.
Press `Add`, then connect to Klone as normal. Keep this window open as it
maintains a connection to the VNC session running on Klone.

4. Connect to the VNC session at instructed address (in this example:
`localhost:AAAA`)

5. To close the VNC session, run the following

```bash
hyakvnc kill-all
```
```bash
hyakvnc kill-all
```

### Checking active VNC sessions

Expand Down Expand Up @@ -159,7 +155,7 @@ re-established with new port mappings via the `hyakvnc repair` command.

Before repairing:

```
```text
Active hyakvnc jobs:
Job ID: NNNNNNNN
SubNode: n3050
Expand All @@ -169,7 +165,7 @@ Active hyakvnc jobs:

After repairing port forwarding:

```
```text
Active hyakvnc jobs:
Job ID: NNNNNNNN
SubNode: n3050
Expand All @@ -186,7 +182,7 @@ which may require the user to set up new port forward(s).

### Override Apptainer bind paths

If present, `hyakvnc` will use `APPTAINER_BINDPATH` or `SINGULARITY_BINDPATH` to
If present, `hyakvnc` will use the [environment variables](https://tldp.org/LDP/Bash-Beginners-Guide/html/sect_03_02.html) `APPTAINER_BINDPATH` or `SINGULARITY_BINDPATH` to
determine how paths are mounted in the VNC container environment. If neither is
defined, `hyakvnc` will use its default bindpath.

Expand Down

0 comments on commit b08885c

Please sign in to comment.