Installation Guide

TomoTree can be installed in four ways depending on your use case:

  • Conda / Mamba — recommended for local development and scientific work; manages binary dependencies cleanly.

  • pip — suitable when you already have a Python environment and only need the package.

  • Jupyter / Colab — quick installation in notebook environments for interactive work. This method does not include the Streamlit UI.

  • Docker — recommended for server deployments; no Python environment required on the host.


Prerequisites (all methods)

  • Git — to clone the repository.

  • Python ≥ 3.9 — required by Conda and pip methods.

  • A copy of the repository:

git clone https://github.com/robert-marik/tomotree.git
cd tomotree

Method 1 — Conda / Mamba

This is the recommended approach for local use. Mamba is a faster drop-in replacement for Conda; all commands work equally with either tool.

1. Create and activate a new environment

conda create -n tomotree python=3.12
conda activate tomotree

2. Install core dependencies via Conda

The packages listed in requirements-mamba.txt are available in the conda-forge channel and benefit from pre-compiled binaries (especially NumPy, SciPy, Numba):

conda install --file requirements-mamba.txt -c conda-forge

3. Install pip-only extras

A small number of Streamlit UI components are not available on Conda and must be installed via pip:

pip install -r requirements-pip.txt

4. Install the TomoTree package

pip install -e .

The -e flag installs the package in editable mode, so any changes you make to the source code under src/ take effect immediately without reinstalling.

Library only. pip install -e . without the requirements files above installs just the core library (requirements-core.txt: tomograms, datasets, resistograph, no Streamlit). Optional parts are extras: pip install -e ".[scans]" adds 3D scans (tomotree.scans), pip install -e ".[gui]" everything (the same as steps 2 and 3). From a private repository with an access token: pip install "tomotree[gui] @ git+https://x-access-token:${GITHUB_TOKEN}@github.com/robert-marik/tomotree.git@dev" (without [gui] only the core library is installed and the application does not start).

5. Verify

python -c "import tomotree; print(tomotree.__version__)"

Method 2 — pip

Use this method if you manage your Python environment with pip and venv only, or if you are installing as a dependency of another project.

Option A — Install directly from GitHub (no clone needed)

If you only need the package (not the Streamlit application or configuration files), you can install it in one command using SSH access to the repository:

pip install git+ssh://git@github.com/robert-marik/tomotree.git

Or using HTTPS (no SSH key required):

pip install git+https://github.com/robert-marik/tomotree.git

This installs the latest version of the tomotree Python package together with all its declared dependencies.

Note: The SSH variant requires that your SSH key is authorised for the repository. The HTTPS variant works without any prior setup.

Option B — Install from a local clone

Use this option when you also need the Streamlit web UI, configuration templates, demo data, or want to modify the source code.

1. Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate      # Linux / macOS
# .venv\Scripts\activate       # Windows

2. Install all dependencies and the package

pip install -r requirements-mamba.txt -r requirements-pip.txt
pip install -e .

Note: Some packages in requirements-mamba.txt (notably numba) have C-level dependencies. On Linux and macOS these are usually resolved automatically. On Windows you may need to install the Microsoft C++ Build Tools beforehand.

3. Verify

python -c "import tomotree; print(tomotree.__version__)"

Method 3 — Jupyter / Colab

Use this method to install TomoTree directly in a Jupyter notebook or Google Colab environment for interactive analysis and development.

Simply run this command in a notebook cell:

!pip install git+https://github.com/robert-marik/tomotree.git

Then verify the installation in the next cell:

import tomotree
print(tomotree.__version__)

Advantages

  • No setup required — install and use immediately without managing environments

  • Perfect for demos and quick prototypes — share notebooks with colleagues

  • Works on any machine — including cloud environments like Colab, Kaggle, or Azure Notebooks

Limitations


Method 4 — Docker

Three images built from one docker/Dockerfile: the library only (tomotree:lib, ~0.8 GB), the web application (tomotree:latest, ~3 GB) and JupyterLab with the demo notebooks (tomotree:jupyter, ~0.9 GB). They run as a non-root user, and their ports listen only on 127.0.0.1. Full guide: docker/README.md (česky).

make docker-build                       # in the repository root: builds all three images
cd docker
echo "TOMOTREE_UID=$(id -u)" >> .env; echo "TOMOTREE_GID=$(id -g)" >> .env

# Library: run a script from the current directory
docker run --rm -it --user "$(id -u):$(id -g)" -v "$PWD":/work tomotree:lib python script.py

# Web application on http://localhost:8501 (first start: create the directories and configuration)
(cd .. && mkdir -p streamlit_data streamlit_user streamlit_shared streamlit_session config log .streamlit)
docker compose run --rm tomotree python -m tomotree.streamlit_app.setup_check --init
docker compose up -d

