Merge pull request #34 from IBM/update-gcr-docs

Update GCR docs

Author: crivetimihai

.gitignore

@@ -1,3 +1,4 @@
+.env.gcr
 packages-lock.json
 packages.json
 node_modules/

docs/docs/deployment/google-cloud-run.md

@@ -35,8 +35,26 @@ Install the Google Cloud SDK:
 
 * **Debian/Ubuntu:**
 
+> These steps also apply to WSL2 running Ubuntu.
+
   ```bash
-  sudo apt-get install google-cloud-cli
+  # Update package lists and install necessary utilities
+  sudo apt-get update
+  sudo apt-get install -y apt-transport-https ca-certificates gnupg curl
+
+  # Import the Google Cloud public key securely
+  # This is for newer distributions (Debian 9+ or Ubuntu 18.04+).
+  curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
+
+  # Add the Google Cloud SDK distribution URI as a package source
+  # This is for newer distributions, ensuring packages are signed by the key we just added.
+  echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
+
+  # Update your package lists again to recognize the new repository
+  sudo apt-get update
+
+  # Install the Google Cloud CLI
+  sudo apt-get install -y google-cloud-cli
   ```
 
 * **Windows (PowerShell):**
@@ -57,11 +75,18 @@ Authenticate with your Google Cloud account:
 gcloud auth login
 ```
 
+Set a project ID:
+
+```bash
+gcloud config set project PROJECT_ID
+```
+
 ### 2. Enable Required APIs
 
 Enable the necessary Google Cloud APIs:
 
 ```bash
+# This might take a minute..
 gcloud services enable \
   run.googleapis.com \
   sqladmin.googleapis.com \
@@ -87,6 +112,35 @@ Prepare the following environment variables:
 | `CACHE_TYPE`          | Set to `redis` for production environments            |
 | `PORT`                | Port number the application listens on (e.g., `4444`) |
 
+Consider creating a `.env.gcr` file where you will record the various settings used during deployment.
+
+```bash
+# ─── Google Cloud project ───────────────────────────────────
+PROJECT_ID=
+REGION=us-central1
+SERVICE_NAME=mcpgateway
+
+# ─── Authentication ─────────────────────────────────────────
+JWT_SECRET_KEY=
+BASIC_AUTH_USER=
+BASIC_AUTH_PASSWORD=
+AUTH_REQUIRED=true
+
+# ─── Cloud SQL (PostgreSQL) ─────────────────────────────────
+SQL_INSTANCE=mcpgw-db
+SQL_REGION=us-central1
+DATABASE_URL=postgresql://postgres:<PASSWORD>@<SQL_IP>:5432/mcpgw
+
+# ─── Memorystore (Redis) ────────────────────────────────────
+REDIS_INSTANCE=mcpgw-redis
+REDIS_REGION=us-central1
+REDIS_URL=redis://<REDIS_IP>:6379/0
+CACHE_TYPE=redis
+
+# ─── Application ────────────────────────────────────────────
+PORT=4444
+```
+
 ---
 
 ## ⚙️ Setup Steps
@@ -96,8 +150,10 @@ Prepare the following environment variables:
 Create a PostgreSQL instance using the `db-f1-micro` tier for cost efficiency:
 
 ```bash
+# POSTGRES_16 and POSTGRES_17 default to Enterprise Plus; adding --edition=ENTERPRISE lets you pick db-f1-micro
 gcloud sql instances create mcpgw-db \
   --database-version=POSTGRES_17 \
+  --edition=ENTERPRISE \
   --tier=db-f1-micro \
   --region=us-central1
 ```
@@ -148,32 +204,131 @@ gcloud redis instances describe mcpgw-redis \
 
 ### 3. Deploy to Google Cloud Run
 
