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:

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:

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 and the Configuration file reference for details.

3. Run the application

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:

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 (<userdir>/<username>/<dataset>/)

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.<name>] 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

  • 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):

[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:

# In app.py
cfg = Config(
    oidc_providers={
        "google": {
            "label": "Google",
            "roles": {
                "user@example.com": ["admin"],
                "reviewer@example.com": ["developer", "user"],
            },
        },
    }
)

Or in config.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.<name>] section; see Other OIDC providers.

See the Installation Guide 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:

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.

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 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

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 and the Administrator Guide.


Changes to Watch for When Updating

app.py.dist is updated alongside the package when new configuration parameters are added. After pulling an update:

# 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.