#23: Karabo GUI Installation on Various Platforms
=================================================

Did you know that the Karabo GUI can be installed not only in Linux PCs,
as those found in the control rooms, but also in Windows and Mac OS PCs?
This is possible with ``conda``, a cross-platform package and environment system.

One of the benefits of installing Karabo GUI on an own machine rather than
using a remote desktop software is the usage of the native user interface.
The user interaction will be smoother for most of the cases as it will not be
channelled through an internet connection. Only data needed to interact with the
control system will be channelled through the internet connection. Files from the
GUI will also be stored locally. For instance, saving an image widget snapshot will
be done on the local machine and not on the remote machine, thus one now avoid
retrieving this file via a remote transfer.


Installation Instructions
*************************

The installation consists of majorly three steps:

1. Downloading ``miniconda``.
2. Setting up a ``conda`` environment and configuring a couple of ``conda`` settings
3. Install karabogui from the created environment.

The detailed instructions can be found here:

https://rtd.xfel.eu/docs/karabo/en/latest/installation/gui.html

Afterwards, the GUI can now be run with the following commands on the terminal
(**Anaconda Prompt** on Windows or **Bash** on Linux or MacOS):

.. code-block:: bash

    conda activate <name of the Karabo environment>
    karabo-gui


Connecting to the GUI servers outside of DESY Network
*****************************************************

At these time that users are mostly working off-site and are not connected to
the DESY network, establishing a connection to GUI servers that are only
accessible inside of the network can seem daunting. Such connection can be
achieved by the following instructions:

**Windows:** SSH connections in Windows can be established by using an external
tool (``PuTTy``). The instruction can be found here:

https://rtd.xfel.eu/docs/karabo/en/latest/installation/windows.html

Alternatively, one can enable running SSH commands in Windows 10 from the OpenSSH
instructions at https://docs.microsoft.com/en-us/windows/terminal/tutorials/ssh.
Afterwards, the following steps below can be done instead.

**Linux/MacOS:**

*(These steps can also be done in Windows 10 with an enabled OpenSSH.)*

1. Run the following command in the terminal to establish the SSH connection to
the desired GUI server (for instance, ``SA1``):

.. code-block:: bash

   ssh -L 38080:localhost:38081 <desyusername>@bastion.desy.de -t ssh -L 38081:sa1-br-sys-con-gui1:44444 exflgateway

Note that ``38080`` and ``38081`` are arbitrary port numbers, so feel free to use an unused port
between ``1024-49151``.


2. Use the assigned port (in this case, ``38080``) in the Karabo GUI.

.. figure:: images/gui_login.png
   :align: center
   :alt: Using the port ``38080`` to connect to ``SA1``
   :figclass: align-center

   Using the port ``38080`` to connect to ``SA1``

-----

Our aim is to continuously make the Karabo GUI more accessible.
Social distancing practices have forced colleagues to work on laptops
and home computers with diverse operating systems. The installation
through the ``conda`` packaging system enables the Karabo GUI installation
on Windows, MacOSX (from 2.9.0) and multiple Linux OSs using the x86_64
architecture. Your feedback is greatly appreciated! Please send your feedback
to controls-integration@xfel.eu.