From 9b30b2f072eb4cbbde6b2c259b470093bb34041a Mon Sep 17 00:00:00 2001 From: Altan Orhon Date: Thu, 7 Sep 2023 15:23:38 -0700 Subject: [PATCH] Update README --- README.md | 77 +++++++++---------------------------------------------- 1 file changed, 12 insertions(+), 65 deletions(-) diff --git a/README.md b/README.md index 97a39ed..5bd66f9 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,9 @@ Create and manage VNC Slurm jobs on UW HYAK Klone cluster. -`hyakvnc` allocates resources then starts a VNC session within an Apptainer -environment. +`hyakvnc` allocates resources then starts a VNC session within an Apptainer environment. -Disclaimer: VNC sessions are time-limited and will expire with all processes -closed. Save often if you can or reserve a session for a generous length of -time. +Disclaimer: VNC sessions are time-limited and will expire with all processes closed. Save often if you can or reserve a session for a generous length of time. ## Get started @@ -15,16 +12,12 @@ time. 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) @@ -36,14 +29,12 @@ Before running `hyakvnc`, you'll need the following: 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 @@ -67,8 +58,7 @@ If successful, then `hyakvnc` should be installed to `~/.local/bin/`. #### Optional dependencies for development -The optional dependency group `[dev]` in `pyproject.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. +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: @@ -82,7 +72,6 @@ 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 @@ -93,14 +82,6 @@ python3.9 -m pip install --user '.[dev]' --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: @@ -112,42 +93,22 @@ python3.9 -m pip install --user '.[dev]' 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 hansem7@klone.hyak.uw.edu - 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. + 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. +3. Set up port forward between your computer and HYAK login node. On your machine, in a new terminal window, run the copied command. Following the example, run: - Following the example, run: ```bash ssh -N -f -L AAAA:127.0.0.1:BBBB hansem7@klone.hyak.uw.edu ``` - ```bash - ssh -N -f -L AAAA:127.0.0.1:BBBB hansem7@klone.hyak.uw.edu - ``` - 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. + 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`) @@ -157,14 +118,10 @@ python3.9 -m pip install --user '.[dev]' ```bash hyakvnc kill-all ``` - ```bash - hyakvnc kill-all - ``` ### Checking active VNC sessions -Print details of active VNC sessions (with the same job name) with the -`hyakvnc status` command. +Print details of active VNC sessions (with the same job name) with the `hyakvnc status` command. ### Closing active VNC session(s) @@ -174,25 +131,20 @@ To kill all VNC jobs (with the same job name), run `hyakvnc kill-all`. ### Resetting VNC password -To reset your VNC password, use the `hyakvnc set-passwd` with a VNC container -specified: +To reset your VNC password, use the `hyakvnc set-passwd` with a VNC container specified: ```bash hyakvnc set-passwd --container /path/to/container.sif ``` -This should run `vncpasswd` in the container to prompt the user to set a new -password. +This should run `vncpasswd` in the container to prompt the user to set a new password. ### Re-connecting to VNC session after Login Node reboot -In rare circumstances, when the login node reboots, `hyakvnc status` lists VNC -jobs with an inactive VNC signal. In this case, new connections can be -re-established with new port mappings via the `hyakvnc repair` command. +In rare circumstances, when the login node reboots, `hyakvnc status` lists VNC jobs with an inactive VNC signal. In this case, new connections can be re-established with new port mappings via the `hyakvnc repair` command. Before repairing: -```text ```text Active hyakvnc jobs: Job ID: NNNNNNNN @@ -203,7 +155,6 @@ Active hyakvnc jobs: After repairing port forwarding: -```text ```text Active hyakvnc jobs: Job ID: NNNNNNNN @@ -216,15 +167,11 @@ Active hyakvnc jobs: Run command: ssh -N -f -L 5908:127.0.0.1:5908 hansem7@klone.hyak.uw.edu ``` -Note that `hyakvnc repair` does not attempt to restore the same port mappings, -which may require the user to set up new port forward(s). +Note that `hyakvnc repair` does not attempt to restore the same port mappings, which may require the user to set up new port forward(s). ### Override Apptainer bind paths -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 -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. +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. ## License