Add server functionality for port forwarding

- This PR implements additional server functionality for
the webviewer, enabling local visualizations even though
the webviewer is run on a remote machine.
- Specifically, the user can specify whether
the webviewer should be run in server mode, and on which port,
thereby enabling SSH port forwarding.

Author: dragos-ana

README.md

@@ -51,10 +51,11 @@ pre-commit install
 
 ## Using the 4C-Webviewer
 
-To start the webviewer, in the conda environment run:
+After activating the conda environment, start the webviewer by using:
 ```
 fourc_webviewer
 ```
+
 To directly open a YAML input file use
 ```
 fourc_webviewer --fourc_yaml_file <path-to-4C-YAML-input-file>
@@ -65,6 +66,20 @@ Alternatively change to the directory of the repo. Activate the created conda en
 python main.py
 ```
 
+The webviewer can also be run in server mode on a remote machine without opening the browser:
+```
+fourc_webviewer --fourc_yaml_file <path-to-4C-YAML-input-file> --server --port 12345
+```
+Then, on your local machine, forward the bound port 12345:
+```
+ssh -N -L 12345:localhost:12345 user@remote
+```
+and open the local browser at:
+```
+http://localhost:12345
+```
+
+
 ## Dependency Management
 
 To ease the dependency update process [`pip-tools`](https://github.com/jazzband/pip-tools) is utilized. To create the necessary [`requirements.txt`](./requirements.txt) file simply execute

src/fourc_webviewer/cli_utils.py

@@ -21,6 +21,16 @@ def get_arguments():
     parser.add_argument(
         "--fourc_yaml_file", type=str, help="input file path to visualize"
     )
+    parser.add_argument(
+        "--server",
+        action="store_true",
+        help="start app in server mode without opening the browser? (useful for local port forwarding via ssh)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        help="port to start the app on",
+    )
 
     args = parser.parse_args()
 

src/fourc_webviewer/run_webserver.py

@@ -3,11 +3,11 @@
 from fourc_webviewer.fourc_webserver import FourCWebServer
 from fourc_webviewer_default_files import DEFAULT_INPUT_FILE
 
-# specify server port for the app to run on
-SERVER_PORT = 12345
+# specify default port for running the app
+DEFAULT_PORT = 12345
 
 
-def run_webviewer(fourc_yaml_file=None):
+def run_webviewer(fourc_yaml_file=None, port=None, server=None):
     """Runs the webviewer by creating a dedicated webserver object, starting it
     and cleaning up afterwards."""
 
@@ -18,7 +18,9 @@ def run_webviewer(fourc_yaml_file=None):
     fourc_webserver = FourCWebServer(fourc_yaml_file)
 
     # start the server after everything is set up
-    fourc_webserver.server.start(port=SERVER_PORT)
+    server_port = port or DEFAULT_PORT
+    open_browser = not server
+    fourc_webserver.server.start(port=server_port, open_browser=open_browser)
 
     # run cleanup
     fourc_webserver.cleanup()