Skip to content

docs: fix step numbering in README #343

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

Closed
incursio-xd wants to merge 2 commits into from
Closed

docs: fix step numbering in README #343

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
85a6cb8
docs: fix step numbering in README
Feb 20, 2026
ee903cd
docs: refine step numbering fix in README
Feb 20, 2026
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
155 changes: 68 additions & 87 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# OpenMS streamlit template
# OpenMS streamlit template


[![Open Template!](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://abi-services.cs.uni-tuebingen.de/streamlit-template/)

This repository contains a template app for OpenMS workflows in a web application using the **streamlit** framework. It serves as a foundation for apps ranging from simple workflows with **pyOpenMS** to complex workflows utilizing **OpenMS TOPP tools** with parallel execution. It includes solutions for handling user data and parameters in workspaces as well as deployment with docker-compose.

Expand All @@ -16,119 +16,100 @@ This repository contains a template app for OpenMS workflows in a web applicatio

## 🔗 Try the Online Demo

Explore the hosted version here: 👉 [Live App](https://abi-services.cs.uni-tuebingen.de/streamlit-template/)
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
```
```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
```
Make sure you can run `pip` commands.
Install all dependencies with:
```bash
pip install -r requirements.txt

> ⚠️ Note: The local version offers limited functionality. Features that depend on OpenMS TOPP tools are only available out of the box in the Docker setup. For the local version [OpenMS Command Line Tools](https://openms.readthedocs.io/en/latest/about/installation.html) must be installed separately.
```
3. **Launch the app**
```bash
streamlit run app.py

```

> ⚠️ Note: The local version offers limited functionality. Features that depend on OpenMS TOPP tools are only available out of the box in the Docker setup. For the local version [OpenMS Command Line Tools](https://openms.readthedocs.io/en/latest/about/installation.html) must be installed separately.

## 🐳 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
```

3. **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
```
4. **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.
5. **Clone the repository**
```bash
git clone https://github.com/OpenMS/streamlit-template.git
cd streamlit-template

```
6. **Specify GitHub token (to download Windows executables).**
Create a temporary `.env` file with your Github token.
Copy link

@coderabbitai coderabbitai bot Feb 20, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

"Github" should be "GitHub" (capital H)

The official product name uses a capital H. Flagged by LanguageTool.

📝 Proposed fix 
-  Create a temporary `.env` file with your Github token.
+  Create a temporary `.env` file with your GitHub token.
📝 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
Create a temporary `.env` file with your Github token.
Create a temporary `.env` file with your GitHub token.
🧰 Tools
🪛 LanguageTool

[uncategorized] ~70-~70: The official name of this software platform is spelled with a capital “H”.
Context: ...reate a temporary .env file with your Github token. It should contain only one lin...

(GITHUB)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 70, Change the product name capitalization in the README
sentence "Create a temporary `.env` file with your Github token." to use the
official casing "GitHub" (capital H); locate the exact string in the README and
replace "Github" with "GitHub" so the sentence reads "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.
7. **Build & Launch the App**
To build and start the containers. From the project root directory:
```bash
docker-compose up -d --build
Copy link

@coderabbitai coderabbitai bot Feb 20, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Inconsistent docker-compose vs docker compose command syntax

Line 76 uses docker-compose up -d --build (Compose v1 standalone binary) while line 84 uses docker compose ps (Compose v2 plugin syntax). These are different binaries and may not both be available on the same system. Pick one consistently — Compose v2 (docker compose) is the current recommended form.

📝 Proposed fix (standardise on Compose v2) 
-  docker-compose up -d --build
+  docker compose up -d --build

Also applies to: 84-84

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 76, Update README to consistently use Docker Compose v2
syntax: replace all occurrences of the legacy "docker-compose" command (e.g.,
the "docker-compose up -d --build" invocation) with the recommended "docker
compose" form so examples like "docker compose up -d --build" and "docker
compose ps" use the same binary; ensure both occurrences mentioned (the up
command and the ps command) are standardized and any related instructions or
examples are updated to match Compose v2.


```
At the end, you should see this:
```
Copy link

@coderabbitai coderabbitai bot Feb 20, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Fenced code blocks are missing language specifiers

Three code blocks have no language tag, which violates markdownlint rule MD040 and degrades syntax-highlighting in rendered documentation.

📝 Proposed fix

Line 79 (docker-compose output — use text or console):

-  ```
+  ```text
   [+] Running 2/2

Line 85 (docker compose ps table — use text):

-  ```
+  ```text
   CONTAINER ID   IMAGE ...

Line 91 (docker run command — use bash):

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

Also applies to: 85-85, 91-91

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 79-79: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 79, The README has three fenced code blocks missing
language tags (violates MD040) — update the three backticks enclosing the
docker-compose output containing "[+] Running 2/2" to use a text/console tag
(e.g. ```text), the docker compose ps table starting with "CONTAINER ID   IMAGE
..." to use ```text, and the docker run command "docker run -p 8505:8501
openms_streamlit_template" to use ```bash so syntax highlighting is enabled and
markdownlint MD040 is satisfied.

[+] 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

```
Comment on lines +97 to +101
Copy link

@coderabbitai coderabbitai bot Feb 20, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

The trailing docker run command is disconnected and potentially confusing

After a complete docker-compose workflow (build, start, verify with docker compose ps), line 90 introduces docker run -p 8505:8501 openms_streamlit_template without explanation of when or why to use it. Additionally, the accompanying text says "map the port to default streamlit port 8501" yet the external port is 8505, not 8501 — which is likely to confuse readers. If this command is intended as an alternative to docker-compose, that context should be made explicit; otherwise, consider removing it.

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 91-91: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 90 - 94, The docker run snippet is unclear and
mismatched with the text; update the README so the command is either removed OR
clearly presented as an alternative to docker-compose (e.g., "As an alternative
to docker-compose, run the container directly: docker run -p 8505:8501
openms_streamlit_template") and fix the explanatory text to state that the host
port 8505 is mapped to the container's default Streamlit port 8501 (or change
the command to docker run -p 8501:8501 if you intend the host to also be 8501);
ensure the sentence referencing the port reflects the chosen mapping and that
the docker run example is placed with explicit context.


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

## Citation

Please cite:
Müller, T. D., Siraj, A., et al. OpenMS WebApps: Building User-Friendly Solutions for MS Analysis. Journal of Proteome Research (2025). [https://doi.org/10.1021/acs.jproteome.4c00872](https://doi.org/10.1021/acs.jproteome.4c00872)
Please cite: Müller, T. D., Siraj, A., et al. OpenMS WebApps: Building User-Friendly Solutions for MS Analysis. Journal of Proteome Research (2025). [https://doi.org/10.1021/acs.jproteome.4c00872](https://doi.org/10.1021/acs.jproteome.4c00872)

## References

- Pfeuffer, J., Bielow, C., Wein, S. et al. OpenMS 3 enables reproducible analysis of large-scale mass spectrometry data. Nat Methods 21, 365–367 (2024). [https://doi.org/10.1038/s41592-024-02197-7](https://doi.org/10.1038/s41592-024-02197-7)

- Röst HL, Schmitt U, Aebersold R, Malmström L. pyOpenMS: a Python-based interface to the OpenMS mass-spectrometry algorithm library. Proteomics. 2014 Jan;14(1):74-7. [https://doi.org/10.1002/pmic.201300246](https://doi.org/10.1002/pmic.201300246). PMID: [24420968](https://pubmed.ncbi.nlm.nih.gov/24420968/).