# JupyterLab on http://localhost:8888 (the address with the token is in the log)
docker compose up -d jupyter
docker compose logs jupyter | grep token= | tail -1

The images are not published on Docker Hub yet; build them from the repository.

Docker on a remote server: both ports listen only on 127.0.0.1 of the server; reach them through an SSH tunnel, e.g. ssh -N -L 8888:127.0.0.1:8888 user@server and open the local address (details in docker/README.md).

Connecting with VS Code Dev Containers

VS Code can attach to a running TomoTree container (Dev Containers extension → Dev Containers: Attach to Running Container → the tomotree or jupyter container). The working directory is /app (GUI) or /work (Jupyter).


Post-Installation Configuration (GUI only)

After installing by any method, configure the application before first use.

Short path

From the repository root:

make init-config    # create the missing configuration files and directories
make check-config   # report what is missing or wrong, with the commands that fix it
make www            # start the app (prints the same check first, but does not stop on errors)

make init-config (python -m tomotree.streamlit_app.setup_check --init) never overwrites an existing file. It creates

  • config/config.yaml from config/config.yaml.dist with a random passphrase,

  • config/login.yaml from config/login.yaml.dist with a random cookie key and random passwords of the template accounts demo (admin) and guest, printed once in the terminal,

  • .streamlit/secrets.toml from .streamlit/secrets.toml.dist with a random cookie_secret (and redirect_uri built from hostname),

  • the data directory (dirname) and the runtime directories (userdir, shareddir, session_save_dir, server_status_dir, the directory of log_path).

make check-config (python -m tomotree.streamlit_app.setup_check [--config PATH]) exits with code 1 when there are errors. A login.yaml that still has the public cookie key or the template passwords (demo/password, guest/Tomotree), a config.yaml with the template passphrase or a .streamlit/secrets.toml with the template cookie_secret, e.g. copied by hand from the template, is an error: the app does not start until python -m tomotree.streamlit_app.setup_check --fix-login (in Docker docker compose exec tomotree python -m tomotree.streamlit_app.setup_check --fix-login) replaces them by random values and prints the new passwords (existing secret links stop working when the passphrase changes).

The same check runs in the GUI. Errors that prevent the app from working (no login method, unreadable config.yaml, login.yaml or secrets.toml, Google/Logto.io enabled without the [auth] keys) are shown before login on a Setup required page. Warnings are shown only to admins and developers, see the Administrator Guide.

Streamlit telemetry is turned off in .streamlit/config.toml (local run) and by STREAMLIT_BROWSER_GATHER_USAGE_STATS=false in docker/Dockerfile (Docker image): with browser.gatherUsageStats = true, the Streamlit default, the browser of every user gets the tracking cookie ajs_anonymous_id and sends usage data to data.streamlit.io, which would need the consent of the users. The installation check warns when it is on. The cookies left are only the necessary ones (XSRF protection, login).

The sections below describe the files in detail and the manual alternative.

1. Main configuration file

Manual alternative to make init-config: copy the template and edit it:

cp config/config.yaml.dist config/config.yaml

If the file is missing, the defaults are used. If it is not valid YAML, the app still starts with the defaults and the check reports the error with its line. Unknown keys (typos) are reported with a suggestion of the closest valid key.

Key settings in config/config.yaml:

Key

Description

Default

dirname

Directory containing preloaded demo datasets

streamlit_data

userdir

Root directory for per-user data (<userdir>/<username>/<dataset>/)

streamlit_user

shareddir

Directory with symbolic links to publicly shared datasets

streamlit_shared

session_save_dir

Automatic per-session saves of the application state

streamlit_session

hostname

Public hostname shown in share links

localhost:8501

passphrase

Secret used to encrypt/decrypt sharing links — change this

(placeholder)

allow_registration

Whether new users can register themselves

False

max_user_storage

Per-user storage limit in bytes

104857600 (100 MB)

dpi

Resolution for exported tomogram images

600

allow_no_auth

Run without login when no login method is configured: everybody is logged in as developer with full rights and a red banner is shown on every page. Only for a local single-user installation, never on a server.

false

2. User credentials file

Manual alternative to make init-config: copy the template and edit it:

cp config/login.yaml.dist config/login.yaml

The file defines user accounts. An example entry:

credentials:
  usernames:
    demo:
      email: nobody@nowhere.com
      first_name: Demo
      last_name: TomoTree
      password: MySecurePassword   # will be hashed automatically on first login
      roles:
        - admin

Passwords are stored in hashed form automatically after the first successful login; plain-text values in login.yaml are replaced on startup.

The cookie section controls session persistence:

