Fix #12: Update Prerequisites and Installation Instructions in README.md (#25)

- Updated Prerequisites section with clearer SSL certificate options
- Added detailed security group configuration for different deployment scenarios
- Replaced manual Docker commands with build_and_run.sh script usage
- Added Docker Compose architecture explanation with separate containers
- Updated environment configuration steps using .env.template
- Enhanced authentication section with Cognito vs username/password options
- Updated HTTPS configuration for production deployments
- Made instructions more accessible for entry-level developers

Addresses all tasks in issue #12:
✅ Prerequisites section explains SSL options and security group requirements
✅ Installation steps use build_and_run.sh instead of manual Docker commands
✅ Environment configuration is clearly explained
✅ Instructions are accessible to entry-level developers

Author: aarora79

README.md

@@ -183,135 +183,156 @@ flowchart TB
 
 ## Prerequisites
 
-*   An Amazon EC2 machine (`ml.t3.2xlarge`) with a standard Ubuntu AMI for running this solution.
-*   An SSL cert for securing the communication to the Gateway. _This Gateway uses a self-signed cert by default and is also available over HTTP_. 
-*   One of the example MCP servers packaged in this repo uses the [`Polygon`](https://polygon.io/stocks) API for stock ticker data. Get an API key from [here](https://polygon.io/dashboard/signup?redirect=%2Fdashboard%2Fkeys). The server will still start without the API key but you will get a 401 Unauthorized error when using the tools provided by this server.
-*   Setup authentication using Amazon Cognito as per instructions [here](docs/auth.md).
+*   **Amazon EC2 Instance:** An Amazon EC2 machine (`ml.t3.2xlarge`) with a standard Ubuntu AMI for running this solution.
 
-## Installation
+*   **SSL Certificate Options:**
+    - **Production Deployments:** SSL certificate is preferred for secure communication to the Gateway
+    - **Testing/Development:** Can use localhost when running on EC2, or EC2 domain name for testing
+    - **Default Configuration:** Gateway is available over HTTP for development
 
-### Installation on EC2
+*   **Security Group Configuration:** Configure your EC2 security group based on your deployment scenario:
+    - **HTTPS with SSL certificate:** Only port **443** needs to be opened
+    - **HTTP with EC2 domain name:** Only port **80** needs to be opened
+    - **HTTP with localhost (port forwarding):** Ports **80**, **7860**, and **8888** need to be opened
 
-The Gateway and the Registry are available as a Docker container. The package includes a couple of test MCP servers as well.
+*   **External API Keys (Optional):** One of the example MCP servers uses the [`Polygon`](https://polygon.io/stocks) API for stock ticker data. Get an API key from [here](https://polygon.io/dashboard/signup?redirect=%2Fdashboard%2Fkeys). The server will still start without the API key but you will get a 401 Unauthorized error when using the tools provided by this server.
 
-1.  **Clone the repository:**
-    ```bash
-    git clone https://github.com/agentic-community/mcp-gateway-registry.git
-    cd mcp-gateway
-    ```
+*   **Authentication Setup:** Setup authentication using Amazon Cognito as per instructions [here](docs/auth.md).
 
-1. **Create local directories for saving MCP server logs and run-time data:**
-    ```bash
-    sudo mkdir -p /opt/mcp-gateway/servers
-    sudo cp -r registry/servers /opt/mcp-gateway/
-    sudo mkdir /var/log/mcp-gateway
-    ```
+## Installation
 
-1. **Build the Docker container to run the Gateway and Registry:**
+### Installation on EC2
 
-    ```bash
-    docker build -t mcp-gateway .
+The Gateway and Registry are deployed using Docker Compose with separate containers for each service, providing a scalable and maintainable architecture.
 
-    ```
+#### Docker Compose Architecture
 
-1. **Run the container:**
+The deployment includes these containers:
+- **Nginx Reverse Proxy**: Routes requests to appropriate services and handles SSL termination
+- **Auth Server**: Handles authentication with Amazon Cognito and GitHub OAuth
+- **Registry MCP Server**: Provides service discovery, management, and the web UI
+- **Example MCP Servers**:
+  - Current Time server (port 8000)
+  - Financial Info server (port 8001)
+  - Real Server Fake Tools server (port 8002)
+  - MCP Gateway server (port 8003)
 
-    ```bash
-    # environment variables
-    export ADMIN_USER=admin
-    export ADMIN_PASSWORD=your-admin-password
-    export POLYGON_API_KEY=your-polygon-api-key
-    # stop any previous instance
-    docker stop mcp-gateway-container && docker rm mcp-gateway-container 
-    docker run -p 80:80 -p 443:443 -p 7860:7860 -p 8888:8888 \
-    -e ADMIN_USER=$ADMIN_USER \
-    -e ADMIN_PASSWORD=$ADMIN_PASSWORD \
-    -e POLYGON_API_KEY=$POLYGON_API_KEY \
-    -e SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') \
-    -v /var/log/mcp-gateway:/app/logs \
-    -v /opt/mcp-gateway/servers:/app/registry/servers \
-    --name mcp-gateway-container mcp-gateway
-    ```
-
-    You should see some of the following traces show up on the screen (the following is an excerpt, some traces have been omitted for clarity).
+#### Quick Start Installation
 
+1.  **Clone the repository:**
     ```bash
-    Nginx config regeneration successful.
-    Starting background health check task...
-    Running periodic health checks (Interval: 300s)...
-    Performing periodic check for enabled service: /fininfo
-    Setting status to 'checking' for /fininfo (http://localhost:8002/)...
-    INFO:     Application startup complete.
-    INFO:     Uvicorn running on http://0.0.0.0:7860 (Press CTRL+C to quit)
-    INFO:     127.0.0.1:40132 - "HEAD /sse HTTP/1.1" 200 OK
-    Health check successful for /fininfo (http://localhost:8002/).
-    Final health status for /fininfo: healthy
-    Performing periodic check for enabled service: /currenttime
-    Setting status to 'checking' for /currenttime (http://0.0.0.0:8001/)...
-    INFO:     127.0.0.1:54256 - "HEAD /sse HTTP/1.1" 200 OK
-    Health check successful for /currenttime (http://0.0.0.0:8001/).
-    Final health status for /currenttime: healthy
-    Finished periodic health checks. Current status map: {'/fininfo': 'healthy', '/currenttime': 'healthy'}
-    No status changes detected in periodic check, skipping broadcast.
-    Starting Nginx in the background...
-    Nginx started. Keeping container alive...
+    git clone https://github.com/agentic-community/mcp-gateway-registry.git
+    cd mcp-gateway-registry
     ```
 
-1. **Navigate to [`http://localhost:7860`](http://localhost:7860) access the Registry**
-
-    ![MCP Registry](docs/img/registry.png)
-
-1. **View logs from the Registry and the built-in MCP servers:**
-   Logs are available on the local machine in the `/var/log/mcp-gateway` directory.
+2. **Configure environment variables:**
+   ```bash
+   # Copy the template and edit with your values
+   cp .env.template .env
+   nano .env  # or use your preferred editor
    ```
-   tail -f /var/log/mcp-gateway/*
+   
+   **Required configuration in `.env`:**
+   - `ADMIN_PASSWORD`: Set to a secure password (replace "your-secure-password-here")
+   - `COGNITO_USER_POOL_ID`: Your AWS Cognito User Pool ID
+   - `COGNITO_CLIENT_ID`: Your Cognito App Client ID
+   - `COGNITO_CLIENT_SECRET`: Your Cognito App Client Secret
+   - `AWS_REGION`: AWS region where your Cognito User Pool is located
+   
+   **Optional configuration:**
+   - `POLYGON_API_KEY`: For financial data tools (get from [Polygon.io](https://polygon.io/dashboard/signup))
+   - `SECRET_KEY`: Auto-generated by build script if not provided
+
+3. **Deploy with the build and run script:**
+   ```bash
+   ./build_and_run.sh
+   ```
+   
+   The script will:
+   - Validate your `.env` configuration
+   - Generate `SECRET_KEY` if not provided
+   - Build all Docker images using Docker Compose
+   - Start all services in the correct order
+   - Verify service health and display status
+
+4. **Access the Registry:**
+   Navigate to `http://localhost:7860` and you will have two authentication options:
+   
+   **Option 1 - Amazon Cognito (Recommended for Production):**
+   - Click "Login with Cognito" to authenticate via your configured Cognito User Pool
+   - Access permissions will be based on the Cognito group you are a member of
+   - Provides fine-grained access control based on your organizational roles
+   
+   **Option 2 - Username/Password (Testing Only):**
+   - Use the traditional login with:
+     - **Username:** Value of `ADMIN_USER` (default: admin)
+     - **Password:** Value of `ADMIN_PASSWORD` from your `.env` file
+   - Provides admin access by default
+   - **Note:** This approach should only be used for testing and will soon require setting `ENABLE_DEV_MODE=true` in your `.env` file
+
+   ![MCP Registry](docs/img/registry.png)
+
+#### Post-Installation
+
+1. **View logs from all services:**
+   ```bash
+   # View logs from all services
+   docker-compose logs -f
+   
+   # View logs from a specific service
+   docker-compose logs -f registry
+   docker-compose logs -f auth-server
    ```
 
-1. **View MCP server metadata:**
-   Metadata about all MCP servers connected to the Registry is available in `/opt/mcp-gateway/servers` directory. The metadata includes information gathered from `ListTools` as well as information provided while registering the server.
+2. **View MCP server metadata:**
+   Metadata about all MCP servers is available in `/opt/mcp-gateway/servers` directory. The metadata includes information gathered from `ListTools` as well as information provided during server registration.
 
-1. **Test the Gateway and Registry with the sample Agent and test suite:**
-   The repo includes a test agent that can connect to the Registry to discover tools and invoke them to do interesting tasks. This functionality can be invoked either standalone or as part of a test suite.
+3. **Test the Gateway and Registry:**
+   The repo includes a test agent that can connect to the Registry to discover tools and invoke them:
 
-   ```{.python}
+   ```bash
    python agents/agent.py --mcp-registry-url http://localhost/mcpgw/sse --message "what is the current time in clarksburg, md"
 
    # With Strands agent
    # python agents/strands_agent.py --mcp-registry-url http://localhost/mcpgw/sse --message "what is the current time in clarksburg, md"
    ```
 
-   You can also run the full test suite and get a handy agent evaluation report. This test suite exercises the Registry functionality as well as tests the multiple built-in MCP servers provided by the Gateway.
+   You can also run the full test suite:
 
-   ```{.python}
+   ```bash
    python agents/test_suite.py --mcp-registry-url http://localhost/mcpgw/sse
    # With Strands agent
    # python agents/test_suite.py --mcp-registry-url http://localhost/mcpgw/sse --use-strands
    ```
 
-   The result of the tests suites are available in the agents/test_results folder. It contains an accuracy.json, a summary.json, a logs folder and a raw_data folder that contains the verbose output from the agent. The test suite uses an LLM as a judge to evaluate the results for accuracy and tool usage quality.
+   Test results are available in the `agents/test_results` folder with accuracy metrics and detailed logs.
 
 #### Running the Gateway over HTTPS
 
-1. Enable access to TCP port 443 from the IP address of your MCP client (your laptop, or anywhere) in the inbound rules in the security group associated with your EC2 instance.
+For production deployments with SSL certificates:
 
-1. You would need to have an HTTPS certificate and private key to proceed. Let's say you use `your-mcp-gateway.com` as the domain for your MCP server then you will need an SSL cert for `your-mcp-gateway.com` and MCP servers behind the Gateway will be accessible to MCP clients as `https://your-mcp-gateway.com/mcp-server-name/sse`.
+1. **Configure Security Group:** Enable access to TCP port 443 from the IP addresses of your MCP clients in the inbound rules of your EC2 instance's security group.
 
-1. Rebuild the container using the same command line as before.
+2. **Prepare SSL Certificates:** You need an HTTPS certificate and private key for your domain. For example, if you use `your-mcp-gateway.com` as the domain, you'll need an SSL certificate for `your-mcp-gateway.com`. MCP servers behind the Gateway will be accessible as `https://your-mcp-gateway.com/mcp-server-name/sse`.
 
-1. Run the container with the `-v` switch to map the local folder containing the cert and the private key to the container. Replace `/path/to/certs/` and `/path/private` as appropriate in the command provided below.
+3. **Place SSL Certificates:** Copy your SSL certificates to `/home/ubuntu/ssl_data/` on your EC2 instance:
+   ```bash
+   sudo mkdir -p /home/ubuntu/ssl_data/certs
+   sudo mkdir -p /home/ubuntu/ssl_data/private
+   # Copy your certificate and private key files to these directories
+   ```
 
-    ```bash
-    docker run -p 80:80 -p 443:443 -p 7860:7860 -p 8888:8888 \
-      -e ADMIN_USER=$ADMIN_USER \
-      -e ADMIN_PASSWORD=$ADMIN_PASSWORD \
-      -e POLYGON_API_KEY=$POLYGON_API_KEY \
-      -e SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') \
-      -v /path/to/certs:/etc/ssl/certs \
-      -v /path/to/private:/etc/ssl/private \
-      -v /var/log/mcp-gateway:/app/logs \
-      -v /opt/mcp-gateway/servers:/app/registry/servers \
-      --name mcp-gateway-container   mcp-gateway
-    ```
+4. **Deploy with HTTPS:** Run the deployment script as normal:
+   ```bash
+   ./build_and_run.sh
+   ```
+   
+   The Docker Compose configuration automatically mounts the SSL certificates from `/home/ubuntu/ssl_data` to the appropriate container paths.
+
+5. **Access via HTTPS:** Your services will be available at:
+   - Main interface: `https://your-domain.com`
+   - Registry API: `https://your-domain.com:7860` (if port 7860 is opened in security group)
+   - MCP servers: `https://your-domain.com/server-name/sse`
 
 ### Installation on EKS