From f9bdf97b797909509cc1517df55b11b1061306a4 Mon Sep 17 00:00:00 2001 From: Ehsanstp <142738825+Ehsanstp@users.noreply.github.com> Date: Wed, 25 Mar 2026 14:28:09 +0600 Subject: [PATCH 1/4] Update README.md --- README.md | 117 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index f38a4d3..6417ee7 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,14 @@ The Reactome ChatBot is an interactive tool that provides information about biol ## Installation +### Supported Operating Systems +- **Linux** +- **MacOS** +- **Windows** - Windows 10 version 2004 or higher, or Windows 11 + - Windows users must use [WSl](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). + - **WSL version 2.1.5 or later** is required. To check your version: `wsl --version` + - Recommended distribution: Ubuntu + ### Prerequisites - **Minimum requirements:** @@ -13,10 +21,13 @@ The Reactome ChatBot is an interactive tool that provides information about biol - **Requirements for running the complete application:** + [Docker](https://docs.docker.com/get-started/get-docker/) + [Docker Compose](https://docs.docker.com/compose/install/) + + Windows users should install [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) with WSL 2 backend enabled (Settings → Resources → WSL integration) -### Quick Start +### Option A: Docker Setup (recommended) -Follow these steps to run the barebones Chainlit application. +The project uses Docker Compose to manage the PostgreSQL database. The configuration for the database is stored in the `docker-compose.yml` file, and the environment variables are stored in the `.env` file. + +Follow these steps to run the complete application in Docker. 1. Clone the repository: ```bash @@ -26,71 +37,93 @@ Follow these steps to run the barebones Chainlit application. ```bash cd reactome_chatbot ``` -3. Install dependencies using Poetry: - ```bash - poetry install - ``` -4. Verify your `PYTHONPATH` environment variable includes `./src`: - ```bash - echo $PYTHONPATH - # ./src - ``` -5. List embeddings available for download: - ```bash - ./bin/embeddings_manager ls-remote - ``` -6. Install your chosen embeddings: - ```bash - ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX - ``` -7. Run the Chainlit application: - ``` - chainlit run bin/chat-chainlit.py -w - ``` -8. Access the app at http://localhost:8000 🎉 - -### Docker Setup - -The project uses Docker Compose to manage the PostgreSQL database. The configuration for the database is stored in the `docker-compose.yml` file, and the environment variables are stored in the `.env` file. - -Follow these steps to run the complete application in Docker. - -1. Create a copy of the `env_template` file and name it `.env`: +3. Create a copy of the `env_template` file and name it `.env`: ```bash cp env_template .env ``` -2. Configure the application by editing environment variables in `.env`: +4. Configure the application by editing environment variables in `.env`: - `OPENAI_API_KEY`: add your OpenAI key. - `CLOUDFLARE_SECRET_KEY`: keep blank to disable captcha. - - `CHAINLIT_IMAGE=reactome-chatbot`: set this to use your local docker build. - - Use the following variables to configure Auth0: + - `CHAINLIT_IMAGE=reactome-chatbot`: set this to use your **local docker build**. + - Use the following variables to configure Auth0 (optional): + This will enable Chainlit user-login and chat history. ``` OAUTH_AUTH0_CLIENT_ID OAUTH_AUTH0_CLIENT_SECRET OAUTH_AUTH0_DOMAIN ``` -3. List embeddings available for download: +5. List embeddings available for download: ```bash docker compose run --rm chainlit /bin/bash -c "./bin/embeddings_manager ls-remote" ``` -4. Install your chosen embeddings: +6. Install your chosen embeddings: ```bash docker compose run --rm chainlit /bin/bash -c "./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX" ``` -5. Build the Docker image (do this every time you make local changes): +7. Build the Docker image (do this every time you make **local changes**): ```bash docker build -t reactome-chatbot . ``` -6. Start the Chainlit application and PostgrSQL database in Docker containers: +8. Start the Chainlit application and PostgrSQL database in Docker containers: ```bash docker-compose up # To run it in the background, use: # docker-compose up -d ``` -7. Access the app at http://localhost:8000 🎉 +9. Access the app at http://localhost:8000 🎉 +### Using Prebuilt Docker image (faster) + +Clone and navigate to the project repository. Then in your `.env` file set the required keys as in normal docker setup and set: +``` +CHAINLIT_IMAGE=public.ecr.aws/reactome/reactome-chatbot:2044791 +``` +The part after `:` can be set to any commit ID from the 'main' branch. + +Then run: +```bash +docker compose up + +# Nw you don't need to build the image locally +``` +Access the app at http://localhost:8000 🎉 + +### Option B: Quick Start +>**NOTE:** The `main` branch no longer supports the barebones method of running the application. The steps below are for reference. For running the current application, use **Option A** with docker setup instead. + +The steps to run the barebones Chainlit application. + +1. Clone the repository: + ```bash + git clone https://github.com/reactome/reactome_chatbot.git + ``` +2. Navigate to the project directory: + ```bash + cd reactome_chatbot + ``` +3. Install dependencies using Poetry: + ```bash + poetry install + ``` +4. Verify your `PYTHONPATH` environment variable includes `./src`: + ```bash + echo $PYTHONPATH + # ./src + ``` +5. List embeddings available for download: + ```bash + ./bin/embeddings_manager ls-remote + ``` +6. Install your chosen embeddings: + ```bash + ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX + ``` +7. Run the Chainlit application: + ``` + chainlit run bin/chat-chainlit.py -w + ``` +8. Access the app at http://localhost:8000 🎉 ## Embeddings & Documents Bundles @@ -104,6 +137,10 @@ All aspects of generating, managing, uploading, and retrieving embeddings bundle - Basic usage is covered in the **_Quick Start_** guide above. - See the [Embeddings Manager documentation](docs/embeddings_manager.md) for more information. +## Troubleshooting + +- "Docker build is taking hours" + - Use prebuilt docker image ## Developers From 758e5312737f05587319dac09dd3400741dc78b0 Mon Sep 17 00:00:00 2001 From: Ehsanstp <142738825+Ehsanstp@users.noreply.github.com> Date: Thu, 26 Mar 2026 00:04:34 +0600 Subject: [PATCH 2/4] Fix formatting issues in README.md Corrected formatting and punctuation in README.md for clarity. --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6417ee7..3278192 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ Follow these steps to run the complete application in Docker. 4. Configure the application by editing environment variables in `.env`: - `OPENAI_API_KEY`: add your OpenAI key. - `CLOUDFLARE_SECRET_KEY`: keep blank to disable captcha. - - `CHAINLIT_IMAGE=reactome-chatbot`: set this to use your **local docker build**. + - `CHAINLIT_IMAGE=reactome-chatbot`: set this to use your local docker build. - Use the following variables to configure Auth0 (optional): + This will enable Chainlit user-login and chat history. ``` @@ -79,7 +79,7 @@ Clone and navigate to the project repository. Then in your `.env` file set the r ``` CHAINLIT_IMAGE=public.ecr.aws/reactome/reactome-chatbot:2044791 ``` -The part after `:` can be set to any commit ID from the 'main' branch. +The part after `:` can be set to any commit ID from the `main` branch. Then run: ```bash @@ -142,6 +142,10 @@ All aspects of generating, managing, uploading, and retrieving embeddings bundle - "Docker build is taking hours" - Use prebuilt docker image +- "An error occurred (AccessDenied) +when calling the ListObjects operation: Access Denied when `./bin/embeddings_manager ls-remote` is called." + - Use `./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX`, or directly install any embedding using available model in the format `/` and a compatible released Reactome version. + ## Developers ### Code Quality From 16b0238b6a52ef1b16b6edf4f4b61aee5811445e Mon Sep 17 00:00:00 2001 From: Ehsanstp <142738825+Ehsanstp@users.noreply.github.com> Date: Thu, 26 Mar 2026 15:09:21 +0600 Subject: [PATCH 3/4] Revise README for installation and troubleshooting clarity Updated installation instructions for Windows, including WSL2 requirements and Docker setup. Clarified troubleshooting issues related to Docker builds and access errors. --- README.md | 72 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 3278192..3ab2181 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,21 @@ The Reactome ChatBot is an interactive tool that provides information about biol ## Installation ### Supported Operating Systems -- **Linux** -- **MacOS** -- **Windows** - Windows 10 version 2004 or higher, or Windows 11 - - Windows users must use [WSl](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). - - **WSL version 2.1.5 or later** is required. To check your version: `wsl --version` +- 64-bit Unix Systems + - **Linux** (x64) + - **macOS** (Intel x64; Apple Silicon requires emulations) + +- **Windows** (not supported natively) + - Windows 10 version 2004 or higher, or Windows 11 + - Windows users must use [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install) (Windows Subsystem for Linux). + - **WSL version 2.1.5 or later** is required. Check your version with: + ```bash + wsl --version + ``` + If outdated, update with: + ```bash + wsl --update + ``` - Recommended distribution: Ubuntu ### Prerequisites @@ -21,7 +31,7 @@ The Reactome ChatBot is an interactive tool that provides information about biol - **Requirements for running the complete application:** + [Docker](https://docs.docker.com/get-started/get-docker/) + [Docker Compose](https://docs.docker.com/compose/install/) - + Windows users should install [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) with WSL 2 backend enabled (Settings → Resources → WSL integration) + + [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) for Windows users with WSL2 backend enabled (Settings → Resources → WSL integration) ### Option A: Docker Setup (recommended) @@ -45,7 +55,7 @@ Follow these steps to run the complete application in Docker. - `OPENAI_API_KEY`: add your OpenAI key. - `CLOUDFLARE_SECRET_KEY`: keep blank to disable captcha. - `CHAINLIT_IMAGE=reactome-chatbot`: set this to use your local docker build. - - Use the following variables to configure Auth0 (optional): + - Use the following variables to configure Auth0: + This will enable Chainlit user-login and chat history. ``` OAUTH_AUTH0_CLIENT_ID @@ -56,20 +66,20 @@ Follow these steps to run the complete application in Docker. ```bash docker compose run --rm chainlit /bin/bash -c "./bin/embeddings_manager ls-remote" ``` -6. Install your chosen embeddings: +6. Install your chosen embeddings (replace `ReleaseXX` with any valid release, e.g. Release89): ```bash docker compose run --rm chainlit /bin/bash -c "./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX" ``` -7. Build the Docker image (do this every time you make **local changes**): +7. Build the Docker image (do this every time you make local changes): ```bash docker build -t reactome-chatbot . ``` 8. Start the Chainlit application and PostgrSQL database in Docker containers: ```bash - docker-compose up + docker compose up # To run it in the background, use: - # docker-compose up -d + # docker compose up -d ``` 9. Access the app at http://localhost:8000 🎉 @@ -85,7 +95,7 @@ Then run: ```bash docker compose up -# Nw you don't need to build the image locally +# Now you don't need to build the image locally ``` Access the app at http://localhost:8000 🎉 @@ -111,19 +121,24 @@ The steps to run the barebones Chainlit application. echo $PYTHONPATH # ./src ``` -5. List embeddings available for download: + Set `PYTHONPATH` to `src` if not already set: + ```bash + export PYTHONPATH=./src + ``` + and then verify using `echo` +6. List embeddings available for download: ```bash ./bin/embeddings_manager ls-remote ``` -6. Install your chosen embeddings: +7. Install your chosen embeddings: ```bash ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX ``` -7. Run the Chainlit application: +8. Run the Chainlit application: ``` chainlit run bin/chat-chainlit.py -w ``` -8. Access the app at http://localhost:8000 🎉 +9. Access the app at http://localhost:8000 🎉 ## Embeddings & Documents Bundles @@ -137,14 +152,29 @@ All aspects of generating, managing, uploading, and retrieving embeddings bundle - Basic usage is covered in the **_Quick Start_** guide above. - See the [Embeddings Manager documentation](docs/embeddings_manager.md) for more information. + ## Troubleshooting -- "Docker build is taking hours" - - Use prebuilt docker image +>**ISSUE: "The Docker build is taking an unusually long time"** + - Use prebuilt docker image. + + +>**ISSUE: "Docker image: Build vs Prebuilt"** + - Building the Docker image locally can take a significant amount of time - potentially hours, especially on Windows. If you are not making any changes to the codebase, i.e. modyfying any code, you can use the publicly available prebuilt image. + + +>**ISSUE: "Why do I get `{"detail":"Not Found"}` when I try to access the Chatbot at http://localhost:8000?"** + - Use http://localhost:8000/chat + + +>**ISSUE: " `An error occurred (AccessDenied) when calling the ListObjects operation: Access Denied` when `./bin/embeddings_manager ls-remote` is called."** + - If you don't have an AWS authentication use `install` command to fetch embeddings instead + ```bash + ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX + ``` + Or install an embedding directly in the format `/` specifying a model and a compatible released Reactome version. + > Example: openai/text-embedding-3-large/reactome/Release89 -- "An error occurred (AccessDenied) -when calling the ListObjects operation: Access Denied when `./bin/embeddings_manager ls-remote` is called." - - Use `./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX`, or directly install any embedding using available model in the format `/` and a compatible released Reactome version. ## Developers From 6906376e2a7f2d8752322cc8989685f664a55ae0 Mon Sep 17 00:00:00 2001 From: Ehsanstp <142738825+Ehsanstp@users.noreply.github.com> Date: Thu, 26 Mar 2026 15:20:01 +0600 Subject: [PATCH 4/4] Final changes Updated note to a warning regarding the barebones method. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3ab2181..666e3d6 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ docker compose up Access the app at http://localhost:8000 🎉 ### Option B: Quick Start ->**NOTE:** The `main` branch no longer supports the barebones method of running the application. The steps below are for reference. For running the current application, use **Option A** with docker setup instead. +>**WARNING:** The `main` branch no longer supports the barebones method of running the application. The steps below are for reference. For running the current application, use **Option A** with docker setup instead. The steps to run the barebones Chainlit application.