Usage — Remote use

1. Launching the app (connection flow)

We recommend an SSH tunnel (port forwarding) for the connection. Authentication and encryption are left to SSH, so the Streamlit port never has to be exposed to the network. 1.1 explains the basic connection flow, and 1.2 and 1.3 introduce settings that make each launch easier (the Streamlit config file and a shell function). 1.4 then describes a better-protected way to launch on a shared server where the administrator assigns ports. Configuring the allowed directories for data loading, which is practically mandatory in remote use, is described in Install 3.3.

1.1 Basic connection flow

The simplest flow, in which a single SSH session serves as both the login and the tunnel, is as follows.

• -L 8501:localhost:8501 has the form -L PC-side-port:localhost:server-side-port and means "forward whatever arrives at port 8501 on my PC, through the encrypted SSH tunnel, to localhost:8501 on the server".
• The first number (PC side) can be changed freely as long as the port is free on your PC (e.g. -L 8502:localhost:8501 — the URL to open in the browser then becomes http://localhost:8502). The second number (server side), however, refers to the port Streamlit actually listens on, so it must match the launch on the server (default 8501; to change it, add --server.port to the launch command so that they agree).
• conda activate env_name switches to your usual Python environment with the dependencies installed (Install 1.3). The shell right after SSH login is in the default environment, so if you forget this step the streamlit command is not found, or the app starts with a python lacking the dependencies and fails.
• streamlit run app.py --server.headless=true means "launch app.py with streamlit, but do not open a browser automatically on the server side".
• With --server.address=127.0.0.1, Streamlit accepts connections only from within the server machine. It is no longer visible directly from the network, and only users who have passed SSH authentication can reach http://<server-IP>:8501.
• Opening http://localhost:8501 in the browser on your PC connects, through the encrypted SSH tunnel, to localhost:8501 on the server.
• Note: closing the terminal of ① (ending the SSH session) stops Streamlit itself together with the tunnel.
• A single tunnel can carry several connections at once. Opening the same URL in two browser tabs gives two independent sessions on the same app, so you can work on different figures in parallel (screens and panel settings do not mix).

1.2 Skip typing the launch options every time (~/.streamlit/config.toml)

The two options in step ② of 1.1 can be omitted if you put a Streamlit config file in your home directory on the server. From then on, streamlit run app.py alone is enough to launch.

• The precedence is "command-line options > environment variables > config file". To change something temporarily, just override it with an option such as --server.port=8503; this file will not get in the way even if you later move to the launcher workflow described below (which launches with the required options stated explicitly).
• This is different from the ClimCanvas config file ~/.climcanvas/config.toml (config file details). The file name config.toml is the same, but this one is read by Streamlit itself.

1.3 Launch from any directory (shell function)

streamlit run can be launched from any directory if you give app.py as an absolute path (Streamlit automatically adds the directory containing app.py to the import search path). The working directory (current directory), however, stays where you launched from, so the initial value data/sample/sample_atmos.nc of the "Path to netCDF file" field and the relative-path form of reproduction scripts (FAQ) are interpreted relative to that location. We therefore recommend writing a shell function in ~/.bashrc that does cd to the installation directory before launching. If you write the full path to python, conda activate is no longer needed either. Write the actual paths, not the placeholder $IDIR used on this page (the example below assumes ClimCanvas is in $HOME/climcanvas and the Python environment in $HOME/miniforge3/envs/myenv).

• On a shared server where the administrator assigns ports (1.4), use the launcher instead of this function; to launch from anywhere, make the launcher an alias (1.4).

1.4 When the administrator has assigned ports (start-climcanvas.sh)

On a multi-user server where the administrator has assigned a port to each user (Install — Setup for remote environments), launch with the bundled launcher. The launcher looks up your port number in the port table automatically and launches with all the options required for protection. Use your own port number as the tunnel destination (the second number) in ① on your PC (the assignment is fixed, so it is the same number every time; the first, PC-side port is free to choose, as in 1.1). You can also launch manually, but a wrong port or option disables the protection, so for safety we strongly recommend launching via the launcher.

• Your port number is given to you by the administrator when it is assigned. If you forget it, first log in to the server normally (without a tunnel) and run the launcher: it prints a ready-to-use connection command of the form "ssh -L 8501:localhost:(your port) …", so run that in another terminal on your PC and then open the browser.
• The launch command is the same regardless of the kind of environment (conda / venv / system python) and of where ClimCanvas is installed (by yourself / by the administrator). If the dependencies are installed in the system python, activate is not needed.
• To restrict the netCDF files that can be opened for a single launch only, launch with CLIMCANVAS_ALLOWED_DIRS set (Install 3.3).

Specifying the python to use (skipping activate)

To launch without activating the environment, set CLIMCANVAS_PYTHON to the python of your environment as a full path. If you put it in ~/.bashrc or similar, you can thereafter launch with just the same commands as ② above, without activate.

An even easier launch (alias / PATH)

The launcher resolves the location of app.py from its own location (the script file), so it can be launched from any directory. Set up an alias or PATH in ~/.bashrc and cd is no longer needed either. Write the actual path, not the placeholder $IDIR used on this page (the example below assumes an installation in /opt/climcanvas).

Reference: launcher environment variables

2. Saving and restoring work in progress (sessions)

A session file is the complete set of settings of a figure you created — the paths of the loaded netCDF files, the panel layout, the plot settings and so on — stored as a single JSON file. By saving it, you can pick up where you left off next time (restore). In remote use there are two methods, depending on whether the file stays on the server or is brought to your PC. Both restoring ("Restore session") and saving ("Save" → "Session") are split into a pair of tabs, "server (blue) / upload and download (orange)", and the origin of the session being edited can always be checked in the banner of the same color above the figure. To have the blue tab labeled "From the server" / "To the server", set mode = "remote" in config.toml on the server (without it, the labels are "From this PC" / "To this PC", intended for local use).

Notes on restoring

• The session JSON contains only the paths of the netCDF files, not the data itself. The paths are paths on the server, so the netCDF files must be at the same locations on the server where you restore (take particular care when bringing a session to a different server).
• In an environment with allowed_dirs set, the paths are validated on restore as well. A session containing paths outside the allowed directories results in an error.
• Sessions saved on the server go in each user's own home directory. Logging in as a different user shows a different list.
• The "Session file" field is for sessions only. Personal preset JSON files are not accepted (a preset placed at ~/.climcanvas/preset.json on the server is applied automatically at start-up).