cookie:
  expiry_days: 30
  key: any_random_string
  name: streamlit_tomotree

Change key to any unique random string for your deployment (make init-config does this).

Password login needs only this file; .streamlit/secrets.toml is not required for it.

3. Google OAuth Authentication (Optional)

To enable login via Google accounts (requires Streamlit 1.42+), follow these steps:

a. Create Google OAuth credentials

  1. Go to Google Cloud Console

  2. Create a new project (or select an existing one)

  3. Go to Credentials → Create Credentials → OAuth 2.0 Client ID

  4. Select Web application as the application type

  5. Add authorized redirect URIs:

    • For local testing: http://localhost:8501/oauth2callback

    • For production: https://your-domain.com/oauth2callback (your actual hostname)

  6. Save your Client ID and Client Secret

b. Configure Streamlit secrets

Store your Google OAuth credentials securely in .streamlit/secrets.toml (project directory) or ~/.streamlit/secrets.toml. Start from the template .streamlit/secrets.toml.dist (make init-config copies it with a random cookie_secret) and uncomment the [auth.google] section:

# ~/.streamlit/secrets.toml
[auth]
redirect_uri = "http://localhost:8501/oauth2callback"
cookie_secret = "some-random-string"

[auth.google]
client_id = "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com"
client_secret = "YOUR_GOOGLE_CLIENT_SECRET"
server_metadata_url = "https://accounts.google.com/.well-known/openid-configuration"

TomoTree calls st.login(<name>) with the provider name from oidc_providers (here google), so the credentials must be in the [auth.google] section.

⚠️ SECURITY WARNING: Never commit credentials to version control. .streamlit/secrets.toml is listed in .gitignore; only the template secrets.toml.dist is tracked.

c. Enable Google OAuth in config

Edit config/config.yaml:

oidc_providers:
  google:                 # = section [auth.google] in .streamlit/secrets.toml
    label: Google         # optional, default: the name
    icon: "🔑"            # optional, default: 🔑
    roles:                # optional, e-mail -> roles (case-insensitive)
      user@example.com: [admin, developer, user]
      reviewer@example.com: [developer, user]
      viewer@example.com: [user]

Users not listed in roles of the provider automatically receive the user role.

d. Result

After logging in:

  • Users can choose between Google and Password login methods

  • Google-authenticated users are identified by their email address

  • Roles are assigned according to roles of the google provider in config.yaml

For the full guide see docs/google_oauth_setup.md.


3b. Logto.io Authentication (Optional)

Logto.io is an OIDC-compatible identity provider that aggregates many upstream sign-in methods (Google, GitHub, Apple ID, Microsoft, and more). Instead of configuring each provider separately, you set up one logto application and enable the connectors you want in the logto dashboard.

a. Create a logto application

  1. Sign in at https://cloud.logto.io (or your self-hosted instance).

  2. Create a Traditional web application.

  3. Note the App ID and App secret.

  4. Add the redirect URI: http://localhost:8501/oauth2callback (or your production URL).

b. Configure Streamlit secrets

Start from .streamlit/secrets.toml.dist (or the file created by make init-config) and uncomment the [auth.logto] section:

# .streamlit/secrets.toml (or ~/.streamlit/secrets.toml)

[auth]
redirect_uri  = "http://localhost:8501/oauth2callback"
cookie_secret = "some-random-string"

[auth.logto]
client_id     = "YOUR_LOGTO_APP_ID"
client_secret = "YOUR_LOGTO_APP_SECRET"
server_metadata_url = "https://<your-tenant>.logto.app/oidc/.well-known/openid-configuration"

TomoTree calls st.login("logto") for the provider named logto in oidc_providers, so the credentials must be in the [auth.logto] section. When Google is configured as well, add the [auth.google] section to the same file (one shared [auth] section).

c. Enable logto.io in config

Edit config/config.yaml:

oidc_providers:
  logto:
    label: Logto.io
    icon: "🪪"
    roles:
      admin@example.com: [admin, developer, user]
      reviewer@example.com: [developer, user]
      viewer@example.com: [user]

d. Result

After enabling logto:

  • Users can choose between Logto.io and Password login methods (and every other provider listed in oidc_providers)

  • Logto redirects users to its hosted sign-in page where they choose from all enabled connectors (Google, GitHub, etc.)

  • Roles are assigned according to roles of the logto provider in config.yaml

For the full guide see docs/logto_setup.md.

3c. Other OIDC providers (Optional)