-Deploy the MCP Gateway container with minimal resource allocation:
+Cloud Run only accepts container images that live in Artifact Registry or the older Container Registry endpoints; anything pulled from the public internet (for example ghcr.io) must first be proxied or copied into Artifact Registry.
+
+
+#### Set Your Project ID
+
+Begin by setting your Google Cloud project ID as an environment variable:
+
+```bash
+export PROJECT_ID="your-project-id"
+```
+
+Replace `"your-project-id"` with your actual Google Cloud project ID.
+
+#### Enable Required APIs
+
+Ensure that the necessary Google Cloud APIs are enabled:
+
+```bash
+gcloud services enable artifactregistry.googleapis.com
+```
+
+#### Create a Remote Repository
+
+Set up a remote repository in Artifact Registry that proxies GitHub Container Registry (GHCR):
+
+```bash
+gcloud artifacts repositories create ghcr-remote \
+  --project=$PROJECT_ID \
+  --repository-format=docker \
+  --location=us-central1 \
+  --description="Proxy for GitHub Container Registry" \
+  --mode=remote-repository \
+  --remote-docker-repo=https://ghcr.io
+```
+
+#### Retrieve Cloud SQL Instance Connection Name
+
+```bash
+gcloud sql instances describe mcpgw-db \
+  --format="value(connectionName)"
+```
+
+It will output something like this:
+
+```
+your-project-id:us-central1:mcpgw-db
+```
+
+
+#### Allow ingress to your database.
+
+Consider only allowing the Cloud Run IP range.
+
+```bash
+gcloud sql instances patch mcpgw-db \
+  --authorized-networks=0.0.0.0/0
+```
+
+#### Deploy the MCP Gateway container with minimal resource allocation:
 
 ```bash
 gcloud run deploy mcpgateway \
-  --image=ghcr.io/ibm/mcp-context-forge:latest \
+  --image=us-central1-docker.pkg.dev/$PROJECT_ID/ghcr-remote/ibm/mcp-context-forge:latest
   --region=us-central1 \
   --platform=managed \
   --allow-unauthenticated \
   --port=4444 \
   --cpu=1 \
-  --memory=256Mi \
+  --memory=512i \
   --max-instances=1 \
   --set-env-vars=\
-JWT_SECRET_KEY=your-secret,\
+JWT_SECRET_KEY=jwt-secret-key,\
 BASIC_AUTH_USER=admin,\
 BASIC_AUTH_PASSWORD=changeme,\
 AUTH_REQUIRED=true,\
 DATABASE_URL=postgresql://postgres:mysecretpassword@<SQL_IP>:5432/mcpgw,\
 REDIS_URL=redis://<REDIS_IP>:6379/0,\
-CACHE_TYPE=redis
+CACHE_TYPE=redis,\
+HOST=0.0.0.0,\
+GUNICORN_WORKERS=1
 ```
 
 > **Replace `<SQL_IP>` and `<REDIS_IP>`** with the actual IP addresses obtained from the previous steps.
+> Do not leave out the HOST=0.0.0.0 to ensure the container listens on all ports, or the container engine won't be able to reach the container.
+> Setting the number of GUNICORN_WORKERS lets you control how much memory the service consumes.
+
+#### Check the logs
 
+```bash
+gcloud run services logs read mcpgateway --region=us-central1
+```
 ---
 
+#### Check that the database is created:
+
+You can use any PostgreSQL client, such as `psql`. You should see the list of tables when using `dt;`
+
+```bash
+psql postgresql://postgres:mysecretpassword@<SQL_IP>:5432/mcpgw
+
+mcpgw=> \dt;
+                    List of relations
+ Schema |             Name             | Type  |  Owner
+--------+------------------------------+-------+----------
+ public | gateways                     | table | postgres
+ public | mcp_messages                 | table | postgres
+ public | mcp_sessions                 | table | postgres
+ public | prompt_gateway_association   | table | postgres
+ public | prompt_metrics               | table | postgres
+ public | prompts                      | table | postgres
+ public | resource_gateway_association | table | postgres
+ public | resource_metrics             | table | postgres
+ public | resource_subscriptions       | table | postgres
+ public | resources                    | table | postgres
+ public | server_metrics               | table | postgres
+ public | server_prompt_association    | table | postgres
+ public | server_resource_association  | table | postgres
+ public | server_tool_association      | table | postgres
+ public | servers                      | table | postgres
+ public | tool_gateway_association     | table | postgres
+ public | tool_metrics                 | table | postgres
+ public | tools                        | table | postgres
+(18 rows)
+```
+
 ## 🔒 Authentication and Access
 
 ### Generate a JWT Bearer Token
@@ -182,7 +337,7 @@ Use the MCP Gateway container to generate a JWT token:
 
 ```bash
 docker run -it --rm ghcr.io/ibm/mcp-context-forge:latest \
-  python3 -m mcpgateway.utils.create_jwt_token -u admin
+  python3 -m mcpgateway.utils.create_jwt_token -u admin --secret jwt-secret-key
 ```
 
 Export the token as an environment variable:
@@ -193,12 +348,18 @@ export MCPGATEWAY_BEARER_TOKEN=<paste-token-here>
 
 ### Perform Smoke Tests
 
-Test the `/health` and `/tools` endpoints:
+Test the `/health`, `/version`, and `/tools` endpoints:
 
 ```bash
+# Check that the service is healthy
 curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      https://<your-cloud-run-url>/health
 
+# Check that version reports the version and show Postgres/Redis as connected
+curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
+     https://<your-cloud-run-url>/health
+
+# Check that tools return an empty list []
 curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
      https://<your-cloud-run-url>/tools
 ```
@@ -211,24 +372,11 @@ curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
 
 ### View Logs via CLI
 
-Tail real-time logs:
+Tailing real-time logs requires `google-cloud-cli-log-streaming`. Ex: `sudo apt-get install google-cloud-cli-log-streaming`:
 
 ```bash
-gcloud run services logs tail mcpgateway --region us-central1
+gcloud beta run services logs tail mcpgateway --region=us-central1
 ```
-
-Read recent logs:
-
-```bash
-gcloud run services logs read mcpgateway --limit 50
-```
-
-Filter logs by severity:
-
-```bash
-gcloud run services logs read mcpgateway --severity=ERROR
-```
-
 ### Access Logs via Console
 
 Navigate to the [Cloud Run Console](https://console.cloud.google.com/run) and select your service to view logs and metrics.