Add server functionality for port forwarding

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-on-remote-machine> --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

@@ -18,9 +18,20 @@ def get_arguments():
         dict: Arguments dictionary
     """
     parser = argparse.ArgumentParser(description="4C Webviewer")
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=12345,
+        help="port to start the app on",
+    )
     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)",
+    )
 
     args = parser.parse_args()
 

src/fourc_webviewer/run_webserver.py

@@ -3,13 +3,16 @@
 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
 
-
-def run_webviewer(fourc_yaml_file=None):
+def run_webviewer(port, fourc_yaml_file=None, server=None):
     """Runs the webviewer by creating a dedicated webserver object, starting it
-    and cleaning up afterwards."""
+    and cleaning up afterwards.
+
+    Args:
+        port (int): Port number to start the server on.
+        fourc_yaml_file (str|Path, optional): Path to the input fourc yaml file. If None, the default input file is used.
+        server (bool, optional): If True, runs in server mode without opening a browser. Useful for SSH port forwarding.
+    """
 
     # use the default input file
     if fourc_yaml_file is None:
@@ -18,7 +21,11 @@ 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)
+    if not (1 <= port <= 65535):
+        raise ValueError("Port must be between 1 and 65535")
+
+    open_browser = not bool(server)
+    fourc_webserver.server.start(port=port, open_browser=open_browser)
 
     # run cleanup
     fourc_webserver.cleanup()