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 |
|---|---|---|
|
|
Root directory for administrator-provided preloaded datasets |
|
|
Root directory for per-user data ( |
|
|
Directory used for public sharing symlinks |
|
|
Automatic per-session saves of the application state |
|
|
Path to the user credentials file |
|
|
Allow new users to register themselves |
|
|
Secret used to encrypt/decrypt sharing links — must be set, secret links do not work without it |
|
|
Path for the per-user login event log |
|
|
Markdown file shown on the login/welcome page |
|
|
Markdown shown as a warning box in the sidebar on every page |
|
|
Show the About tab on the home screen |
|
|
Public hostname used in generated share URLs, e.g. |
|
|
Default per-user storage limit in bytes (100 MB) |
|
|
Per-user overrides, e.g. |
|
|
Resolution for exported tomogram images |
|
|
Width (px) of the side-by-side image comparison slider |
|
|
Override default slider/toggle values (see |
|
|
OIDC login providers (Google, Logto.io, Keycloak, …) in the order of the login buttons: |
|
|
With no login method configured, let everybody in as |
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 fromconfig/config.yamlbyload_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 whatdocker/app.pyandsrc/tomotree/streamlit_app/app.pydo.If
app(cfg)is called with aConfig(...)object (as inapp.py.dist), this object is used as is andconfig/config.yamlis not read at all. Parameters not given inConfig(...)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.