Skip to content

update Readme (Several way to run app) #267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Arslan-Siraj merged 11 commits into from
Aug 1, 2025
Merged

update Readme (Several way to run app) #267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
2993a48
Update README.md
Arslan-Siraj Jul 31, 2025
ff0f4ea
Update README.md
Arslan-Siraj Jul 31, 2025
27bdb85
add docs, to run the app
Arslan-Siraj Jul 31, 2025
7d12753
Update README.md
Arslan-Siraj Jul 31, 2025
3ec2995
Update README.md
Arslan-Siraj Jul 31, 2025
49c8785
Update README.md
Arslan-Siraj Jul 31, 2025
98c2920
Update README.md
Arslan-Siraj Jul 31, 2025
6d91278
Update README.md for docker
Arslan-Siraj Jul 31, 2025
c5b0758
Update README.md
Arslan-Siraj Jul 31, 2025
56e2232
add info about both dockerfiles
t0mdavid-m Jul 31, 2025
e326c4b
update docs in template
t0mdavid-m Jul 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 102 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,108 @@ This repository contains a template app for OpenMS workflows in a web applicatio
- framework for workflows with OpenMS TOPP tools
- Deployment [with docker-compose](https://github.com/OpenMS/streamlit-deployment)

## 🔗 Try the Online Demo

Explore the hosted version here: 👉 [Live App](https://abi-services.cs.uni-tuebingen.de/streamlit-template/)

## 💻 Run Locally

To run the app locally:

1. **Clone the repository**
```bash
git clone https://github.com/OpenMS/streamlit-template.git
cd streamlit-template
```

2. **Install dependencies**

Make sure you can run ```pip``` commands.

Install all dependencies with:
```bash
pip install -r requirements.txt
```

4. **Launch the app**
```bash
streamlit run app.py
```

> ⚠️ Note: The local version offers limited functionality. Features that depend on OpenMS are only available in the Docker setup.


## 🐳 Build with Docker

This repository contains two Dockerfiles.

1. `Dockerfile`: This Dockerfile builds all dependencies for the app including Python packages and the OpenMS TOPP tools. Recommended for more complex workflows where you want to use the OpenMS TOPP tools for instance with the **TOPP Workflow Framework**.
2. `Dockerfile_simple`: This Dockerfile builds only the Python packages. Recommended for simple apps using pyOpenMS only.

1. **Install Docker**

Install Docker from the [official Docker installation guide](https://docs.docker.com/engine/install/)

<details>
<summary>Click to expand</summary>

```bash
# Remove older Docker versions (if any)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg; done
```

</details>

2. **Test Docker**

Verify that Docker is working.
```bash
docker run hello-world
```
When running this command, you should see a hello world message from Docker.

3. **Clone the repository**
```bash
git clone https://github.com/OpenMS/streamlit-template.git
cd streamlit-template
```

4. **Specify GitHub token (to download Windows executables).**

Create a temporary `.env` file with your Github token.

It should contain only one line:
`GITHUB_TOKEN=<your-github-token>`

ℹ️ **Note:** This step is not strictly required, but skipping it will remove the option to download executables from the WebApp.

3. **Build & Launch the App**

To build and start the containers.
From the project root directory:

```bash
docker-compose up -d --build
```
At the end, you should see this:
```
[+] Running 2/2
✔ openms-streamlit-template Built
✔ Container openms-streamlit-template Started
```

To make sure server started successfully, run `docker compose ps`. You should see `Up` status:
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4abe0603e521 openms_streamlit_template "/app/entrypoint.sh …" 7 minutes ago Up 7 minutes 0.0.0.0:8501->8501/tcp, :::8501->8501/tcp openms-streamlit-template
```

To map the port to default streamlit port `8501` and launch.

```
docker run -p 8505:8501 openms_streamlit_template
```

## Documentation

Documentation for **users** and **developers** is included as pages in [this template app](https://abi-services.cs.uni-tuebingen.de/streamlit-template/), indicated by the 📖 icon.
Expand Down
112 changes: 84 additions & 28 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,43 +11,99 @@ Select the latest successfull run and download the zip file from the artifacts s

Clone the [streamlit-template repository](https://github.com/OpenMS/streamlit-template). It includes files to install dependencies via pip or conda.

### via pip in a new Python environment
## 💻 Run Locally

Create a virtual environment
To run the app locally:
Comment on lines +14 to +16
Copy link

@coderabbitai coderabbitai bot Jul 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Duplicate top-level sections – merge or drop “## 💻 Run Locally”.

A “## Python” section already exists (Line 10). Adding a second top-level “Run Locally” header fragments the flow and breaks the TOC. Either:

-## 💻 Run Locally
+### 💻 Run Locally   <!-- as subsection of “## Python” -->

or remove the earlier “## Python” header and keep the new one.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
## 💻 Run Locally
Create a virtual environment
To run the app locally:
### 💻 Run Locally <!-- as subsection of “## Python” -->
To run the app locally:
🤖 Prompt for AI Agents 
In docs/installation.md around lines 14 to 16, there are duplicate top-level
headers "## Python" at line 10 and "## 💻 Run Locally" at line 14, which breaks
the table of contents and fragments the document flow. To fix this, either merge
the content under these two headers into a single top-level section or remove
one of the headers entirely to maintain a clear and consistent structure.


`python3 -m venv <myenvpath>`
1. **Clone the repository**
```bash
git clone https://github.com/OpenMS/streamlit-template.git
cd streamlit-template
```

Activate the virtual environment
2. **Install dependencies**

Make sure you can run ```pip``` commands.

Install all dependencies with:
```bash
pip install -r requirements.txt
```

`source .venv/bin/activate`
4. **Launch the app**
```bash
streamlit run app.py
```

To install all required depdencies via pip in the new Python environment, run the following command in the terminal:
> ⚠️ Note: The local version offers limited functionality. Features that depend on OpenMS are only available in the Docker setup.

`pip install -r requirements.txt`

### via pip in an existing Python environment

To install all required depdencies via pip in an already existing Python environment, run the following command in the terminal:

`pip install -r requirements.txt`

### create new environment via conda/mamba

Create and activate the conda environment:

`conda env create -f environment.yml`

`conda activate streamlit-env`

### run the app

Run the app via streamlit command in the terminal. *local* and *online* mode can be toggled in the settings.json. Learn more about *local* and *online* mode in the documentation page 📖 **OpenMS Template App**.

`streamlit run app.py`

## Docker
## 🐳 Build with Docker

This repository contains two Dockerfiles.

1. `Dockerfile`: This Dockerfile builds all dependencies for the app including Python packages and the OpenMS TOPP tools. Recommended for more complex workflows where you want to use the OpenMS TOPP tools for instance with the **TOPP Workflow Framework**.
2. `Dockerfile_simple`: This Dockerfile builds only the Python packages. Recommended for simple apps using pyOpenMS only.

1. **Install Docker**

Install Docker from the [official Docker installation guide](https://docs.docker.com/engine/install/)

<details>
<summary>Click to expand</summary>

```bash
# Remove older Docker versions (if any)
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg; done
```

</details>

2. **Test Docker**

Verify that Docker is working.
```bash
docker run hello-world
```
When running this command, you should see a hello world message from Docker.

3. **Clone the repository**
```bash
git clone https://github.com/OpenMS/streamlit-template.git
cd streamlit-template
```

4. **Specify GitHub token (to download Windows executables).**

Create a temporary `.env` file with your Github token.

It should contain only one line:
`GITHUB_TOKEN=<your-github-token>`

ℹ️ **Note:** This step is not strictly required, but skipping it will remove the option to download executables from the WebApp.

3. **Build & Launch the App**

To build and start the containers.
From the project root directory:

```bash
docker-compose up -d --build
```
At the end, you should see this:
```
[+] Running 2/2
✔ openms-streamlit-template Built
✔ Container openms-streamlit-template Started
```

To make sure server started successfully, run `docker compose ps`. You should see `Up` status:
```
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
4abe0603e521 openms_streamlit_template "/app/entrypoint.sh …" 7 minutes ago Up 7 minutes 0.0.0.0:8501->8501/tcp, :::8501->8501/tcp openms-streamlit-template
```

To map the port to default streamlit port `8501` and launch.

```
docker run -p 8505:8501 openms_streamlit_template
Loading