diff --git a/README.md b/README.md index cd2fe243..9da23d57 100644 --- a/README.md +++ b/README.md @@ -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/) + +
+ 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 + ``` + ## 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. diff --git a/docs/installation.md b/docs/installation.md index f3e6c88a..06e04654 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