Docs: Generalize with Tabs by ax3l · Pull Request #468 · BLAST-AI-ML/synapse

ax3l · 2026-09-18T17:47:50Z

Generalize our docs to be "General Pattern" + "Example Project: ..." style.

That way we:

keep a fully working, copy-pastable version
have by default a pattern that people can adopt to their own projects

Follow-up to #341

- The generic dashboard-training guidance misses the hard-coded realtime QoS - The getting-started tunnel is incompatible with training when MongoDB uses a non-default port - A remaining BELLA-specific command is both ungeneralized and invalid

ax3l · 2026-09-18T22:13:50Z


-3. Set up the database settings (read-only) and the AmSC MLflow API key:
   ```bash
-   export SF_DB_HOST='127.0.0.1'


Removed: went away in a recent PR.
We still need to remove references to it in a few other locations: https://github.com/search?q=repo%3ABLAST-AI-ML%2Fsynapse+SF_DB_HOST&type=code

Co-authored-by: Edoardo Zoni <59625522+EZoni@users.noreply.github.com>

Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

ax3l · 2026-09-22T20:54:09Z

LGTM for a major improvement. Would merge and improve small nits further in separate PRs.

EZoni · 2026-09-22T21:17:33Z

   ```

+   ```{note}
+   This path is hardcoded for the BELLA deployment in {repo}`dashboard/parameters_manager.py`.


Suggested change

This path is hardcoded for the BELLA deployment in {repo}`dashboard/parameters_manager.py`.

This path is hardcoded for the BELLA deployment in {repo}`dashboard/parameters_manager.py` and {repo}`dashboard/model_manager.py`.

EZoni · 2026-09-22T21:28:37Z

-   podman-hpc run --gpu -v /etc/localtime:/etc/localtime -v $HOME/db.profile:/root/db.profile -v /path/to/config.yaml:/app/ml/config.yaml --rm -it registry.nersc.gov/m558/superfacility/synapse-ml:latest python -u /app/ml/train_model.py --test --config_file /app/ml/config.yaml --model NN
+   podman-hpc run --gpu -v /etc/localtime:/etc/localtime --env-file $HOME/db-podman.profile -v <your_config_file>:/app/ml/config.yaml --rm -it registry.nersc.gov/m558/superfacility/synapse-ml:latest python -u /app/ml/train_model.py --test --config_file /app/ml/config.yaml --model NN


Just double checking, these changes in the code snippet,

from db.profile to db-podman.profile

from -v to --env-file

happen to fix issues that we had missed so far?

EZoni · 2026-09-22T21:30:24Z

+conda activate base
+conda-lock install --name synapse-gui environment-lock.yml
+conda activate synapse-gui
+export SF_DB_READONLY_PASSWORD='...'


Suggested change

export SF_DB_READONLY_PASSWORD='...'

export SF_DB_READONLY_PASSWORD='<your_password_here>' # Use SINGLE quotes around the password!

EZoni · 2026-09-22T21:30:36Z

+conda activate base
 conda-lock install --name synapse-ml environment-lock.yml
 conda activate synapse-ml
 export SF_DB_READONLY_PASSWORD='...'


Suggested change

export SF_DB_READONLY_PASSWORD='...'

export SF_DB_READONLY_PASSWORD='<your_password_here>' # Use SINGLE quotes around the password!

EZoni · 2026-09-22T21:31:11Z

+   :sync: bella-nersc
+
+   ```text
+   SF_DB_READONLY_PASSWORD=your_password_here


Suggested change

SF_DB_READONLY_PASSWORD=your_password_here

SF_DB_READONLY_PASSWORD=<your_password_here>

EZoni · 2026-09-22T21:31:38Z

-3. Set up the database settings (read-only) and the AmSC MLflow API key:
   ```bash
-   export SF_DB_HOST='127.0.0.1'
   export SF_DB_READONLY_PASSWORD='your_password_here'  # Use SINGLE quotes around the password!


Suggested change

export SF_DB_READONLY_PASSWORD='your_password_here' # Use SINGLE quotes around the password!

export SF_DB_READONLY_PASSWORD='<your_password_here>' # Use SINGLE quotes around the password!

EZoni · 2026-09-22T21:31:52Z

   ```bash
