# 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: ```bash 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 ```bash 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): ```bash 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: ```bash pip install -r requirements-pip.txt ``` ### 4. Install the TomoTree package ```bash 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 ```bash 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: ```bash pip install git+ssh://git@github.com/robert-marik/tomotree.git ``` Or using HTTPS (no SSH key required): ```bash 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 ```bash python -m venv .venv source .venv/bin/activate # Linux / macOS # .venv\Scripts\activate # Windows ``` #### 2. Install all dependencies and the package ```bash 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](https://visualstudio.microsoft.com/visual-cpp-build-tools/) beforehand. #### 3. Verify ```bash 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: ```bash !pip install git+https://github.com/robert-marik/tomotree.git ``` Then verify the installation in the next cell: ```python 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](#method-1--conda--mamba) or [Docker method](#method-4--docker) 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](../docker/README.md)** ([česky](../docker/README.cs.md)). ```bash 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](../docker/README.md#3-jupyter-notebooks)). ### 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: ```bash 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](admin_guide.md#installation-check). 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: ```bash 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 (`///`) | `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: ```bash cp config/login.yaml.dist config/login.yaml ``` The file defines user accounts. An example entry: ```yaml 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: ```yaml 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](https://console.cloud.google.com/) 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: ```toml # ~/.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()` 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`: ```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](google_oauth_setup.md). --- ### 3b. Logto.io Authentication (Optional) [Logto.io](https://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](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: ```toml # .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://.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`: ```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](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.]` to `.streamlit/secrets.toml`, e.g. for Keycloak or Auth0: ```toml [auth.keycloak] client_id = "..." client_secret = "..." server_metadata_url = "https:///realms//.well-known/openid-configuration" [auth.auth0] client_id = "..." client_secret = "..." server_metadata_url = "https://..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`: ```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://'` | `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`: ```toml # .streamlit/secrets.toml groq_api_key = "gsk_YOUR_GROQ_API_KEY" ``` Obtain a free API key from [https://console.groq.com/](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: ```bash 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](user_guide.md#where-your-data-are-stored). --- ## Running the Application (GUI only) ### Streamlit web UI ```bash 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 ```bash pytest tests/ -q ```