Updated remote server documentation

Author: smistad

doc/pages/Running-FAST-on-a-remote-server.md

@@ -1,40 +1,75 @@
 Running FAST on a remote server {#fast-remote-server}
 ========================================
 
-FAST can run on a remote Linux server using SSH.
+FAST can run on a remote Linux server using SSH. [Install FAST and its dependencies for Linux](@ref install-ubuntu-linux).
 
-**If you don't want to do any visualization, you don't have to do anything extra.** FAST will detect that there is no display to render and thus disable visualization (i.e. OpenGL) in FAST. If you try to do anything that requires OpenGL (rendering etc.) FAST will crash.
+**If you don't want to do any visualization, you don't have to do anything extra.** 
+FAST will detect that there is no display to render and thus disable visualization (i.e. OpenGL) in FAST. 
+If you try to do anything that requires OpenGL (rendering etc.) FAST will throw an exception.
 
-**If you want to run FAST with visualization on a remote server you need to use [VirtualGL](https://virtualgl.org/).** Indirect rendering over SSH with X forwarding (ssh -X) will not work because FAST uses modern OpenGL (3+), which indirect GLX does not support (however some have reported that modern Mesa OpenGL does support this).
+However, if you want to do rendering and visualization with FAST on a remote headless server, you need to use OpenGL, X and GLX.
+To do this, you either need Xvfb or VirtualGL depending on whether you want an interactive FAST window or not, see below for more information.
 
-### Setting up VirtualGL
-
-**WARNING: Installing VirtualGL can mess up your system if not done correctly. Make sure you know what you are doing. Also, note that this guide has not been updated for a long time.**
+## Remote FAST visualization WITHOUT interactive window
+**If you only want to render a visualization FAST, without interactive having an window, you can use Xvfb**.
+Since X requires a display, which you don't necessarily have on a headless server, you
+can use Xvfb (X virtual framebuffer) to create a virtual screen.
 
-Install VirtualGL on the client machine (If windows, see [documentation here](https://rawcdn.githack.com/VirtualGL/virtualgl/main/doc/index.html#hd005003)):
-```bash
-sudo apt install virtualgl
-```
-Then, install VirtualGL on the server machine:
+First install Xvfb:
 ```bash
-sudo apt install virtualgl
+sudo apt install xvfb
 ```
-If your server is *headless*, meaning it has no display connected, you need to setup an "empty" X display.
-If your server uses the NVIDIA driver, you can do this with the following command:
+Then you can create a virtual screen with a given resolution and DISPLAY ID:
+The DISPLAY ID should be unique, so if you have multiple users, and/or a real screen attached to the server.
+Make sure you select a DISPLAY ID which is unused.
 ```bash
-sudo nvidia-xconfig -a --use-display-device=None --virtual=1280x1024
+DISPLAY=:10 # Set the DISPLAY environment variable
+Xvfb "$DISPLAY" -screen 0 1920x1080x24 & # You can change the resolution here if wanted
 ```
-This will create a new xorg.conf config file in the folder /etc/X11/.
 
-Then run the virtualgl config on your server:
-```
-vglserver_config
+Now you should be able to render a FAST visualization on a headless remote server which you can then save to an image file
+or display with another visualization program which can run with X forwarding, for instance matplotlib if you are using python.
+
+## Examples
+Make sure you have Xvfb running and the DISPLAY environment variable active in the terminal
+you are running these examples from.
+
+**Example of remote headless rendering to an image file with FAST using python:**
+```python
+import fast
+
+importer = fast.ImageFileImporter.create(fast.Config.getDocumentationPath() + '/images/FAST_logo_square.png')
+renderer = fast.ImageRenderer.create().connect(importer)
+visualization = fast.RenderToImage.create(width=1024).connect(renderer)
+fast.ImageFileExporter.create('fast_remote_render.jpg')\
+    .connect(visualization)\
+    .run()
 ```
-Finally restart X on your server, or just reboot:
-```bash
-sudo systemctl restart gdm
+
+**Example of remote headless rendering with FAST and display using matplotlib:**
+```python
+import fast
+import matplotlib.pyplot as plt
+
+importer = fast.ImageFileImporter.create(fast.Config.getDocumentationPath() + '/images/FAST_logo_square.png')
+renderer = fast.ImageRenderer.create().connect(importer)
+visualization = fast.RenderToImage.create(width=1024)\
+    .connect(renderer)\
+    .runAndGetOutputData()
+
+plt.imshow(visualization)
+plt.show()
 ```
-If something goes wrong, remove the xorg.conf that was created (or replace it with the backup /etc/X11/xorg.conf.backup) and reboot.
+
+## Remote FAST visualization WITH interactive window
+**If you want to run FAST with interactive visualization on a remote server you need to use [VirtualGL](https://virtualgl.org/).** 
+Indirect rendering over SSH with X forwarding (ssh -X) will not work because FAST uses modern OpenGL (3+), which indirect GLX does not support (however some have reported that modern Mesa OpenGL does support this).
+
+### Setting up VirtualGL
+
+**WARNING: Installing VirtualGL can mess up your system if not done correctly. Make sure you know what you are doing. Also, note that this guide has not been updated for a long time.**
+
+Follow the instructions on installing VirtualGL from the [official VGL documentation](https://virtualgl.org/).
 
 ### Using FAST with VirtualGL
 Instead of using the ssh command to connect to the server, connect with the following virtualgl command instead:
@@ -54,4 +89,4 @@ vglrun python
 vglrun python your_script.py
 ```
 
-For more information on VirtualGL over SSH, see [documentation here](https://rawcdn.githack.com/VirtualGL/virtualgl/main/doc/index.html#hd008).
+For more info, read the [official VirtualGL documentation](https://virtualgl.org/).