Install

1. Requirements

1.1 Required Python libraries

ClimCanvas is developed and tested with Python 3.12. The dependencies are listed below; they can be installed together from requirements.txt when you install the app.

1.2 Optional extras

ClimCanvas works without the following. Add them as needed.

1.3 Setting up a Python environment

ClimCanvas is a visualization tool, and it assumes that users analyze their data in Python beforehand — that is, you already have your own Python environment. It does not matter whether that environment is a shared one or a conda / venv environment you created yourself. Add the dependencies (1.1) to the environment you use for everyday analysis and you can use it as is.

1.3.1 Adding to an existing virtual environment

Activate that environment, then install from the requirements.txt bundled with the app (the location of the app, $IDIR/climcanvas, is explained in 2.1). In a conda environment, you may instead install the same package list as in the conda create below with conda install -c conda-forge (cartopy is most reliably installed from conda-forge).

1.3.2 Creating a new virtual environment

An example of creating a new environment for ClimCanvas. Because cartopy depends on geographic libraries (GEOS and PROJ), installing everything from conda-forge is the most reliable way. "proj<9.8" is a temporary pin that avoids a known cartopy problem (coastlines shifted in latitude when combined with PROJ 9.8); it can be removed once the cartopy fix is released.

With the environment.yml bundled with the app, you can create an environment with the tested set of versions (including the pin above) in a single command.

2. Installing the app

ClimCanvas is not a package that is integrated into a Python environment (via pip install); installing it simply means placing a directory anywhere you like.

There are three forms of installation, and they can be combined (for example, keeping a clone of your own on a server that already has a shared installation by the administrator). Port protection in a remote environment (3.2) works regardless of where the code is located, so the safety is the same in every form.

2.1 Installing it yourself

The steps are the same on your own PC and on a server. Once a Python environment with the dependencies (1.3) is ready, you only need to place the app to start it. Just clone the GitHub repository (ClimCanvas/ClimCanvas).

From here on, the app lives in $IDIR/climcanvas (the directory containing app.py = $IDIR/climcanvas). The trailing climcanvas in git clone is the name of the target directory; if omitted, it becomes ClimCanvas (capitalized). This site consistently uses the lowercase climcanvas.

• Cloning always gives you the latest version. The public repository has only one commit per version, and the head of main is always the latest version. Note that the "Latest" mark in the Releases section on GitHub is attached only to versions with a DOI, so it is not an indicator of the latest version.
• Checking the version you are using: it is shown below the app heading as ver 1.02.1. It is also written on the first line of reproduction scripts.

Using a specific version: versions are selected by tag (such as v1.00). To reproduce a version you used before, for example, clone with the tag name given to --branch.

Updating: a normal clone (main) is brought to the latest version with git pull. A clone made with a tag is not updated with git pull; fetch the tags again and then switch.

Without git: download the Source code (zip) of the version from the "Tags" page on GitHub, extract it, and place the directory as $IDIR/climcanvas. To update, extract the zip of the new version and replace the directory.

2.2 Installation by an administrator (shared installation on a server)

On a server used by several people, a single shared installation by the administrator is easier both to manage and to keep secure. The steps are the same as in 2.1; only the placement differs.

• Place it in a shared location, read-only (e.g. /opt/climcanvas, owned by root). Users need only read and execute permission. If users are allowed to write, a malicious user could modify the code and have other users run it (with their privileges), so always make it read-only.
• The Python environment can be shared too. If you create a conda environment or similar in a location readable by everyone, users do not need to build their own environments.
• The administrator updates once. Updating the shared code applies to everyone, so versions do not diverge between users.
• Users' data stay separate. Settings, sessions, presets and custom colormaps are saved under each user's home in ~/.climcanvas/, so they remain separated per user even though the code is shared.

3. Setup for remote environments

These are the settings for placing the app on a server and using it remotely. They do not depend on whether you or an administrator installed it (2.1 / 2.2). The ideas in 3.1 apply to all remote use. 3.2 is an additional setup done by the administrator when several people use the server and data must be separated between users; 3.3 is the setup done by each user (the deployment mode in config.toml and the range of data that can be opened) and the launch.

3.1 Background: how ClimCanvas approaches security

