Skip to content

Commit b737bbb

Browse files
EZoniRemiLehe
EZoni
and
RemiLehe
authored
Add ML environment lock file, update README files (#376)
Co-authored-by: Remi Lehe <remi.lehe@normalesup.org>
1 parent d0d1308 commit b737bbb

File tree

6 files changed

+17297
-204
lines changed

6 files changed

+17297
-204
lines changed

‎dashboard/README.md‎

Lines changed: 181 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -1,121 +1,104 @@
1-
## Dashboard
2-
3-
Here are a few how-to guides on how to develop and use the dashboard.
4-
5-
### Prerequisites
6-
- Ensure you have Conda installed.
7-
- Ensure you have Docker installed (if you plan to use Docker).
8-
9-
### How to create a new conda environment lock file
10-
11-
1. Activate the `base` conda environment:
12-
```console
13-
conda activate base
14-
```
15-
16-
2. Install `conda-lock` (if not already installed):
17-
```console
18-
conda install -c conda-forge conda-lock
19-
```
20-
21-
3. Create the lock file starting from the existing minimal environment file:
22-
```console
23-
conda-lock --file environment.yml --lockfile environment-lock.yml
24-
```
25-
26-
### How to set up the conda environment
27-
28-
1. Activate the `base` conda environment:
29-
```console
30-
conda activate base
31-
```
32-
33-
2. Install `conda-lock` (if not already installed):
34-
```console
35-
conda install -c conda-forge conda-lock
36-
```
37-
38-
3. Create the `synapse-gui` conda environment from the lock file:
39-
```console
40-
conda-lock install --name synapse-gui environment-lock.yml
41-
```
42-
43-
### How to run the GUI
44-
45-
1. Activate the `synapse-gui` conda environment:
46-
```console
47-
conda activate synapse-gui
48-
```
49-
50-
2. Set the database settings (read only):
51-
```console
52-
export SF_DB_HOST='127.0.0.1'
53-
export SF_DB_READONLY_PASSWORD='your_password_here' # Use SINGLE quotes around the password!
54-
```
55-
56-
3. For local development, open a separate terminal and keep it open while SSH forwarding the database connection:
57-
```console
58-
ssh -L 27017:mongodb05.nersc.gov:27017 <username>@dtn03.nersc.gov -N
59-
```
60-
61-
4. Run the GUI from the `dashboard/` folder:
62-
- Via the web browser interface:
63-
```console
64-
python -u app.py --port 8080
65-
```
66-
- As a desktop application:
67-
```console
68-
python -u app.py --app
69-
```
70-
If you run the GUI as a desktop application, make sure to set the following environment variable first:
71-
```console
72-
python -m pip install pywebview[qt]
73-
export PYWEBVIEW_GUI=qt
74-
```
75-
76-
5. Terminate the GUI via `Ctrl` + `C`.
77-
78-
### How to build and run the Docker container
1+
# Table of Contents
2+
* [Overview](#Overview)
3+
* [Run the Dashboard Locally](#Run-the-Dashboard-Locally)
4+
* [Without Docker](#Without-Docker)
5+
* [With Docker](#With-Docker)
6+
* [Run the Dashboard at NERSC](#Run-the-Dashboard-at-NERSC)
7+
* [Get the Superfacility API Credentials](#Get-the-Superfacility-API-Credentials)
8+
* [For Maintainers](#For-Maintainers)
9+
* [Generate the conda environment lock file](#Generate-the-conda-environment-lock-file)
10+
* [Build and push the Docker container to NERSC](#Build-and-push-the-Docker-container-to-NERSC)
11+
* [References](#References)
7912

80-
1. Move to the root directory of the repository.
13+
# Overview
14+
15+
The Synapse dashboard provides a web interface for working with data from experiments, simulations, and ML models.
16+
17+
The dashboard can be run in two distinct ways:
18+
19+
1. Locally on your computer.
20+
21+
2. At NERSC through Spin.
22+
23+
# Run the Dashboard Locally
24+
25+
This section describes how to develop and use the dashboard locally.
26+
27+
## Without Docker
28+
29+
### Prepare the conda environment
30+
31+
1. Move to the [dashboard/](./) directory.
32+
33+
2. Activate the conda environment `base`:
34+
```bash
35+
conda activate base
36+
```
37+
38+
3. Install `conda-lock` if not installed yet:
39+
```bash
40+
conda install -c conda-forge conda-lock
41+
```
42+
43+
4. Create the conda environment `synapse-gui`:
44+
```bash
45+
conda-lock install --name synapse-gui environment-lock.yml
46+
```
47+
48+
### Run the dashboard
49+
50+
1. Create an SSH tunnel to access the MongoDB database at NERSC (in a separate terminal):
51+
```bash
52+
ssh -L 27017:mongodb05.nersc.gov:27017 <username>@dtn03.nersc.gov -N
53+
```
54+
55+
2. Move to the [dashboard/](./) directory.
56+
57+
3. Set up the database settings (read-only):
58+
```bash
59+
export SF_DB_HOST='127.0.0.1'
60+
export SF_DB_READONLY_PASSWORD='your_password_here' # Use SINGLE quotes around the password!
61+
```
62+
63+
4. Activate the conda environment `synapse-gui`:
64+
```bash
65+
conda activate synapse-gui
66+
```
67+
68+
5. Run the dashboard as a web application:
69+
```bash
70+
python -u app.py --port 8080
71+
```
72+
73+
## With Docker
74+
75+
### Run the dashboard
76+
77+
1. Create an SSH tunnel to access the MongoDB database at NERSC (in a separate terminal):
78+
```bash
79+
ssh -L 27017:mongodb05.nersc.gov:27017 <username>@dtn03.nersc.gov -N
80+
```
81+
82+
2. Move to the root directory of the repository.
83+
84+
3. Build the Docker image as described [below](#build-the-docker-image).
85+
86+
4. Run the Docker container:
87+
```bash
88+
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' synapse-gui
89+
```
90+
For debugging, you can enter the container without starting the app:
91+
```bash
92+
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' -it synapse-gui bash
93+
```
94+
Note that `-v /etc/localtime:/etc/localtime` is necessary to synchronize the time zone in the container with the host machine.
8195

82-
2. Build the Docker image based on `Dockerfile`:
83-
```console
84-
docker build --platform linux/amd64 -t synapse-gui -f dashboard.Dockerfile .
85-
```
86-
87-
3. Run the Docker container from the `dashboard/` folder:
88-
```console
89-
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' synapse-gui
90-
```
91-
For debugging, you can also enter the container without starting the app:
92-
```console
93-
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' -it synapse-gui bash
94-
```
95-
Note that `-v /etc/localtime:/etc/localtime` is necessary to synchronize the time zone in the container with the host machine.
96-
97-
4. Optional: Publish the container privately to NERSC registry (https://registry.nersc.gov):
98-
```console
99-
docker login registry.nersc.gov
100-
# Username: your NERSC username
101-
# Password: your NERSC password without 2FA
102-
```
103-
```console
104-
docker tag synapse-gui:latest registry.nersc.gov/m558/superfacility/synapse-gui:latest
105-
docker tag synapse-gui:latest registry.nersc.gov/m558/superfacility/synapse-gui:$(date "+%y.%m")
106-
docker push -a registry.nersc.gov/m558/superfacility/synapse-gui
107-
```
108-
This has been also automated through the Python script [publish_container.py](https://github.com/BLAST-AI-ML/synapse/blob/main/publish_container.py), which can be executed via
109-
```console
110-
python publish_container.py --gui
111-
```
112-
113-
5. Optional: From time to time, as you develop the container, you might want to prune old, unused images to get back GBytes of storage on your development machine:
114-
```console
115-
docker system prune -a
116-
```
117-
118-
### How to get the Superfacility API credentials
96+
# Run the Dashboard at NERSC
97+
98+
Connect to the [dashboard](https://bellasuperfacility.lbl.gov/) deployed at NERSC through Spin and play around!
99+
Remember that you need to upload valid Superfacility API credentials in order to launch simulations or train ML models directly from the dashboard.
100+
101+
# Get the Superfacility API Credentials
119102

120103
Following the instructions at [docs.nersc.gov/services/sfapi/authentication/#client](https://docs.nersc.gov/services/sfapi/authentication/#client):
121104

@@ -127,15 +110,89 @@ Following the instructions at [docs.nersc.gov/services/sfapi/authentication/#cli
127110

128111
4. Enter a client name (e.g., "Synapse"), choose `sf558` for the user, choose "Red" security level, and select either "Your IP" or "Spin" from the "IP Presets" menu, depending on whether the key will be used from a local computer or from Spin.
129112

130-
5. Download the private key file (in pem format) and save it as `priv_key.pem` in the root directory of the GUI.
131-
Each time the GUI is launched, it will automatically find the existing key file and load the corresponding credentials.
113+
5. Download the private key file (in pem format) and save it as `priv_key.pem` in the root directory of the dashboard.
114+
Each time the dashboard is launched, it will automatically find the existing key file and load the corresponding credentials.
132115

133116
6. Copy your client ID and add it on the first line of your private key file as described in the instructions at [nersc.github.io/sfapi_client/quickstart/#storing-keys-in-files](https://nersc.github.io/sfapi_client/quickstart/#storing-keys-in-files):
134-
```
135-
randmstrgz
136-
-----BEGIN RSA PRIVATE KEY-----
137-
...
138-
-----END RSA PRIVATE KEY-----
139-
```
117+
```
118+
randmstrgz
119+
-----BEGIN RSA PRIVATE KEY-----
120+
...
121+
-----END RSA PRIVATE KEY-----
122+
```
140123

141124
7. Run `chmod 600 priv_key.pem` to change the permissions of your private key file to read/write only.
125+
126+
# For Maintainers
127+
128+
## Generate the conda environment lock file
129+
130+
1. Move to the directory [dashboard/](.).
131+
132+
2. Activate the conda environment `base`:
133+
```bash
134+
conda activate base
135+
```
136+
137+
3. Install `conda-lock` if not installed yet:
138+
```bash
139+
conda install -c conda-forge conda-lock
140+
```
141+
142+
4. Generate the conda environment lock file:
143+
```bash
144+
conda-lock --file environment.yml --lockfile environment-lock.yml
145+
```
146+
147+
## Build and push the Docker container to NERSC
148+
149+
> [!WARNING]
150+
> Pushing a new Docker container affects the production dashboard deployed at NERSC through Spin.
151+
152+
> [!TIP]
153+
> Run this workflow automatically with the Python script [publish_container.py](../publish_container.py):
154+
> ```bash
155+
> python publish_container.py --gui
156+
> ```
157+
158+
> [!TIP]
159+
> Prune old, unused images periodically in order to free up space on your machine:
160+
> ```bash
161+
> docker system prune -a
162+
> ```
163+
164+
### Build the Docker image
165+
166+
1. Move to the root directory of the repository.
167+
168+
2. Build the Docker image:
169+
```bash
170+
docker build --platform linux/amd64 -t synapse-gui -f dashboard.Dockerfile .
171+
```
172+
173+
### Push the Docker container
174+
175+
1. Move to the root directory of the repository.
176+
177+
2. Login to the [NERSC registry](https://registry.nersc.gov):
178+
```bash
179+
docker login registry.nersc.gov
180+
# Username: your NERSC username
181+
# Password: your NERSC password without 2FA
182+
```
183+
184+
3. Tag the Docker image:
185+
```bash
186+
docker tag synapse-gui:latest registry.nersc.gov/m558/superfacility/synapse-gui:latest
187+
docker tag synapse-gui:latest registry.nersc.gov/m558/superfacility/synapse-gui:$(date "+%y.%m")
188+
```
189+
190+
4. Push the Docker container:
191+
```bash
192+
docker push -a registry.nersc.gov/m558/superfacility/synapse-gui
193+
```
194+
195+
# References
196+
197+
* [Using NERSC's `registry.nersc.gov`](https://docs.nersc.gov/development/containers/registry/)
198+
* [Superfacility API authentication](https://docs.nersc.gov/services/sfapi/authentication/#client)

‎ml.Dockerfile‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,11 @@ ENV PIP_ROOT_USER_ACTION=ignore
1010
# Install any needed packages specified in the environment file
1111
# Match the CUDA 12.4.0 on Perlmutter (NERSC):
1212
# https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#specifying-a-different-target-platform-for-an-environment
13-
COPY ml/environment.yml /app/ml/environment.yml
13+
COPY ml/environment-lock.yml /app/ml/environment-lock.yml
1414
ENV CONDA_OVERRIDE_CUDA=12.4.0
1515
RUN conda info
16-
RUN conda env create -y -f environment.yml \
16+
RUN conda install -c conda-forge conda-lock \
17+
&& conda-lock install --name synapse-ml environment-lock.yml \
1718
&& conda clean --all -y
1819

1920
# Configure an exectuable entrypoint script

0 commit comments

Comments
 (0)