From 4a33a61eee42d2610412bc6d9e5ca8401ae8da85 Mon Sep 17 00:00:00 2001 From: MahiRaj22 Date: Fri, 20 Feb 2026 15:24:14 +0530 Subject: [PATCH] docs: improve README setup clarity and fix Docker command inconsistencies --- README.md | 107 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 56 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 3b995b66..d59b79af 100644 --- a/README.md +++ b/README.md @@ -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/) @@ -8,20 +8,24 @@ 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 @@ -29,92 +33,95 @@ To run the app locally: ``` 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/). +
Click to expand - + ```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 ``` - +
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=` + + Create a temporary `.env` file with your GitHub token. It should contain only one line: + ``` + 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: - + ⚠️ **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 @@ -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/). \ No newline at end of file