-   export SF_DB_HOST='127.0.0.1'
   export SF_DB_READONLY_PASSWORD='your_password_here'  # Use SINGLE quotes around the password!
   export AM_SC_API_KEY='your_amsc_api_key_here'        # Required when MLflow tracking_uri is AmSC


Suggested change

export AM_SC_API_KEY='your_amsc_api_key_here' # Required when MLflow tracking_uri is AmSC

export AM_SC_API_KEY='<your_amsc_api_key_here>' # Required when MLflow tracking_uri is AmSC

EZoni · 2026-09-22T21:32:57Z


-3. Set up the database settings (read-only) and the AmSC MLflow API key:
   ```bash
   export SF_DB_READONLY_PASSWORD='your_password_here'  # Use SINGLE quotes around the password!


Suggested change

export SF_DB_READONLY_PASSWORD='your_password_here' # Use SINGLE quotes around the password!

export SF_DB_READONLY_PASSWORD='<your_password_here>' # Use SINGLE quotes around the password!

EZoni · 2026-09-22T21:33:11Z

+   :sync: bella-nersc
+
   ```bash
   export SF_DB_READONLY_PASSWORD='your_password_here'  # Use SINGLE quotes around the password!


Suggested change

export SF_DB_READONLY_PASSWORD='your_password_here' # Use SINGLE quotes around the password!

export SF_DB_READONLY_PASSWORD='<your_password_here>' # Use SINGLE quotes around the password!

EZoni · 2026-09-22T21:33:54Z

-4. Run the Docker container:
   ```bash
-   docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_HOST='127.0.0.1' -e SF_DB_READONLY_PASSWORD='your_password_here' -e AM_SC_API_KEY='your_amsc_api_key_here' synapse-gui
+   docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_READONLY_PASSWORD='your_password_here' -e AM_SC_API_KEY='your_amsc_api_key_here' synapse-gui


Suggested change

docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_READONLY_PASSWORD='your_password_here' -e AM_SC_API_KEY='your_amsc_api_key_here' synapse-gui

docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_READONLY_PASSWORD='<your_password_here>' -e AM_SC_API_KEY='<your_amsc_api_key_here>' synapse-gui

EZoni · 2026-09-22T21:34:12Z

   For debugging, you can enter the container without starting the app:
   ```bash
-   docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_HOST='127.0.0.1' -e SF_DB_READONLY_PASSWORD='your_password_here' -e AM_SC_API_KEY='your_amsc_api_key_here' -it synapse-gui bash
+   docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_READONLY_PASSWORD='your_password_here' -e AM_SC_API_KEY='your_amsc_api_key_here' -it synapse-gui bash


Suggested change

docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_READONLY_PASSWORD='your_password_here' -e AM_SC_API_KEY='your_amsc_api_key_here' -it synapse-gui bash

docker run --network=host -v /etc/localtime:/etc/localtime -v $PWD/ml:/app/ml -e SF_DB_READONLY_PASSWORD='<your_password_here>' -e AM_SC_API_KEY='<your_amsc_api_key_here>' -it synapse-gui bash

EZoni · 2026-09-22T21:34:41Z

-export SF_DB_HOST='127.0.0.1'
-export SF_DB_READONLY_PASSWORD='...'
-export AM_SC_API_KEY='...'
+export <database.password_ro_env>='...'


Suggested change

export <database.password_ro_env>='...'

export <database.password_ro_env>='<your_password_here>' # Use SINGLE quotes around the password!

ax3l · 2026-10-06T05:56:32Z

@EZoni do you like this finish this PR this week (do not over-do it) and we can merge a first generalized version?

ax3l added 3 commits September 18, 2026 10:45

Add Sphinx-Design (for Tabs)

9b61dc4

Update AGENTS.md

53ad856

Docs: Generalize with Tabs

beb8f89

ax3l requested a review from EZoni September 18, 2026 17:47

ax3l added the documentation label Sep 18, 2026

Fix three issues:

35e9b90

- The generic dashboard-training guidance misses the hard-coded realtime QoS - The getting-started tunnel is incompatible with training when MongoDB uses a non-default port - A remaining BELLA-specific command is both ungeneralized and invalid

EZoni mentioned this pull request Sep 18, 2026

Add pre-commit to docs conda environment #469

Merged