Any OpenID Connect provider works the same way (Microsoft Entra ID, Keycloak, Auth0, GitLab, …). Plain OAuth2 services without OIDC (e.g. GitHub) can be connected only through an aggregator such as Logto.io or Auth0. For each provider:

  1. Register http://localhost:8501/oauth2callback (or your production URL) as the redirect URI at the provider and note the client ID and secret.

  2. Add a section [auth.<name>] to .streamlit/secrets.toml, e.g. for Keycloak or Auth0:

    [auth.keycloak]
    client_id = "..."
    client_secret = "..."
    server_metadata_url = "https://<host>/realms/<realm>/.well-known/openid-configuration"
    
    [auth.auth0]
    client_id = "..."
    client_secret = "..."
    server_metadata_url = "https://<tenant>.<region>.auth0.com/.well-known/openid-configuration"
    

    server_metadata_url is the full address of the provider’s OIDC discovery document, ending with /.well-known/openid-configuration, never just the provider’s domain.

  3. Add the same name to oidc_providers in config/config.yaml:

    oidc_providers:
      google:
        label: Google
      keycloak:
        label: University account
    

Providers are offered as login buttons in the order given in oidc_providers (a click starts the login at once, the first button is highlighted); password login (login_file) is in a collapsed panel below them. The name password is reserved (make check-config reports it as an error). make check-config also checks that every listed provider has client_id, client_secret and server_metadata_url in its secrets section, and warns when server_metadata_url does not end with /.well-known/openid-configuration.

Streamlit reads .streamlit/secrets.toml only at startup: restart the app after every change of the secrets.

Settings at the provider

The redirect URI http://localhost:8501/oauth2callback (the redirect_uri of [auth], or your production address) is used both for login and for logout, so register it with the path in both lists of the provider:

Provider setting

Value

Allowed callback / redirect URLs

http://localhost:8501/oauth2callback

Allowed logout / post-logout redirect URLs

http://localhost:8501/oauth2callback

Auth0 calls them Allowed Callback URLs and Allowed Logout URLs (Applications → your app → Settings); the application type must be Regular Web Application (otherwise it has no client secret).

Troubleshooting OIDC login

Symptom

Cause and fix

Login fails, the console shows HTTPStatusError: Redirect response '302 Found' for url 'https://<domain>'

server_metadata_url is only the domain. Append /.well-known/openid-configuration and restart the app (make check-config warns about it).

The error persists after fixing .streamlit/secrets.toml

The app was not restarted, or another secrets file was edited. Check the file make check-config reports.

After logout the provider shows an error page (e.g. Auth0 …/oidc/logout?client_id=…)

http://localhost:8501/oauth2callback is missing in the provider’s allowed logout URLs (see above).

Console: No end_session_endpoint found for provider google

Harmless. The provider (Google) has no logout endpoint, so logout ends the TomoTree session only; the user stays logged in at Google in the browser.

Console: Missing provider for OAuth callback; this often indicates a stale or replayed callback

Harmless if login works: the browser returned to /oauth2callback from the back button, a reload, an old tab or after a server restart. If every login fails with it, open the app at exactly the host of redirect_uri (localhost and 127.0.0.1 are different hosts for the login cookie).

Console: AuthlibDeprecationWarning: The httpx module is deprecated

Harmless warning from the authlib library used by Streamlit; disappears with newer versions.

4. Groq AI Integration (Optional)

The configuration editor in the Streamlit UI has optional “Try to fix with Groq AI” buttons that use a Groq language model to automatically correct malformed node coordinates, distance/time matrices, and YAML configuration data.

To enable this feature, add your Groq API key to .streamlit/secrets.toml:

# .streamlit/secrets.toml
groq_api_key = "gsk_YOUR_GROQ_API_KEY"

Obtain a free API key from https://console.groq.com/.

⚠️ SECURITY WARNING: Never commit .streamlit/secrets.toml to version control. Ensure it is listed in .gitignore.

If the key is absent the AI-fix buttons are silently disabled — no error is shown to the user.

5. Required directories

The runtime directories (userdir, shareddir, session_save_dir, server_status_dir and the directory of log_path) are created automatically when the app starts. The data directory dirname (streamlit_data) is not; make init-config creates it, or create it manually:

mkdir -p streamlit_data

When using Docker, the mounted directories are created by the volume mounts. The session directory streamlit_session is not mounted in the example compose.yml, so automatic session saves are lost when the container is recreated; add a volume ./streamlit_session:/app/streamlit_session if you want to keep them.

The layout of user data inside these directories is described in the User Guide.


Running the Application (GUI only)

Streamlit web UI

make www                      # runs make check-config first, then the app
# or
streamlit run app.py          # after cp app.py.dist app.py, see Launching the GUI
# or, without app.py
streamlit run src/tomotree/streamlit_app/app.py

Start the app from the repository root: config/config.yaml and the data directories are resolved relative to the working directory.

Open http://localhost:8501 in your browser.


Running the Test Suite

pytest tests/ -q