ClimCanvas itself has no login feature; by design, protection is left to the mechanisms of the OS. The recommended configuration is "each user starts their own ClimCanvas from their own SSH account", resting on the following three pillars.

• Leave authentication to SSH: start with --server.address=127.0.0.1 so that the port is not exposed to the network, and connect only through an SSH tunnel.
• Leave permissions to the OS: rather than everyone sharing a single process, each user starts a process with their own privileges. The files the app can read and write are limited by the OS to those accessible to the person who started it.
• Restrict the data that can be opened: allowed_dirs in the configuration file (3.3) restricts the netCDF files that can be opened to those under the data directories.

All of this can be done by each user, so no administrator work is required.

3.2 What the server administrator does: assigning and protecting a port per user

The configuration above leaves one hole that the OS cannot close. 127.0.0.1 blocks connections from outside the server, but it has no effect on other legitimate users who can log in to the same server over SSH. Streamlit has no authentication, so if someone manages to connect to another person's ClimCanvas by trying port numbers, they can read and write files with the privileges of the person who started it. In an environment where it is acceptable for members with accounts to see each other's data, this is fine as it is; but when data must be separated between users, the administrator (root) sets up firewall owner matching. This locks each port so that only the user it was assigned to may connect, disabling port probing by other users altogether.

The bundled scripts (scripts/server/) combine port assignment and application of the protection rules into a single command (for Linux servers).

