.. _`local-vnc-viewer`:

################
Local VNC Viewer
################

- This guide provides a step-by-step instructions on how you can connect to RIS compute serivces through local PC/Laptop through GUI.
- This guide details step-by-step instructions on connecting to RIS compute services via VNC GUI through a local Linux/MacOS computer. Windows platform is currently not supported.

.. contents::
   :depth: 2
   :local:

==============
Pre-requisites
==============

Connecting to WashU Network
~~~~~~~~~~~~~~~~~~~~~~~~~~~

- If you are off campus, you will need to use a VPN to access compute1.
- Instructions for accessing the WashU VPNs can be found `here. <https://it.wustl.edu/items/connect/>`_
- If you run into issues using the VPN, you will need to follow the directions in the previous link to contact WashU IT proper.

Compute/Storage Allocation
~~~~~~~~~~~~~~~~~~~~~~~~~~

- User must have a compute/storage allocation.
- If you do not have one, You can request `here. <https://washu.atlassian.net/servicedesk/customer/portal/2/group/6/create/53>`_.

Install TurboVNC Viewer
~~~~~~~~~~~~~~~~~~~~~~~

- Install `TurboVNC Viewer <https://www.turbovnc.org/>`_ on the local computer
- On MacOS, run:

.. code::

    brew install --cask turbovnc-viewer

- Validate that installation is successful. There should be an application under Finder -> Applications.
- Install `expect <https://formulae.brew.sh/formula/expect>`_, on local computer run:

.. code::

    brew install expect

- Validate that installation is successful.; run:

.. code::

    which expect
    /usr/bin/expect ## output

- (Optional) Add vncviewer in the PATH variable, Open Terminal then run:

.. code::

    echo 'export PATH="/opt/TurboVNC/bin:$PATH"' >> ~/.zshrc

    source ~/.zshrc


Add SSH Private-Public Key Pair
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- If you do not have SSH private-public key pair already setup. Please refer our guide `here <https://docs.ris.wustl.edu/doc/compute/recipes/ssh-keypair.html>`_

========================
Connecting through NoVNC
========================

- User should be either connected to campus network or WUSTL VPN.
- Download  `LaunchDesktop.zip <https://wustl.box.com/s/8w6303e08bdv6ff4b8jz0n2h0u6oxtno>`_ to a desired location, preferably, on the Desktop. (note: WUSTL login required)
- Unzip LaunchDesktop.zip or just double-click on the zip file.
- This will output an executable file **LaunchDesktop**.

.. image:: ../images/novnc-launch-remote-desktop.png

- Now open the **LaunchDesktop** file with any text editor and enter your wustl key in the first line as below example:

.. code::

    # Set a WUSTL key
    set WUSTLKEY "WUSTL_KEY"

-  Double-click the executable. It will open a terminal session, connect to RIS platform, submits a job and output a command to connect VNC viewer. (Refer example screenshot below)

.. image:: ../images/novnc-successful-login.png

- Now, copy the command that starts with **/opt/TurboVNC/...** in another instance of terminal and run it.

.. image:: ../images/novnc-start-vnc-viewer.png

- You shall be able to now access desktop GUI on the compute node.

.. image:: ../images/novnc-final-desktop.png

.. admonition:: Compute Resources

    - See the `RIS Service Desk <https://jira.ris.wustl.edu/servicedesk/customer/portal/1/group/22>`_ for additional assistance.