From 3d1ecd3caf6d4e09ff05153e809f89290cf26226 Mon Sep 17 00:00:00 2001 From: Sighvatur Sveinn Davidsson Date: Wed, 27 Mar 2024 12:39:22 +0100 Subject: [PATCH] Several interface updates to application pages --- .../img}/gui/port-forwarding-example.png | Bin .../img}/gui/x-window-example.png | Bin .../application_guides/about_applications.md | 106 +++++++++++++++++- docs/guides/application_guides/gui/gui.md | 95 ---------------- .../application_guides/jupyter/jupyter.md | 6 +- .../application_guides/matlab/matlab.md | 5 +- mkdocs.yml | 1 - 7 files changed, 108 insertions(+), 105 deletions(-) rename docs/{guides/application_guides => assets/img}/gui/port-forwarding-example.png (100%) rename docs/{guides/application_guides => assets/img}/gui/x-window-example.png (100%) delete mode 100644 docs/guides/application_guides/gui/gui.md diff --git a/docs/guides/application_guides/gui/port-forwarding-example.png b/docs/assets/img/gui/port-forwarding-example.png similarity index 100% rename from docs/guides/application_guides/gui/port-forwarding-example.png rename to docs/assets/img/gui/port-forwarding-example.png diff --git a/docs/guides/application_guides/gui/x-window-example.png b/docs/assets/img/gui/x-window-example.png similarity index 100% rename from docs/guides/application_guides/gui/x-window-example.png rename to docs/assets/img/gui/x-window-example.png diff --git a/docs/guides/application_guides/about_applications.md b/docs/guides/application_guides/about_applications.md index ba89339..b092180 100644 --- a/docs/guides/application_guides/about_applications.md +++ b/docs/guides/application_guides/about_applications.md @@ -1,9 +1,105 @@ -# About applications on Strato +# Strato Applications -All Strato instances are essentially Linux computers with [headless interfaces](https://en.wikipedia.org/wiki/Headless_computer), and they can run virtually any Linux application that exists. This will be a new experience for many users who are not familiar with operating a computer from the command line, and they may wish to install graphical user interfaces, to get a more familiar desktop computer experience. This is possible, but not necessarily a good idea (read our section on [Graphical User Interfaces](https://www.strato-docs.claaudia.aau.dk/guides/application_guides/gui.md)). +## Command Line Interfaces +All Strato instances are essentially Linux computers with [headless interfaces](https://en.wikipedia.org/wiki/Headless_computer). They are in many ways very similar to regular desktop computers as they have a file system, network and computing capability, and they can run virtually any application - provided it can run on Linux. This is the most efficient way of distributing computing ressources and should be sufficient in most cases. -We therefore encourage our users to learn a few of the basic Linux commands - an good and concise overview of the most imporant ones can be found at [linuxjourney.com](https://linuxjourney.com/lesson/the-shell). If you work with computing or data analysis by any stretch, this skill will likely be useful for you in the future. +For many users, operating a computer from the command line will be a new experience. At first they may not know what to do with it. and they may be tempted to install applications, that more or less turn their instance into a remote desktop. Although this may be possible, it might not necessarily be a good idea. Installing desktop capabilities will require a large number additional libraries to be installed, whereby critical system libraries are replaced, leaving you with a very non-standard instance that may be prone to errors, is difficult to troubleshoot and potentially has security risks. -Users should also know that a great number of applications can be accessed instantly via [DeiC Interactive HPC](https://cloud.sdu.dk/). They require no installation and rely much more on GUI interactions. +!!! Tip + A great way to learn how to use the Linux shell is to look at [linuxjourney.com](https://linuxjourney.com/lesson/the-shell) -Further many users could also benefit from reading about our other computing services at [our website](https://www.researcher.aau.dk/guides/research-data/high-performance-computing). + +## Graphical User Interfaces + +In some cases however, you might need a graphical user interface (also known as a [GUI](https://en.wikipedia.org/wiki/Graphical_user_interface)) to do the work you need. These could be situations where your software does not have a headless interface or where it simply does not make sense to have one. + +In the following we will suggest a few simple solutions for working with GUI applications on Strato. + +!!! Tip + If you find that the prospect of learning to navigate the command line will be too difficult, you may consider one of our other HPC options: + + - A more suitable alternative could be [DeiC Interactive HPC (also known as UCloud)](https://cloud.sdu.dk/app/login), which as the name indicates is built for GUI-reliant interactive HPC operations. + - Read about our other computing services at our website: [researcher.aau.dk](https://www.researcher.aau.dk/guides/research-data/high-performance-computing). + +### Port forwarding + +**This is likely the prefereable choice for most users.** + +Many applications have dedicated server versions that can be run on a remote server and accessed through a web browser on your local computer. + +Before you go ahead and run the application, you should consider two things: + +1. Find out what port is being used to expose the application. This configuration will vary frome one application to another, but in many cases you will find that certain applications use a default port. You should be able to find this in the documentation for the application. In many cases you should also be able to specify a different port, should the default port conflict with one that's being used. + +2. Establish port forwarding between the Strato instance and your local computer. We do this by adding an additional parameter to our SSH command: `-L :localhost:`. Assuming that the port in question is `8888` the full command would be: +``` +ssh -i ~/.ssh/ -L 8888:localhost:8888 ubuntu@10.92.x.xxx +``` + +Now you should be able to run your application in a web browser! + +!!! Example + We use Jupyter Notebook as an example. + + Assuming that we logged in with the `-L` parameter added to our ssh command and installed Jupyter, we can launch it with + ``` + jupyter notebook + ``` + + Now find a web browser on your local computer. In Jupyter's case a URL will be outputted after executing the application. Normally it would be sufficient to go to: + ``` + localhost:8888 + ``` + + You should now have a fully functional Jupyter Notebook environment from within your browser! + + ![Port forwarding example](../../assets/img/gui/port-forwarding-example.png) + +### X11 forwarding + +This approach can be good for rendering less demanding applications, plots, images, etc. In most cases rendering complete desktop software will simply be to heavy, and you will experience a considerable amount of lag. + +X11 is an display server technology commonly used in Linux, and is not always supported out of the box on other operating systems. Setup will therefore depend on your operating system. In recent years there have been advances with regards to support for X11 Forwarding, and the required setup of your system has become relatively easy. + +=== "Windows" + * Ensure that you are using an appropriate terminal emulator. We recomend using Powershell. Both Powershell and OpenSSH come preinstalled with all currently supported versions of Windows. + * Ensure that your version of OpenSSH is greater than `8.1p1`. Check the version with: + ``` + PS C:\ ssh -V + OpenSSH_for_Windows_8.1p1, LibreSSL 3.0.2 + ``` + If your version that is lower than 8.1p1 your version is supported. If your version is lower, you should consider updating your system. + +=== "macOS" + * Ensure that you have Xquartz installed on your system. If this is not the case it can be downloaded from the official [XQuartz webpage](https://xquartz.org). + +=== "Linux desktops" + * Check which display server you are running on your local computer. Open a terminal application and run the command: + ``` + echo $XDG_SESSION_TYPE + ``` + * If this outputs `X11`, you need not do anything. + * If this outputs `wayland`, you might want to install [Waypie]("https://gitlab.freedesktop.org/mstoeckl/waypipe") or consider switching to X11 temporarily. + +Now you should be ready to use the feature. We do this by verifying by adding `-X` to our initial ssh command: + +``` +ssh -i ~/.ssh/ -X ubuntu@10.92.x.xxx +``` +If you did not log in to the instance with the `-X` flag, simply log out and log back in. + +This will create a file in the home diretory of your Strato instance called `.Xauthority`. You can use `ls -al $HOME` to view the files in your user directory. If you find one, and the last modified date column corresponds to the time you logged in to the server, you can assume that everything went well. + +!!! Example + Now that you have logged in to your instance with `ssh -X` image windows will now get rendered on your computer. + + Assuming that I have the following R code + ``` + x <- rnorm(100) + y <- rnorm(100) + plot(x, y) + ``` + + As soon as the `plot(x, y)` is run, this window will open: + + ![X Window example](../../assets/img/gui/x-window-example.png) diff --git a/docs/guides/application_guides/gui/gui.md b/docs/guides/application_guides/gui/gui.md deleted file mode 100644 index 87f13be..0000000 --- a/docs/guides/application_guides/gui/gui.md +++ /dev/null @@ -1,95 +0,0 @@ -# Graphical User Interfaces - -Strato instances are most often operated as [headless interfaces](https://en.wikipedia.org/wiki/Headless_computer). This is the most efficient way of distributing computing ressources and should be sufficient in most cases. -In some cases however, you might need a graphical user interface (also known as a [GUI](https://en.wikipedia.org/wiki/Graphical_user_interface)) to do the work you need. -These could be situations where your software does not have a headless interface or where it simply does not make sense to have one. - -There are several ways of achieving this. In the following we will suggest a few simple solutions. -Please note that it is not recommended to experiment with installing complete [desktop environments](https://en.wikipedia.org/wiki/Desktop_environment) directly on to your instance. Doing this will require large number of additional libraries to be installed, whereby critical system libraries will be replaced, leaving you with a very non-standard instance that is prone to errors and security risks, and will be difficult to troubleshoot. - -## Port forwarding - -**This should be the prefereable choice for most users.** -Many applications have dedicated server versions that can be run on a remote server and accessed through a web browser on your local computer. - -### Setup -Before you go ahead and run the application, you should consider two things: - -1. Find out what port is being used to expose the application. This configuration will vary frome one application to another, but in many cases you will find that certain applications use a default port. You should be able to find this in the documentation for the application. In many cases you should also be able to specify a different port, should the default port conflict with one that's being used. - -2. Establish port forwarding between the Strato instance and your local computer. We do this by adding an additional parameter to our SSH command: `-L :localhost:`. Assuming that the port in question is `8888` the full command would be: -``` -ssh -i ~/.ssh/ -L 8888:localhost:8888 ubuntu@10.92.x.xxx -``` - -### Example - -We use Jupyter Notebook as an example. - -Assuming that we logged in with the necessary `-L` parameter and installed Jupyter, we can launch it with -``` -jupyter notebook -``` - -Now find a web browser on your local computer. In Jupyter's case a URL will be outputted after executing the application. Normally it would be sufficient to go to: -``` -localhost:8888 -``` - -You should now have a fully functional Jupyter Notebook environment from within your browser! - -![Port forwarding example](port-forwarding-example.png) - - -## X11 forwarding - -This approach can be good for rendering less demanding applications, plots, images, etc. In most cases rendering complete desktop software will simply be to heavy, and you will experience a considerable amount of lag. - -### Setup -X11 is an display server technology commonly used in Linux, and is not always supported out of the box on other operating systems. Setup will therefore depend on your operating system. -In recent years there have been advances with regards to support for X11 Forwarding, and the required setup of your system has become relatively easy. - -* Windows - * Ensure that you are using an appropriate terminal emulator. We recomend using Powershell. Both Powershell and OpenSSH come preinstalled with all currently supported versions of Windows. - * Ensure that your version of OpenSSH is greater than `8.1p1`. Check the version with: - ``` - PS C:\ ssh -V - OpenSSH_for_Windows_8.1p1, LibreSSL 3.0.2 - ``` - If your version that is lower than 8.1p1 your version is supported. If your version is lower, you should consider updating your system. - -* macOS - * Ensure that you have Xquartz installed on your system. If this is not the case it can be downloaded from the official [XQuartz webpage](https://xquartz.org). - -* Linux desktops - * Check which display server you are running on your local computer. Open a terminal application and run the command: - ``` - echo $XDG_SESSION_TYPE - ``` - * If this outputs `X11`, you need not do anything. - * If this outputs `wayland`, you might want to install [Waypie]("https://gitlab.freedesktop.org/mstoeckl/waypipe") or consider switching to X11 temporarily. - -Now you should be ready to use the feature. We do this by verifying by adding `-X` to our initial ssh command: - -``` -ssh -i ~/.ssh/ -X ubuntu@10.92.x.xxx -``` -If you did not log in to the instance with the `-X` flag, simply log out and log back in. - -This will create a file in the home diretory of your Strato instance caled `.Xauthority`. You can use `ls -a $HOME` to verify this. - -### Example - -Now that you have logged in to your instance with `ssh -X` image windows will now get rendered on your computer. - -Assuming that I have the following R code -``` -x <- rnorm(100) -y <- rnorm(100) -plot(x, y) -``` - -As soon as the `plot(x, y)` is run, this window will open: - -![X Window example](x-window-example.png) - diff --git a/docs/guides/application_guides/jupyter/jupyter.md b/docs/guides/application_guides/jupyter/jupyter.md index 861ede8..80ae674 100644 --- a/docs/guides/application_guides/jupyter/jupyter.md +++ b/docs/guides/application_guides/jupyter/jupyter.md @@ -2,7 +2,8 @@ In the following we will be guiding you throught the process of setting up Jupyter Notebooks on a Strato Instance. -Jupyter Notebookes are also available on [DeiC Interactive HPC]("https://cloud.sdu.dk/") (also known as UCloud). This requires no setup and ships with a GUI out of the box. Read more about this possibility in [the official platform documentation]("https://docs.cloud.sdu.dk/Apps/jupyter-lab.html"). +!!! Tip + Jupyter Notebookes are also available on [DeiC Interactive HPC]("https://cloud.sdu.dk/") (also known as UCloud). This requires no setup and ships with a GUI out of the box. Read more about this possibility in [the official platform documentation]("https://docs.cloud.sdu.dk/Apps/jupyter-lab.html"). ## Installing Jupyter @@ -12,7 +13,8 @@ Jupyter can be installed either using Pip or Conda (also known as Anaconda). You We recommend following the official installation instructions for installing [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/#quick-command-line-install) (a lightweight Conda distribution). -It's also possible to launch an instance that has Miniconda preinstalled. You can find this image in the list of source images (look for *Miniconda Ubuntu 22.04*) - refer back to the section [Launch Instance]('../../getting_started/launch_instance.md') to learn about this list. +!!! Note + It's also possible to launch an instance that has Miniconda preinstalled. You can find this image in the list of source images (look for *Miniconda Ubuntu 22.04*) - refer back to the section [Launch Instance]('../../getting_started/launch_instance.md') to learn about this list. Install Jupyter with conda diff --git a/docs/guides/application_guides/matlab/matlab.md b/docs/guides/application_guides/matlab/matlab.md index d388851..49e9f55 100644 --- a/docs/guides/application_guides/matlab/matlab.md +++ b/docs/guides/application_guides/matlab/matlab.md @@ -2,7 +2,8 @@ In the following we will be guiding you throught the process of installing Matlab on a Strato Instance. -Matlab is also available on [DeiC Interactive HPC]("https://cloud.sdu.dk/") (also known as UCloud). This requires no setup and ships with a GUI out of the box. Read more about this possibility in [the official platform documentation]("https://docs.cloud.sdu.dk/Apps/matlab.html"). +!!! Tip + Matlab is also available on [DeiC Interactive HPC]("https://cloud.sdu.dk/") (also known as UCloud). This requires no setup and ships with a GUI out of the box. Read more about this possibility in [the official platform documentation]("https://docs.cloud.sdu.dk/Apps/matlab.html"). ## Installing Matlab @@ -33,7 +34,7 @@ mpm install --release=R2023b --destination=$HOME/matlab --products Signal_Proces As we want to be able to launch matlab, when we type `matlab` - we will need to add the directory of the matlab executable to our `PATH` variable. We do this and restart our shell: ``` -echo "export PATH=$PATH:$HOME/matlab/bin" >> .bashrc && exec $SHELL +echo "export PATH=$HOME/matlab/bin:$PATH" >> .bashrc && exec $SHELL ``` ## Running Matlab diff --git a/mkdocs.yml b/mkdocs.yml index 082fb08..941fd7e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,7 +15,6 @@ nav: - "Shutting down": guides/getting_started/shutting_down.md - "Application guides": - guides/application_guides/about_applications.md - - "Graphical User Interfaces": guides/application_guides/gui/gui.md - "Matlab": guides/application_guides/matlab/matlab.md - "Jupyter Notebook": ./guides/application_guides/jupyter/jupyter.md # These have been taken out: