Skip to content

docs: improve README setup clarity and Docker instructions #342

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 1 commit into from
Closed

docs: improve README setup clarity and Docker instructions #342

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
107 changes: 56 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# 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/)

Expand All @@ -8,113 +8,120 @@ This repository contains a template app for OpenMS workflows in a web applicatio

- Workspaces for user data with unique shareable IDs
- Persistent parameters and input files within a workspace
- local and online mode
- Local and online mode
- Captcha control
- Packaged executables for Windows
- framework for workflows with OpenMS TOPP tools
- 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/)
Explore the hosted version here: 👉 [Live App](https://abi-services.cs.uni-tuebingen.de/streamlit-template/)

## 💻 Run Locally

To run the app locally:

**Prerequisites:**
- Python 3.9 or newer
- pip

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.

Ensure Python and pip are installed and available in your PATH.

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

4. **Launch the app**
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.
> ⚠️ 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.
This repository contains two Dockerfiles:

1. `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`: Builds only the Python packages. Recommended for simple apps using pyOpenMS only.

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.
Follow these steps to build and launch the app with Docker:

1. **Install Docker**

Install Docker from the [official Docker installation guide](https://docs.docker.com/engine/install/)
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>`

Create a temporary `.env` file with your GitHub token. It should contain only one line:
```
GITHUB_TOKEN=<your-github-token>
```
Comment on lines +92 to +94
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

Add language specifiers to the three fenced code blocks flagged by markdownlint (MD040).

Three code blocks are missing language identifiers, which triggers markdownlint rule MD040 in CI:

  • Line 92: .env contents → use `env or `text
  • Line 109: Docker build output → use `text or `console
  • Line 116: docker compose ps output → use `text or `console
📝 Proposed fix 
-   ```
+   ```env
    GITHUB_TOKEN=<your-github-token>
    ```
-   ```
+   ```text
    [+] Running 2/2
     ✔ openms-streamlit-template            Built
     ✔ Container openms-streamlit-template  Started
    ```
-   ```
+   ```text
    CONTAINER ID   IMAGE  ...
    4abe0603e521   ...
    ```

Also applies to: 109-113, 116-119

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 92-92: 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 92 - 94, Update the three fenced code blocks in
README that currently lack language specifiers: add "env" (or "text") to the
block containing GITHUB_TOKEN (the block showing
GITHUB_TOKEN=<your-github-token>), add "text" (or "console") to the Docker build
output block (the block showing "[+] Running 2/2 ... Built / Started"), and add
"text" (or "console") to the docker compose ps output block (the block showing
"CONTAINER ID   IMAGE ... 4abe0603e521 ..."); ensure each opening
triple-backtick includes the chosen language label (e.g., ```env, ```text) so
markdownlint MD040 is satisfied.


ℹ️ **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:

⚠️ **Security:** Make sure `.env` is listed in your `.gitignore` to avoid accidentally committing your GitHub token.

5. **Build & Launch the App**

To build and start the containers, run the following from the project root directory:

```bash
docker-compose up -d --build
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 the 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
```

*(Optional)* If you want to run the image manually instead of using `docker compose`, you can map the port to the default Streamlit port `8501` as follows:
```bash
docker run -p 8505:8501 openms_streamlit_template
```
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

Expand All @@ -129,6 +136,4 @@ Müller, T. D., Siraj, A., et al. OpenMS WebApps: Building User-Friendly Solutio

- 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/).


- 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/).