reactome · Ehsanstp · Mar 25, 2026 · Mar 25, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/README.md b/README.md
@@ -5,6 +5,24 @@ The Reactome ChatBot is an interactive tool that provides information about biol
 
 ## Installation
 
+### Supported Operating Systems
+- 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
 
 - **Minimum requirements:**
@@ -13,10 +31,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/)
+    + [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) for Windows users with WSL2 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,40 +47,11 @@ 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.
@@ -70,27 +62,83 @@ Follow these steps to run the complete application in Docker.
         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 (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"
     ```
-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
+    docker compose up
 
     # To run it in the background, use:
-    # docker-compose up -d
+    # 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
+
+# Now you don't need to build the image locally
+```
+Access the app at http://localhost:8000 🎉
 
+### Option B: Quick Start
+>**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.
+
+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
+    ```
+    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
+    ```
+7. Install your chosen embeddings:
+    ```bash
+    ./bin/embeddings_manager install openai/text-embedding-3-large/reactome/ReleaseXX
+    ```
+8. Run the Chainlit application:
+    ```
+    chainlit run bin/chat-chainlit.py -w
+    ```
+9. Access the app at http://localhost:8000 🎉
 
 ## Embeddings & Documents Bundles
 
@@ -105,6 +153,29 @@ All aspects of generating, managing, uploading, and retrieving embeddings bundle
 - See the [Embeddings Manager documentation](docs/embeddings_manager.md) for more information.
 
 
+## Troubleshooting
+
+>**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 `<modelorg>/<model>` specifying a model and a compatible released Reactome version.
+    > Example: openai/text-embedding-3-large/reactome/Release89
+
+
 ## Developers
 
 ### Code Quality