|
|
| (39 intermediate revisions by 6 users not shown) |
| Line 1: |
Line 1: |
| | [[Category:Software]][[Category:GUI]] | | [[Category:Software]][[Category:GUI]] |
| − | __TOC__
| + | '''The module gui/2 is no longer available. Use this page to know how to use GUI applications on Hipergator. |
| − | Here you will find the information necessary to configure and run graphical user interface (GUI) applications on HiPerGator. The process is not complicated, but running a GUI on a remote server and displaying the windows on your local client computer with a sufficiently responsive interface is not as easy as simply running the application locally. To accomplish this task we use [https://xpra.org Xpra software] - an open-source multi-platform persistent remote display server and client for forwarding application and desktop screens. Full information on Xpra can be found in its [https://xpra.org/trac/wiki/Usage basic usage documentation] and the [https://xpra.org/manual.html Xpra manual]. Below we show the parts of Xpra documentation relevant to running GUI Programs on HiPerGator.
| + | ''' |
| | + | __NOTOC__ |
| | | | |
| − | =Open OnDemand=
| + | Here you will find the information necessary to configure and run graphical user interface (GUI) applications on HiPerGator. The process is not complicated, but running a GUI on a remote server and displaying the windows on your local client computer with a sufficiently responsive interface is not as easy as simply running the application locally. We'd like to acknowledge an Open Source [https://xpra.org Xpra Project] for creating software we built our GUI sessions on top of. |
| − | We are testing an [https://openondemand.org/ Open OnDemand] setup to provide a web-only interface to starting and attaching to GUI programs and Virtual Machines with seamless connections through web browsers. This service is now in Beta and is available at the following URL: | |
| | | | |
| − | https://ondemand.rc.ufl.edu
| + | ==X11 Forwarding== |
| | + | For the simplest case of running a lightweight GUI application for a very short time you can log into HiPerGator with |
| | + | ssh -Y MYUSER@hpg.rc.ufl.edu |
| | + | load the environment module your application is in and run it. Do not analyze data this way, but running a text editor, a web browser to log in and get an api token from a remote service or some other very short and lightweight operations are fine. |
| | | | |
| − | To provide feedback, please open a support request with [OnDemand Feedback] in the subject. Please note:
| + | ==Open OnDemand== |
| | + | Normally the X11 DISPLAY variable is set once the X11 server is started. This can be done manually, as described above, but an easier method is to use [https://help.rc.ufl.edu/doc/Open_OnDemand#Display_Environment_on_the_Console Open OnDemand] since that will start an X11 server and allocate the frame buffer automatically. |
| | | | |
| − | '''Ondemand is currently a Beta service. Users are welcome to test the service and submit support requests with feedback. However, no SLA is guaranteed and all features should be considered experimental.'''
| + | [https://openondemand.org/ Open OnDemand] provides a web-only interface to starting and attaching to GUI programs with seamless connections through web browsers. This service is available at the following URL: |
| | | | |
| − | =GUI2=
| + | https://ondemand.rc.ufl.edu |
| − | This is the second iteration of the UFRC approach to starting GUI programs in SLURM jobs on HiPerGator and attaching to them over any modern web browser.
| |
| − | ==Start GUI Session==
| |
| − | * Log into HiPerGator
| |
| − | * Load the environment module
| |
| − | $ module load gui/2
| |
| − | * Start a GUI session
| |
| − | ** Example: RStudio with 2 cpus, 8gb of memory, 24 hours of run time
| |
| − | $ gui start -e rstudio -c 2 -m 8 -t 24
| |
| − | ** Example: Matlab with default resources (1 cpu, 4gb memory, 2 hours of run time)
| |
| − | $ gui start -e matlab
| |
| − | See <code>gui start -h</code> to see all available options.
| |
| − | ** Example: Hardware-accelerated MatLab instance
| |
| − | $ gui start --gpu -e matlab
| |
| − | | |
| − | ==Show Running GUI Sessions==
| |
| − | '''Note:''' Give the session from few seconds to a couple of minutes to start if the output is empty.
| |
| − | $ gui show
| |
| − | The output will look similar to the following e.g. with four active sessions and real passwords listed instead of 'REDACTED' in the example:
| |
| − | <pre>
| |
| − | Current GUI sessions:
| |
| − | ______________________________________________________________________________
| |
| − | #: JobID Application Type State Reason
| |
| − | 1: 38005270 rstudio gui RUNNING
| |
| − | 2: 38005271 rstudio gui RUNNING
| |
| − | 3: 38005272 rstudio gui RUNNING
| |
| − | 4: 38005355 matlab gui RUNNING
| |
| − | | |
| − | ------------------------------------------------------------------------------
| |
| − | Connection URLs:
| |
| − | 1: https://gui3.rc.ufl.edu/4207/?password=REDACTED
| |
| − | 2: https://gui3.rc.ufl.edu/5713/?password=REDACTED
| |
| − | 3: https://gui5.rc.ufl.edu/12474/?password=REDACTED
| |
| − | 4: https://gui5.rc.ufl.edu/4078/?password=REDACTED
| |
| − | ______________________________________________________________________________
| |
| − | | |
| − | Please copy a connection URL and paste it into a modern web browser's
| |
| − | location bar on your LOCAL computer located on campus or connected via VPN
| |
| − | </pre>
| |
| − | ==Connect To a GUI Session==
| |
| − | * Attach to a session
| |
| − | Copy and paste a session URI into a modern browser (tested on Firefox and Chrome/Chromium) e.g.
| |
| − | https://gui3.rc.ufl.edu/4207/?password=REDACTED
| |
| − | As a result the browser tab becomes a 'desktop canvas' and the GUI program window should be visible and can be resized or maximized to the limits of the browser tab window as normal.
| |
| − | ==Stop a GUI Session==
| |
| − | To stop a session either close the application, which will cause the SLURM job to automatically terminate, or cancel the session on the command-line with
| |
| − | gui stop SESSION_ID
| |
| − | E.g.
| |
| − | <pre>
| |
| − | $ gui stop 3
| |
| − | Current GUI sessions:
| |
| − | ______________________________________________________________________________
| |
| − | #: JobID Application Type State Reason
| |
| − | 1: 38005270 rstudio gui RUNNING
| |
| − | 2: 38005271 rstudio gui RUNNING
| |
| − | 3: 38005272 rstudio gui COMPLETING Stopping session and cleaning up
| |
| − | ------------------------------------------------------------------------------
| |
| − | Connection URLs:
| |
| − | 1: https://gui3.rc.ufl.edu/4207/?password=REDACTED
| |
| − | 2: https://gui3.rc.ufl.edu/5713/?password=REDACTED
| |
| − | ______________________________________________________________________________
| |
| − | | |
| − | Please copy a connection URL and paste it into a modern web browser's
| |
| − | location bar on your LOCAL computer located on campus or connected via VPN
| |
| − | </pre>
| |
| − | | |
| − | This is all it should take to use the 2nd generation setup.
| |
| − | | |
| − | =Hardware Accelerated GUI=
| |
| − | This is a service to provide hardware acceleration for OpenGL applications needing 3D acceleration on HPG. Please see the following page for more information:
| |
| − | | |
| − | [[Hardware_Accelerated_GUI_Sessions|Hardware Accelerated GUI Sessions]]
| |
| − | | |
| − | =GUI1=
| |
| − | This is a classic client/server approach where a gui program is started in a SLURM job on HiPerGator and is wrapped in Xpra server. Once started the session can be attached from a remote (local) computer using the xpra client software.
| |
| − | ==Install Xpra Software on the Client Computer==
| |
| − | Since Xpra is required on both ends of the connection you will have to have it installed on your local computer. Xpra client installation depends on the operating system running on your local machine and may require assistance of a system administrator if you do not have the authority to install new software. Once Xpra is installed on your client computer feel free to skip this step. Installation instructions are specific to the operating system running on your local computer:
| |
| − | * [[Xpra Windows Installation|Windows]]
| |
| − | * [[Xpra MacOS X Installation|MacOS X]]
| |
| − | * [[Xpra Linux Installation|Linux]]
| |
| − | | |
| − | ==Start a GUI Session on HiPerGator==
| |
| − | ;Note: The launch_gui_session script described in the sections below takes a number of arguments allowing specification of the number of cpu cores, memory, time limit, and more. Please run
| |
| − | module load gui
| |
| − | launch_gui_session -h
| |
| − | to see all available arguments.
| |
| − | | |
| − | ===Single command, no job script===
| |
| − | There are two classes of applications that can be started with just one command from the gui environment module and do not require you to provide a job script.
| |
| − | | |
| − | ====Preset applications====
| |
| − | <div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
| |
| − | ''Expand this section to view instructions for starting preset applications without a job script.''
| |
| − | <div class="mw-collapsible-content" style="padding: 5px;">
| |
| − | To list applications presets load the gui module and run launch_gui_session -l
| |
| − | module load gui
| |
| − | launch_gui_session -l
| |
| − | | |
| − | To launch a pre-approved application:
| |
| − | | |
| − | * Load the gui module if not already loaded:
| |
| − | module load gui
| |
| − | * Launch the application:
| |
| − | launch_<application>_gui
| |
| − | | |
| − | | |
| − | For example:
| |
| − | launch_mzmine_gui
| |
| − | or:
| |
| − | launch_rstudio_gui
| |
| − | | |
| − | See a full example on the [[RStudio|RSTudio Help Page]].
| |
| − | For MATLAB options, please see the [[matlab|MATLAB Help Page]].
| |
| − | | |
| − | </div>
| |
| − | </div>
| |
| − | | |
| − | ====Simple applications====
| |
| − | <div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
| |
| − | ''Expand this section to view instructions for starting a simple application without a job script.''
| |
| − | <div class="mw-collapsible-content" style="padding: 5px;">
| |
| − | If you want to run a simple application in which either the environment module name matches the name of the program you want to run or you've already loaded the environment module and know the name of the executable then the process is about as simple as launching a preset application
| |
| − | | |
| − | Load the application environment module if its name is different from the executable name
| |
| − | module load <application>/<version>
| |
| − | | |
| − | Launch the executable in a GUI session:
| |
| − | module load gui
| |
| − | launch_gui_session -e <application>
| |
| − | | |
| − | | |
| − | For example:
| |
| − | launch_gui_session -e molden
| |
| − | | |
| − | ;Note: if the name of the application and its environment module name are different you can use the '--module <module_name>' argument to load a specific module.
| |
| − | | |
| − | For example:
| |
| − | launch_gui_session -e beauti --module beast/2.4.3
| |
| − | or
| |
| − | launch_gui_session -e gv --module gaussian
| |
| − | | |
| − | </div>
| |
| − | </div>
| |
| − | | |
| − | ===Provided job script===
| |
| − | If you need to pass custom arguments to the application, load pre-requisite environment modules or run additional commands, you can provide a simple script (linux format text file) with the required commands as an argument to launch_gui_session.
| |
| − | | |
| − | Make sure to prepend the command that starts the program with xpra_start. For example, a following job script named '''my_molden.sh''' will use the molden/5.0 environment module and start molden with a particular model file:
| |
| − | module load molden/5.0
| |
| − | xpra_start 'molden /ufrc/data/tests/molden/boc-iso-1t.gjf'
| |
| − | | |
| − | Now, to launch molden with the above script run:
| |
| − | launch_gui_session -e molden -f my_molden.sh
| |
| − | | |
| − | ===Manual launch===
| |
| − | If you prefer to talk directly to SLURM you can write a full job script complete with resource requirements, job name, output file, etc in the #SBATCH section and submit the script to SLURM manually.
| |
| − | | |
| − | Make sure you use the gui partition:
| |
| − | <nowiki>#</nowiki>SBATCH --partition=gui
| |
| − | and wrap your command with xpra_start as shown above.
| |
| − | | |
| − | You can use a job script for one of the application presets found in the '$HPC_GUI_JOB' directory once the 'gui' environment module is loaded as the base of your own job script.
| |
| − | | |
| − | ==List GUI Sessions==
| |
| − | If you performed a manual launch or used the '-w' argument to the automated launcher command you'll have to manually check on your gui job. Check the job status with 'squeue -u $USER'. When the job starts you have to list the available xpra sessions using xpra_list_sessions command in the gui module. This command will refresh the Xpra session list and provide a convenient list of live Xpra sessions as well as client commands that can be copied and pasted into a terminal on the client machine.
| |
| − | | |
| − | ;Example:
| |
| − | $ module load gui
| |
| − | $ xpra_list_sessions
| |
| − | | |
| − | Output:
| |
| − | <pre>
| |
| − | Refreshing Xpra session list for jdoe. This could take a while.....
| |
| − | | |
| − | List of active Xpra sessions for jdoe:
| |
| − | | |
| − | Session: i21a-s33.rc.ufl.edu:9626 for RStudio job 2852284
| |
| − | Copy this command to a terminal on your LOCAL PC:
| |
| − | xpra attach ssh:jdoe@i21a-s33.rc.ufl.edu:9626
| |
| − | </pre>
| |
| − | | |
| − | See the respective application pages for details and sample job scripts.
| |
| − | | |
| − | =Connect From a Client Computer=
| |
| − | <span style="color:red">'''Servers in the SLURM gui partition are accessible only within the UF campus network.'''</span>
| |
| − | | |
| − | If you are working off campus, you will need to use the VPN to connect to the UF campus network using [https://connect.ufl.edu/it/wiki/Pages/glvpn-anyconnect-install.aspx AnyConnect VPN] or similar software. Please see: [https://vpn.ufl.edu https://vpn.ufl.edu] for additional information.
| |
| − | | |
| − | ====Connecting from Linux====
| |
| − | <div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
| |
| − | ''Expand this section to view connection instructions for Linux/Unix.''
| |
| − | <div class="mw-collapsible-content" style="padding: 5px;">
| |
| − | Use the client command provided by 'xpra_list_sessions' to connect while adding any local options you need to improve the viewing experience like desktop scaling with <code>--desktop-scaling=on</code> or resolution, dpi (dots per inch) with <code>--dpi=96</code>
| |
| − | | |
| − | ;Command
| |
| − | :$USERNAME is your UF GatorLink username, $SERVERNAME is the GUI server address, and $PORT is the X11 port.
| |
| − | xpra attach ssh:$USERNAME@$SERVERNAME:$PORT
| |
| − | Example:
| |
| − | jdoe@local_computer:~$ xpra attach ssh:testuser@i21a-s33.rc.ufl.edu:12345 --desktop-scaling=on --dpi=96
| |
| − | | |
| − | ;Note
| |
| − | :if you close the application window using the close button in the top right (or left) corner, this will exit your application and terminate your SLURM gui session. Use 'Ctrl+c' key combination in the terminal windows where you ran the xpra attach command to disconnect the session if you plan to reconnect later.
| |
| − | </div>
| |
| − | </div>
| |
| − | | |
| − | ====Connecting from MacOS X====
| |
| − | <div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
| |
| − | ''Expand this section to view connection instructions for MacOS X.''
| |
| − | <div class="mw-collapsible-content" style="padding: 5px;">
| |
| − | | |
| − | '''Note:''' This is done '''ON YOUR PERSONAL COMPUTER''' since you will be connecting from it to HiPerGator. Do '''not''' run this command on HiPerGator.
| |
| − | | |
| − | Use the client command provided by 'xpra_list_sessions' to connect while adding any local options you need to improve the viewing experience like desktop scaling with <code>--desktop-scaling=on</code> or resolution, dpi (dots per inch) with <code>--dpi=96</code>
| |
| − | | |
| − | Example:
| |
| − | xpra attach ssh:test-user@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96
| |
| − | | |
| − | Once the GUI application windows is displayed on your local computer, if you close the window using the close button, both the application and the SLURM gui session will close. If you want to detach from the session (leaving it running) and return later, click on the terminal window where you ran the client command and use the 'Ctrl+c' key combination to detach from the session.
| |
| − | | |
| − | '''Note:'''
| |
| − | If the xpra script was not installed by the .pkg installer or manually as noted on the [[Xpra_MacOS_X_Installation|client software installation]] page, you will need to change into the Xpra installation directory before running Xpra executable.
| |
| − | cd /Applications/Xpra.app/Contents/MacOS
| |
| − | xpra attach ssh:test-user@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96
| |
| − | | |
| − | </div>
| |
| − | </div>
| |
| − | | |
| − | ====Connecting from Microsoft Windows====
| |
| − | <div class="mw-collapsible mw-collapsed" style="width:70%; padding: 5px; border: 1px solid gray;">
| |
| − | ''Expand this section to view instructions for logging in with Microsoft Windows.''
| |
| − | <div class="mw-collapsible-content" style="padding: 5px;">
| |
| − | '''Note:''' This is done '''ON YOUR PERSONAL COMPUTER''' since you will be connecting from it to HiPerGator. Do '''not''' run this command on HiPerGator.
| |
| − | | |
| − | | |
| − | Assuming the xpra shell script was downloaded and installed as on the [[Xpra_Windows_Installation|client software installation]] page. You can open a new terminal window and paste the xpra connect command:
| |
| − | | |
| − | ;Example:
| |
| − | xpra attach ssh:test-user@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96
| |
| − | | |
| − | Once the GUI application windows is displayed on your local computer if you close the window using the close button both the application and the SLURM gui session will close. If you want to simply detach the session and come back later click on the terminal window where you ran the client command and use the 'Ctrl+c' key combination to detach the session.
| |
| − | | |
| − | '''Note:'''
| |
| − | If the xpra script was not installed, you will need to navigate to the install location of xpra (normally C:\Program Files\Xpra\) .
| |
| − | ;In MobaXterm:
| |
| − | cd "/drives/c/Program\ Files/Xpra/"
| |
| − | xpra attach ssh:test-user@i21a-s3.rc.ufl.edu:143 --desktop-scaling=on --dpi=96
| |
| | | | |
| − | </div>
| + | {{Note|Many applications have their own interfaces, but other can also be launched by launching a HiPerGator Desktop and then opening the application with the desktop interface.|info}} |
| − | </div>
| |
| | | | |
| − | ===Special cases (GUI scaling, font issues, etc)=== | + | ===[https://mediasite.video.ufl.edu/Mediasite/Play/4654bfa838624de894085bf54678848f1d Using Open on Demand on HiPerGator]=== |
| − | See the [[GUI_Programs_Special_Cases|Special Cases page for GUI Programs]] if you run a program or a local system that requires special care compared to the normal usage. Some examples of special cases include desktop scaling and DPI issues.
| + | [[File:Play_icon.png|frameless|30px|link=https://mediasite.video.ufl.edu/Mediasite/Play/4654bfa838624de894085bf54678848f1d]] [5 min, 11 sec] |
| | + | This video covers the use of Open on Demand https://openondemand.org/ on HiPerGator via https://ood.rc.ufl.edu/. |
| | + | * Connect to https://ood.rc.ufl.edu/ |
| | + | * Launch a terminal |
| | + | * Launch many graphical applications like Rstudio, Matlab and Freeview |
| | + | * Manage job submission |
| | + | * Upload, download and edit files via your browser |
[5 min, 11 sec]
This video covers the use of Open on Demand https://openondemand.org/ on HiPerGator via https://ood.rc.ufl.edu/.