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(notablynumba) 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
The Streamlit web UI is not available in Jupyter environments
Consider the Conda/Mamba method or Docker method for production use
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.yamlfromconfig/config.yaml.distwith a randompassphrase,config/login.yamlfromconfig/login.yaml.distwith a random cookie key and random passwords of the template accountsdemo(admin) andguest, printed once in the terminal,.streamlit/secrets.tomlfrom.streamlit/secrets.toml.distwith a randomcookie_secret(andredirect_uribuilt fromhostname),the data directory (
dirname) and the runtime directories (userdir,shareddir,session_save_dir,server_status_dir, the directory oflog_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 |
|---|---|---|
|
Directory containing preloaded demo datasets |
|
|
Root directory for per-user data ( |
|
|
Directory with symbolic links to publicly shared datasets |
|
|
Automatic per-session saves of the application state |
|
|
Public hostname shown in share links |
|
|
Secret used to encrypt/decrypt sharing links — change this |
(placeholder) |
|
Whether new users can register themselves |
|
|
Per-user storage limit in bytes |
|
|
Resolution for exported tomogram images |
|
|
Run without login when no login method is configured: everybody is logged in as |
|
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
Go to Google Cloud Console
Create a new project (or select an existing one)
Go to Credentials → Create Credentials → OAuth 2.0 Client ID
Select Web application as the application type
Add authorized redirect URIs:
For local testing:
http://localhost:8501/oauth2callbackFor production:
https://your-domain.com/oauth2callback(your actual hostname)
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.tomlis listed in.gitignore; only the templatesecrets.toml.distis 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
rolesof thegoogleprovider inconfig.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
Sign in at https://cloud.logto.io (or your self-hosted instance).
Create a Traditional web application.
Note the App ID and App secret.
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
rolesof thelogtoprovider inconfig.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:
Register
http://localhost:8501/oauth2callback(or your production URL) as the redirect URI at the provider and note the client ID and secret.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_urlis the full address of the provider’s OIDC discovery document, ending with/.well-known/openid-configuration, never just the provider’s domain.Add the same name to
oidc_providersinconfig/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 |
|
Allowed logout / post-logout redirect URLs |
|
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 |
|
The error persists after fixing |
The app was not restarted, or another secrets file was edited. Check the file |
After logout the provider shows an error page (e.g. Auth0 |
|
Console: |
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: |
Harmless if login works: the browser returned to |
Console: |
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.tomlto 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