# Launching the GUI — Using `app.py.dist` The repository ships with a template entry point called `app.py.dist`. It provides a fully configured, commented starting point for running the Streamlit web interface and is the recommended way to customise how the application starts. --- ## Quick Start ### 1. Copy the template From the repository root: ```bash cp app.py.dist app.py ``` `app.py` is listed in `.gitignore` (or treated as a local file), so your customisations will not accidentally overwrite the template when you pull updates. ### 2. Set up configuration files If you have not done this already: ```bash make init-config # create missing config/config.yaml, config/login.yaml, .streamlit/secrets.toml and directories make check-config # report missing or wrong configuration ``` `make init-config` copies the `*.dist` templates with random secrets and never overwrites an existing file. The manual alternative is `cp config/config.yaml.dist config/config.yaml`, `cp config/login.yaml.dist config/login.yaml` and `mkdir -p streamlit_data`; the other directories are created by the app at start. Password login needs no `.streamlit/secrets.toml`. Edit `config/config.yaml` and `config/login.yaml` to match your environment (change the passwords of the template accounts `demo` and `guest`). See the [Installation Guide](installation.md) and the [Configuration file reference](config_file.md) for details. ### 3. Run the application ```bash streamlit run app.py # or, equivalently (prints the installation check first): make www ``` If the configuration has errors that prevent login, the browser shows a *Setup required* page with the commands that fix them. Open **http://localhost:8501** in your browser. --- ## What `app.py.dist` Contains The file has two sections. ### Logging `app()` writes the application log itself (`tomotree.streamlit_app.logging_setup`), whatever entry script starts it (`app.py`, `docker/app.py` or `src/tomotree/streamlit_app/app.py`). Messages of TomoTree from INFO up (logins with provider and `email_verified`, refused logins, file operations, deleted temporary uploads) and warnings of other libraries go to the terminal and to the rotating file `log/app.log` (5 MB, three backups, at most ~20 MB). Admins read it in the Admin console, tab **Log**. Per-rerun details (page start and end, timings) are DEBUG messages. To log one module in detail, add a line to `app.py`: ```python import logging logging.getLogger("tomotree.streamlit.bg").setLevel(logging.DEBUG) ``` An entry script that configures the root logger itself (`logging.basicConfig`, own handlers, as `app_production.py.dist` does) replaces this setup completely. ### `Config()` — application settings All application settings are controlled by the `Config` dataclass (`tomotree.streamlit_app.app_config.Config`). Every parameter has a sensible default and can be left commented out. The table lists the most important parameters; see `app_config.py` for the complete list (authentication by logto.io, whitelist/blacklist, maintenance mode, ...). | Parameter | Default | Description | |-----------|---------|-------------| | `dirname` | `"streamlit_data"` | Root directory for administrator-provided preloaded datasets | | `userdir` | `"streamlit_user"` | Root directory for per-user data (`///`) | | `shareddir` | `"streamlit_shared"` | Directory used for public sharing symlinks | | `session_save_dir` | `"streamlit_session"` | Automatic per-session saves of the application state | | `login_file` | `"config/login.yaml"` | Path to the user credentials file | | `allow_registration` | `False` | Allow new users to register themselves | | `passphrase` | `None` | Secret used to encrypt/decrypt sharing links — **must be set**, secret links do not work without it | | `log_path` | `"log/login.txt"` | Path for the per-user login event log | | `titlepage` | `"config/titlepage.txt"` | Markdown file shown on the login/welcome page | | `side_note` | `"config/side_note.txt"` | Markdown shown as a warning box in the sidebar on every page | | `show_about` | `False` | Show the *About* tab on the home screen | | `hostname` | `None` | Public hostname used in generated share URLs, e.g. `"tomotree.example.com:8501"` | | `max_user_storage` | `104857600` | Default per-user storage limit in bytes (100 MB) | | `user_storage_limits` | `{}` | Per-user overrides, e.g. `{"alice": 524288000}` | | `dpi` | `600` | Resolution for exported tomogram images | | `image_comparison_width` | `800` | Width (px) of the side-by-side image comparison slider | | `widgets` | `{}` | Override default slider/toggle values (see `config/config.yaml.dist`) | | `oidc_providers` | `{}` | OIDC login providers (Google, Logto.io, Keycloak, …) in the order of the login buttons: `{name: {label, icon, roles}}`, the name is the section `[auth.]` in `secrets.toml`; `roles` maps e-mails to application roles, e.g. `{"google": {"roles": {"user@example.com": ["admin"]}}}` | | `allow_no_auth` | `False` | With no login method configured, let everybody in as `developer` (red banner on every page). Local single-user use only, **never on a server** | ### Google OAuth Authentication To enable login via Google accounts: **1. Obtain Google OAuth credentials:** - Go to [Google Cloud Console](https://console.cloud.google.com/) - Create a project - Create OAuth 2.0 credentials (Web application) - Add authorized redirect URI: `http://localhost:8501/oauth2callback` (or your domain) - Save the Client ID and Client Secret **2. Store credentials in `.streamlit/secrets.toml` or `~/.streamlit/secrets.toml`** (template: `.streamlit/secrets.toml.dist`): ```toml [auth] redirect_uri = "http://localhost:8501/oauth2callback" cookie_secret = "some-random-string" [auth.google] client_id = "YOUR_CLIENT_ID.apps.googleusercontent.com" client_secret = "YOUR_CLIENT_SECRET" server_metadata_url = "https://accounts.google.com/.well-known/openid-configuration" ``` **3. Enable in `app.py` or `config/config.yaml`:** ```python # In app.py cfg = Config( oidc_providers={ "google": { "label": "Google", "roles": { "user@example.com": ["admin"], "reviewer@example.com": ["developer", "user"], }, }, } ) ``` Or in `config.yaml`: ```yaml oidc_providers: google: # = section [auth.google] in secrets.toml label: Google # optional, default: the name icon: "🔑" # optional, default: 🔑 roles: user@example.com: [admin, developer] viewer@example.com: [user] ``` Users who log in with Google are identified by their email address and assigned roles according to `roles` of the provider (case-insensitive). Users not listed get the default `user` role. Other OIDC providers (Logto.io, Microsoft Entra ID, Keycloak, …) are added the same way, each with its own `[auth.]` section; see [Other OIDC providers](installation.md#3c-other-oidc-providers-optional). See the [Installation Guide](installation.md#3-google-oauth-authentication-optional) for complete setup instructions. ### Relationship between `app.py` and `config/config.yaml` Settings can be specified in either place, but **not in both at once**: - If `app()` is called **without arguments**, the settings are read from `config/config.yaml` by `load_config()`. The file is read again on every page interaction, so changes take effect without restarting the process, and it is the file managed by the Admin Console editor. This is what `docker/app.py` and `src/tomotree/streamlit_app/app.py` do. - If `app(cfg)` is called with a `Config(...)` object (as in `app.py.dist`), this object is used as is and `config/config.yaml` is **not read at all**. Parameters not given in `Config(...)` keep their built-in defaults. In practice, `config/config.yaml` is the preferred place for deployment-specific values. To use it with `app.py.dist`, replace the `Config(...)` call by `cfg = None`. Use `Config(...)` only when you need Python-level control (for example, when settings depend on environment variables). --- ## Running Without `app.py.dist` If you only need the default configuration you can skip the template and run directly from the installed package entry point: ```bash streamlit run src/tomotree/streamlit_app/app.py ``` This is what `make www` falls back to when no `app.py` exists in the repository root. --- ## Launching the GUI via Docker If you prefer not to install Python dependencies locally, run the web interface (or JupyterLab) from the Docker images. Full guide with the first start (directories, configuration, passwords): [docker/README.md](../docker/README.md). ```bash make docker-build # in the repository root, builds the images cd docker docker compose up -d # GUI on http://localhost:8501 docker compose up -d jupyter # JupyterLab on http://localhost:8888 (token: docker compose logs jupyter) ``` ### Connecting with VS Code VS Code can attach directly to a running container using the [Dev Containers](https://code.visualstudio.com/docs/devcontainers/attach-container) extension. Once the container is running, open the VS Code Command Palette and select **Dev Containers: Attach to Running Container**, then choose the `tomotree` container. ### Useful Docker commands ```bash docker compose ps # list running containers docker compose logs -f # follow live output docker compose down # stop and remove containers docker system df # disk usage of images and volumes docker images # list local images docker image prune # remove unused images ``` For a full production deployment (including persistent data volumes, configuration, and update workflow) see the [Installation Guide — Method 4](installation.md#method-4--docker) and the [Administrator Guide](admin_guide.md). --- ## Changes to Watch for When Updating `app.py.dist` is updated alongside the package when new configuration parameters are added. After pulling an update: ```bash # See what changed in the template diff app.py.dist app.py ``` Copy any new parameters you want into your `app.py` manually. Your existing `app.py` is never overwritten automatically.