• Unless --port N is given, a free port is chosen automatically from the range 8501–8600 (adjustable with the environment variables CLIMCANVAS_BASE_PORT / CLIMCANVAS_MAX_PORT).
• Each assignment adds one line in the form userA<TAB>8501 to the registry /etc/climcanvas/ports.tsv, and on every run the firewall (nftables) rules are regenerated from the whole registry and applied. No stale assignments or duplicate rules are left behind.
• Tell each user their assigned port number once. The user uses this number as the destination of the SSH tunnel from their local PC (if the assignment is 8505, ssh -L 8501:localhost:8505 …; the first 8501 is the port on the user's PC and can be any free number). When assign is run, it prints the connection instructions for that user (① ssh on the local PC → ② the launcher on the server → ③ the browser, with the port number filled in), so you can simply pass them on. Assignments are fixed, so one notification is enough.
• When the user starts the app with scripts/server/start-climcanvas.sh, it looks up the user's port from the registry automatically, so no port number or options need to be written in the start command on the server side (the tunnel on the local PC uses the notified port number). Starting manually with a wrong port or options defeats the protection, so strongly recommend that users start the app from the launcher.

Making the rules persistent (surviving a server reboot)

The applied rules exist only in kernel memory and are lost when the server reboots (the registry and the generated file remain). So set up, once, a mechanism that reloads the generated file /etc/climcanvas/climcanvas.nft at boot. On Debian / Ubuntu, nftables.service loads /etc/nftables.conf with nft -f at boot, so adding one include line there is enough.

• From then on, climcanvas.nft is rewritten on every assign / remove, so the include line never needs to be touched again (the latest state of the registry is always restored at the next boot as well).
• On RHEL / AlmaLinux and relatives, the configuration file is /etc/sysconfig/nftables.conf, but the line to append and systemctl enable nftables are the same.
• If the server is managed with firewalld or ufw, enabling nftables.service may cause conflicts in management. It is safer to create a small systemd unit (or an @reboot cron job) that just runs nft -f /etc/climcanvas/climcanvas.nft.
• The generated file only recreates a dedicated table (inet climcanvas), so including it will not overwrite the existing firewall configuration.

3.3 What the user does

3.3.1 Setting ~/.climcanvas/config.toml

User-side settings are written in ~/.climcanvas/config.toml in your home directory on the server. Refer to the configuration file details and edit three items: allowed_dirs, session_dirs and mode. For remote use, first set mode = "remote". The ClimCanvas UI then changes to the one for remote use. If left unset, the display is always the one for local use. Specifically, with "remote" the blue session tabs read "From the server" / "To the server" and the banner for the session being edited reads "Editing session '…' saved on the server", so that the server side and the local PC side are harder to confuse as the save destination (see saving and restoring work in progress (sessions)).

3.3.2 Setting where sessions are saved

Next, set the directories where work in progress (sessions) is saved. They become the choices of "Destination directory" in the UI. If unset, ~/.climcanvas/sessions is the only choice.

3.3.3 Setting the directories allowed for loading data

In remote use, the "Browse..." button in the sidebar cannot be used when you open netCDF files from the browser. This button opens the OS file dialog, but the dialog opens on the screen of the machine running the app (the server), and nothing happens in the browser on your local PC (FAQ: There is no "Browse..." button, or nothing happens when it is pressed). Therefore, in remote use, setting the directories allowed for loading data is practically mandatory, using allowed_dirs in the configuration file (configuration file details). Once set, "Browse..." is hidden, and instead "Choose from allowed directories", which lets you navigate folders and pick files within the browser, appears in "New work" and "Add a file" in the sidebar (and in the "Coordinate file (optional)" field of each file).

This setting is also convenient from the standpoint of data protection: the netCDF files that can be opened are limited to those under the allowed directories (any other path is an error), and on a server shared by several people you can decide explicitly which data each user may open.

3.3.4 Three ways to specify the allowed directories

There are three ways to specify the allowed directories. Use them as follows: config.toml for the permanent setting, and an environment variable when you want to change it for a single launch only.

The order of precedence is CLIMCANVAS_ALLOWED_DIRS (via the launcher only) > CC_ALLOWED_DIRS > allowed_dirs (config.toml); if none is set, there is no restriction. An environment variable wins over config.toml whenever it is set, even if empty. Via the launcher, CC_ALLOWED_DIRS is overwritten and passed on only when CLIMCANVAS_ALLOWED_DIRS is specified.

3.3.5 Starting the app

Once you have finished editing the configuration file ~/.climcanvas/config.toml, the installation is complete. For the connection procedure, see Usage — remote use. For starting the app on a server that uses port assignment (3.2), see Usage — remote use 1.4.

3.4 Summary: what to set and why

4. License, disclaimer, citation and network access

4.1 License

ClimCanvas is open-source software released under the GNU Affero General Public License version 3 (AGPL-3.0-only), without any warranty (sections 15 and 16 of the license). The full text is in LICENSE in the repository, and the additional terms specific to ClimCanvas are in LICENSE.exception. The main points are as follows.

• The reproduction scripts generated by ClimCanvas and the outputs such as figures, animations and sessions belong to the user. The AGPL does not extend to them.
• When you distribute a modified version or run it over a network for other people, follow the conditions of the AGPL (such as providing the source code). There are no obligations for unmodified use or for your own use.
• The name "ClimCanvas" and the logo may not be used for modified versions.

4.2 Verifying figures is the user's responsibility

It is the user's responsibility to check that a figure generated by ClimCanvas shows what was intended (which level and time were selected, which range was averaged and how, how missing values were handled, and so on). The numerical assumptions are summarized in Computational conventions in the manual, and the checks to make before submitting a paper in Checks before paper submission. When a bug affecting the values in figures is found, the affected versions and features are listed in KNOWN_ISSUES.md in the repository. When citing in a paper or similar, cite with the version you used (citation information is in CITATION.cff).

4.3 Network access

ClimCanvas itself sends nothing over the network. There are two exceptions.

• Download of geographic data: the Natural Earth data for coastlines, borders and land are downloaded automatically by cartopy the first time a given scale is used (an internet connection is required; once fetched, they stay in cartopy's cache).
• Streamlit usage statistics: Streamlit, which is used to display the interface, sends anonymous usage statistics to its developer by default. To stop this, write the following in ~/.streamlit/config.toml on the machine running the app.

4.4 Citation

When citing ClimCanvas in a paper or similar, cite it stating the version you used.

• Checking the version you used: the version (e.g. 1.00.1) is shown in About in the menu at the top right of the app, and on the first line of reproduction scripts.
• Concept DOI 10.5281/zenodo.22997360: common to all versions and always resolves to the latest archive. Use it when referring to the software as a whole, and when the version you used has no version DOI; add the version number alongside.
• Version DOI: refers to the archive of a specific version. DOIs are issued only for milestone versions (v1.00 and the versions used in papers); other versions have only a git tag. Versions with a version DOI: v1.00 = 10.5281/zenodo.22997361.
• The citation metadata are in CITATION.cff in the repository and can be obtained in APA / BibTeX format from "Cite this repository" on the GitHub repository page.