diff --git a/README.md b/README.md index ef904a8..dbfb780 100644 --- a/README.md +++ b/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 @@ -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 --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 diff --git a/src/fourc_webviewer/cli_utils.py b/src/fourc_webviewer/cli_utils.py index 3550b52..bffe91d 100644 --- a/src/fourc_webviewer/cli_utils.py +++ b/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() diff --git a/src/fourc_webviewer/run_webserver.py b/src/fourc_webviewer/run_webserver.py index 79b91ad..afba537 100644 --- a/src/fourc_webviewer/run_webserver.py +++ b/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()