From 2993a484acdb754689f49984fd560dfca1cc27f5 Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 11:36:37 +0200 Subject: [PATCH 01/11] Update README.md --- README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/README.md b/README.md index cd2fe243c..c5f8e58b2 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,90 @@ This repository contains a template app for OpenMS workflows in a web applicatio 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. +# πŸš€ Quickstart Guide + +## πŸ”— Try the Online Demo + +Explore the hosted version here: +πŸ‘‰ [Live App](https://abi-services.cs.uni-tuebingen.de/streamlit-template/) + +--- + +## πŸ’» Run Locally + +To test the app locally (without OpenMS features): + +1. **Clone the repository** + ```bash + git clone https://github.com/your-username/streamlit-template.git + cd streamlit-template + ``` + +2. **Install dependencies** + ```bash + pip install -r requirements.txt + ``` + +3. **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. + +--- + +## 🐳 Run with Docker (Full Feature Set) + +We recommend using Docker for a consistent environment and access to all OpenMS-based tools. + +### πŸ”§ Install Docker (Ubuntu) + +Follow the [official Docker installation guide](https://docs.docker.com/engine/install/) +Or run the following commands on Ubuntu: + +
+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 + +# Install Docker’s GPG key and repository +sudo apt-get update +sudo apt-get install -y ca-certificates curl +sudo install -m 0755 -d /etc/apt/keyrings +sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc +sudo chmod a+r /etc/apt/keyrings/docker.asc +echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null +sudo apt-get update +sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin +``` + +
+ +### βœ… Test Docker + +```bash +docker run hello-world +``` + +You should see a "Hello from Docker!" message. + +--- + +### ▢️ Build & Start the App + +From the project root directory: + +```bash +docker compose up -d --build +``` + +This will launch the app with full functionality, including tools that rely on OpenMS. + +--- + ## Citation Please cite: From ff0f4ea77321bc7a2491050734e87f4e81b3fd90 Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 11:47:04 +0200 Subject: [PATCH 02/11] Update README.md --- README.md | 90 +++++++++++++++++++++++-------------------------------- 1 file changed, 38 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index c5f8e58b2..99a1419c0 100644 --- a/README.md +++ b/README.md @@ -18,18 +18,13 @@ This repository contains a template app for OpenMS workflows in a web applicatio 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. -# πŸš€ Quickstart Guide - ## πŸ”— 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 test the app locally (without OpenMS features): +To test the app locally: 1. **Clone the repository** ```bash @@ -49,58 +44,49 @@ To test the app locally (without OpenMS features): > ⚠️ Note: The local version offers limited functionality. Features that depend on OpenMS are only available in the Docker setup. ---- ## 🐳 Run with Docker (Full Feature Set) -We recommend using Docker for a consistent environment and access to all OpenMS-based tools. - -### πŸ”§ Install Docker (Ubuntu) - -Follow the [official Docker installation guide](https://docs.docker.com/engine/install/) -Or run the following commands on Ubuntu: - -
-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 - -# Install Docker’s GPG key and repository -sudo apt-get update -sudo apt-get install -y ca-certificates curl -sudo install -m 0755 -d /etc/apt/keyrings -sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc -sudo chmod a+r /etc/apt/keyrings/docker.asc -echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null -sudo apt-get update -sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -``` - -
- -### βœ… Test Docker - -```bash -docker run hello-world -``` +1. **Install Docker (Ubuntu)** -You should see a "Hello from Docker!" message. - ---- - -### ▢️ Build & Start the App - -From the project root directory: + 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 + + # Install Docker’s GPG key and repository + sudo apt-get update + sudo apt-get install -y ca-certificates curl + sudo install -m 0755 -d /etc/apt/keyrings + sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc + sudo chmod a+r /etc/apt/keyrings/docker.asc + echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + sudo apt-get update + sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin + ``` + +
-```bash -docker compose up -d --build -``` +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. -This will launch the app with full functionality, including tools that rely on OpenMS. +3. **Build & Start the App** ---- + From the project root directory: + + ```bash + docker compose up -d --build + ``` + This will launch the app with full functionality, including tools that rely on OpenMS. ## Citation From 27bdb857eb40c42f7576ad9f518ccf67dbe1eaf6 Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 11:48:00 +0200 Subject: [PATCH 03/11] add docs, to run the app --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 99a1419c0..4cd7c1de7 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,6 @@ 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) -## 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. - ## πŸ”— Try the Online Demo Explore the hosted version here: πŸ‘‰ [Live App](https://abi-services.cs.uni-tuebingen.de/streamlit-template/) @@ -88,6 +84,10 @@ To test the app locally: ``` This will launch the app with full functionality, including tools that rely on OpenMS. +## 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: From 7d12753ef86e4a298ff2965ece5b94cfda3c9fc8 Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 11:59:08 +0200 Subject: [PATCH 04/11] Update README.md --- README.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4cd7c1de7..6cd8d38e6 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ Explore the hosted version here: πŸ‘‰ [Live App](https://abi-services.cs.uni-tu ## πŸ’» Run Locally -To test the app locally: +To run the app locally: 1. **Clone the repository** ```bash @@ -29,11 +29,15 @@ To test the app locally: ``` 2. **Install dependencies** + + Make sure you can run ```pip``` commands. + + Install all dependencies with: ```bash pip install -r requirements.txt ``` -3. **Launch the app** +4. **Launch the app** ```bash streamlit run app.py ``` @@ -82,7 +86,7 @@ To test the app locally: ```bash docker compose up -d --build ``` - This will launch the app with full functionality, including tools that rely on OpenMS. + This will launch the app with full functionality. ## Documentation From 3ec2995f3ac0f800e91c5aba4cd8e322a8fd4960 Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 12:06:20 +0200 Subject: [PATCH 05/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6cd8d38e6..ceddb41f6 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ To run the app locally: 1. **Clone the repository** ```bash - git clone https://github.com/your-username/streamlit-template.git + git clone https://github.com/Arslan-Siraj/streamlit-template.git cd streamlit-template ``` From 49c8785883c2ead44a1d4d0e0475a2e2da0ff5ed Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 12:07:14 +0200 Subject: [PATCH 06/11] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ceddb41f6..054cc8557 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ To run the app locally: 1. **Clone the repository** ```bash - git clone https://github.com/Arslan-Siraj/streamlit-template.git + git clone https://github.com/OpenMS/streamlit-template.git cd streamlit-template ``` From 98c2920ae75f9a96fb03ab947b6fdcff40c59c1c Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 12:20:24 +0200 Subject: [PATCH 07/11] Update README.md --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 054cc8557..04f2e13e2 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,13 @@ To run the app locally: docker run hello-world ``` When running this command, you should see a hello world message from Docker. - +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=` + 3. **Build & Start the App** From the project root directory: From 6d912788ad50bc93a19e3f5103b47c603c23cf6e Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 14:17:16 +0200 Subject: [PATCH 08/11] Update README.md for docker --- README.md | 49 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 04f2e13e2..eedda7083 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,9 @@ To run the app locally: > ⚠️ Note: The local version offers limited functionality. Features that depend on OpenMS are only available in the Docker setup. -## 🐳 Run with Docker (Full Feature Set) +## 🐳 Build with Docker -1. **Install Docker (Ubuntu)** +1. **Install Docker** Install Docker from the [official Docker installation guide](https://docs.docker.com/engine/install/) @@ -57,42 +57,59 @@ To run the app locally: ```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 - - # Install Docker’s GPG key and repository - sudo apt-get update - sudo apt-get install -y ca-certificates curl - sudo install -m 0755 -d /etc/apt/keyrings - sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc - sudo chmod a+r /etc/apt/keyrings/docker.asc - echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - sudo apt-get update - sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ``` 2. **Test Docker** - Verify that Docker is working.. + 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=` + + ℹ️ **Note:** This step is not strictly required, but skipping it will remove the option to download executables from the WebApp. -3. **Build & Start the App** +3. **Build & Launch the App** + To build and start the containers. From the project root directory: ```bash - docker compose up -d --build + docker-compose up -d --build ``` - This will launch the app with full functionality. + 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 From c5b075829be2881ba4f97aa4780144a8ea89348b Mon Sep 17 00:00:00 2001 From: Arslan Siraj Date: Thu, 31 Jul 2025 15:05:12 +0200 Subject: [PATCH 09/11] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eedda7083..a0005a173 100644 --- a/README.md +++ b/README.md @@ -99,13 +99,13 @@ To run the app locally: βœ” Container openms-streamlit-template Started ``` - To make sure server started successfully, run `docker compose ps`. You should see `UPΒ΄ status': + 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. + To map the port to default streamlit port `8501` and launch. ``` docker run -p 8505:8501 openms_streamlit_template From 56e2232b6b349035b222ce246a2ab2856c8b1df8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=20David=20M=C3=BCller?= <57191390+t0mdavid-m@users.noreply.github.com> Date: Thu, 31 Jul 2025 16:39:18 +0200 Subject: [PATCH 10/11] add info about both dockerfiles --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index a0005a173..9da23d57a 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,11 @@ To run the app locally: ## 🐳 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/) From e326c4be90b612a5615662e9ef416e4c6ece273e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=20David=20M=C3=BCller?= <57191390+t0mdavid-m@users.noreply.github.com> Date: Thu, 31 Jul 2025 16:39:33 +0200 Subject: [PATCH 11/11] update docs in template --- docs/installation.md | 112 ++++++++++++++++++++++++++++++++----------- 1 file changed, 84 insertions(+), 28 deletions(-) diff --git a/docs/installation.md b/docs/installation.md index f3e6c88af..06e04654b 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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: -`python3 -m venv ` +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/) + +
+ 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=` + + ℹ️ **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