Skip to content

Commit 9f86e46

Browse files
crivetimihaicrivetimihai
authored
Merge pull request #31 from IBM/30-add-google-cloud-run-docs-and-action
Add deployment information for Google Cloud Run - closes #30
2 parents 842ace0 + 207f755 commit 9f86e46

File tree

10 files changed

+338
-7
lines changed

10 files changed

+338
-7
lines changed

‎.github/workflows/google-cloud-run.yml.inactive

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# ===============================================================
2+
# ☁️ MCP Gateway ▸ Build, Cache & Deploy to Google Cloud Run
3+
# ===============================================================
4+
#
5+
# This workflow:
6+
# • Restores / updates a local **BuildKit layer cache** ❄️
7+
# • Builds the Docker image from **Containerfile.lite** 🏗️
8+
# • Pushes the image to **Google Artifact Registry** 📤
9+
# • Deploys to **Google Cloud Run** with autoscale=1 🚀
10+
#
11+
# ---------------------------------------------------------------
12+
# Required repository **secrets**
13+
# ---------------------------------------------------------------
14+
# ┌────────────────────────┬────────────────────────────────┐
15+
# │ Secret name │ Example value │
16+
# ├────────────────────────┼────────────────────────────────┤
17+
# │ GCP_SERVICE_KEY │ JSON string for gcloud auth │
18+
# └────────────────────────┴────────────────────────────────┘
19+
#
20+
# ---------------------------------------------------------------
21+
# Required repository **variables**
22+
# ---------------------------------------------------------------
23+
# ┌────────────────────────────┬──────────────────────────────┐
24+
# │ Variable name │ Example value │
25+
# ├────────────────────────────┼──────────────────────────────┤
26+
# │ GCP_PROJECT_ID │ my-gcp-project │
27+
# │ GCP_REGION │ us-central1 │
28+
# │ GAR_REPO_NAME │ mcpgateway │
29+
# │ IMAGE_NAME │ mcpgateway │
30+
# │ CLOUD_RUN_SERVICE │ mcpgateway │
31+
# │ CLOUD_RUN_PORT │ "4444" │
32+
# └────────────────────────────┴──────────────────────────────┘
33+
#
34+
# Triggers:
35+
# • Every push to `main`
36+
# ===============================================================
37+
38+
name: Deploy to Google Cloud Run
39+
40+
on:
41+
push:
42+
branches: ["main"]
43+
44+
permissions:
45+
contents: read
46+
47+
env:
48+
GITHUB_SHA: ${{ github.sha }}
49+
CACHE_DIR: /tmp/.buildx-cache
50+
51+
GCP_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
52+
GCP_REGION: ${{ vars.GCP_REGION }}
53+
54+
GAR_REPO_NAME: ${{ vars.GAR_REPO_NAME }}
55+
IMAGE_NAME: ${{ vars.IMAGE_NAME }}
56+
IMAGE_TAG: ${{ github.sha }}
57+
58+
CLOUD_RUN_SERVICE: ${{ vars.CLOUD_RUN_SERVICE }}
59+
CLOUD_RUN_PORT: ${{ vars.CLOUD_RUN_PORT }}
60+
61+
jobs:
62+
build-push-deploy:
63+
name: 🚀 Build, Cache, Push & Deploy
64+
runs-on: ubuntu-latest
65+
environment: production
66+
67+
steps:
68+
# -----------------------------------------------------------
69+
# 0️⃣ Checkout repository
70+
# -----------------------------------------------------------
71+
- name: ⬇️ Checkout source
72+
uses: actions/checkout@v4
73+
74+
# -----------------------------------------------------------
75+
# 1️⃣ Authenticate to Google Cloud
76+
# -----------------------------------------------------------
77+
- name: 🔐 Authenticate to Google Cloud
78+
uses: google-github-actions/auth@v1
79+
with:
80+
credentials_json: ${{ secrets.GCP_SERVICE_KEY }}
81+
82+
- name: 🧰 Set up gcloud SDK
83+
uses: google-github-actions/setup-gcloud@v1
84+
with:
85+
project_id: ${{ env.GCP_PROJECT_ID }}
86+
install_components: gcloud, docker
87+
export_default_credentials: true
88+
89+
# -----------------------------------------------------------
90+
# 2️⃣ Set up Docker Buildx + cache
91+
# -----------------------------------------------------------
92+
- name: 🛠️ Set up Docker Buildx
93+
uses: docker/setup-buildx-action@v3
94+
95+
- name: 🔄 Restore BuildKit cache
96+
uses: actions/cache@v4
97+
with:
98+
path: ${{ env.CACHE_DIR }}
99+
key: ${{ runner.os }}-buildx-${{ github.sha }}
100+
restore-keys: ${{ runner.os }}-buildx-
101+
102+
# -----------------------------------------------------------
103+
# 3️⃣ Configure Docker to use gcloud auth
104+
# -----------------------------------------------------------
105+
- name: 🔧 Configure Docker for Artifact Registry
106+
run: gcloud auth configure-docker ${{ env.GCP_REGION }}-docker.pkg.dev
107+
108+
# -----------------------------------------------------------
109+
# 4️⃣ Build & tag image
110+
# -----------------------------------------------------------
111+
- name: 🏗️ Build Docker image
112+
run: |
113+
docker buildx build \
114+
--file Containerfile.lite \
115+
--tag ${{ env.GCP_REGION }}-docker.pkg.dev/${{ env.GCP_PROJECT_ID }}/${{ env.GAR_REPO_NAME }}/${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }} \
116+
--cache-from type=local,src=${{ env.CACHE_DIR }} \
117+
--cache-to type=local,dest=${{ env.CACHE_DIR }},mode=max \
118+
--load \
119+
.
120+
121+
# -----------------------------------------------------------
122+
# 5️⃣ Push image to Artifact Registry
123+
# -----------------------------------------------------------
124+
- name: 📤 Push image to GAR
125+
run: |
126+
docker push ${{ env.GCP_REGION }}-docker.pkg.dev/${{ env.GCP_PROJECT_ID }}/${{ env.GAR_REPO_NAME }}/${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }}
127+
128+
# -----------------------------------------------------------
129+
# 6️⃣ Deploy to Cloud Run
130+
# -----------------------------------------------------------
131+
- name: 🚀 Deploy to Cloud Run
132+
run: |
133+
gcloud run deploy "$CLOUD_RUN_SERVICE" \
134+
--image $GCP_REGION-docker.pkg.dev/$GCP_PROJECT_ID/$GAR_REPO_NAME/$IMAGE_NAME:$IMAGE_TAG \
135+
--region "$GCP_REGION" \
136+
--platform managed \
137+
--allow-unauthenticated \
138+
--port "$CLOUD_RUN_PORT" \
139+
--cpu=2 \
140+
--memory=2Gi \
141+
--max-instances=1 \
142+
--set-env-vars=JWT_SECRET_KEY=your-secret,BASIC_AUTH_USER=admin,BASIC_AUTH_PASSWORD=changeme,AUTH_REQUIRED=true

‎docs/docs/deployment/.pages

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ nav:
77
- kubernetes.md
88
- openshift.md
99
- minikube.md
10+
- google-cloud-run.md
1011
- ibm-code-engine.md
1112
- aws.md
1213
- azure.md

‎docs/docs/deployment/aws.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# AWS Deployment
1+
# 🟧 AWS
22

33
MCP Gateway can be deployed to AWS using multiple container-based services:
44

‎docs/docs/deployment/azure.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Azure Deployment
1+
# 🔷 Azure
22

33
MCP Gateway can be deployed on Azure in multiple ways:
44

‎docs/docs/deployment/compose.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# 🚀 Docker Compose
1+
# 🧩 Docker Compose
22

33
Running **MCP Gateway** with **Compose** spins up a full stack (Gateway, Postgres, Redis, optional MPC servers) behind a single YAML file.
44
The Makefile detects Podman or Docker automatically, and you can override it with `COMPOSE_ENGINE=`.

‎docs/docs/deployment/container.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Container Deployment
1+
# 📦 Container Deployment
22

33
You can run MCP Gateway as a fully self-contained container. This is the recommended method for production or platform-agnostic deployments.
44

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

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# ☁️ Google Cloud Run
2+
3+
MCP Gateway can be deployed to [Google Cloud Run](https://cloud.google.com/run), a fully managed, autoscaling platform for containers with built-in HTTPS, identity, and integration with other GCP services like Cloud SQL and Memorystore.
4+
5+
This guide walks through provisioning a PostgreSQL and Redis backend, deploying the container, injecting secrets, and verifying access using JWT.
6+
7+
---
8+
9+
## ✅ Overview
10+
11+
Cloud Run is ideal for MCP Gateway use cases:
12+
13+
- **Serverless and cost-efficient** (scale to zero)
14+
- **Public HTTPS endpoints** with zero config
15+
- Built-in **integration with Cloud SQL (PostgreSQL)** and **Memorystore (Redis)**
16+
- Compatible with public container registries like GitHub’s `ghcr.io`
17+
18+
You can deploy the public image directly:
19+
20+
```text
21+
ghcr.io/ibm/mcp-context-forge:latest
22+
````
23+
24+
---
25+
26+
## 🛠 Prerequisites
27+
28+
* Google Cloud project with billing enabled
29+
30+
* `gcloud` CLI authenticated (`gcloud init`)
31+
32+
* Enabled APIs:
33+
34+
```bash
35+
gcloud services enable run.googleapis.com sqladmin.googleapis.com redis.googleapis.com
36+
```
37+
38+
* Docker (for local testing or JWT token generation)
39+
40+
* `.env` values for:
41+
42+
* `JWT_SECRET_KEY`
43+
* `DATABASE_URL`
44+
* `REDIS_URL`
45+
* `AUTH_REQUIRED`, `BASIC_AUTH_USER`, etc.
46+
47+
---
48+
49+
## ⚙️ Setup Steps
50+
51+
### 1. 🗄️ Provision Cloud SQL (PostgreSQL)
52+
53+
```bash
54+
gcloud sql instances create mcpgw-db \
55+
--database-version=POSTGRES_14 \
56+
--cpu=2 --memory=4GiB \
57+
--region=us-central1
58+
59+
gcloud sql users set-password postgres \
60+
--instance=mcpgw-db --password=mysecretpassword
61+
62+
gcloud sql databases create mcpgw --instance=mcpgw-db
63+
```
64+
65+
Find the IP address:
66+
67+
```bash
68+
gcloud sql instances describe mcpgw-db \
69+
--format="value(ipAddresses.ipAddress)"
70+
```
71+
72+
---
73+
74+
### 2. ⚡ Provision Memorystore (Redis)
75+
76+
```bash
77+
gcloud redis instances create mcpgw-redis \
78+
--region=us-central1 \
79+
--tier=STANDARD_HA \
80+
--size=1
81+
```
82+
83+
Get the Redis IP:
84+
85+
```bash
86+
gcloud redis instances describe mcpgw-redis \
87+
--region=us-central1 \
88+
--format="value(host)"
89+
```
90+
91+
---
92+
93+
### 3. 🚀 Deploy to Google Cloud Run
94+
95+
```bash
96+
gcloud run deploy mcpgateway \
97+
--image=ghcr.io/ibm/mcp-context-forge:latest \
98+
--region=us-central1 \
99+
--platform=managed \
100+
--allow-unauthenticated \
101+
--port=4444 \
102+
--cpu=2 \
103+
--memory=2Gi \
104+
--max-instances=1 \
105+
--set-env-vars=\
106+
JWT_SECRET_KEY=your-secret,\
107+
BASIC_AUTH_USER=admin,\
108+
BASIC_AUTH_PASSWORD=changeme,\
109+
AUTH_REQUIRED=true,\
110+
DATABASE_URL=postgresql://postgres:mysecretpassword@<SQL_IP>:5432/mcpgw,\
111+
REDIS_URL=redis://<REDIS_IP>:6379/0,\
112+
CACHE_TYPE=redis
113+
```
114+
115+
> 🔐 Be sure to replace `<SQL_IP>` and `<REDIS_IP>` with the actual addresses you retrieved.
116+
117+
---
118+
119+
## 🔒 Auth & Access
120+
121+
### Generate a Bearer Token
122+
123+
You can use the official container to generate a token:
124+
125+
```bash
126+
docker run -it --rm ghcr.io/ibm/mcp-context-forge:latest \
127+
python3 -m mcpgateway.utils.create_jwt_token -u admin
128+
```
129+
130+
Export it:
131+
132+
```bash
133+
export MCPGATEWAY_BEARER_TOKEN=<paste-token-here>
134+
```
135+
136+
### Smoke Test
137+
138+
```bash
139+
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
140+
https://<your-cloud-run-url>/health
141+
142+
curl -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
143+
https://<your-cloud-run-url>/tools
144+
```
145+
146+
---
147+
148+
## 📦 GitHub Actions Deployment (Optional)
149+
150+
You can automate builds and deployments using GitHub Actions. See:
151+
152+
```
153+
.github/workflows/google-cloud-run.yml
154+
```
155+
156+
It builds from `Containerfile.lite`, pushes to Artifact Registry, and deploys to Cloud Run with `--max-instances=1`.
157+
158+
---
159+
160+
## 📘 Notes & Tips
161+
162+
* Cloud Run endpoints are public HTTPS by default
163+
* Add a custom domain via Cloud Run settings (optional)
164+
* Use Secret Manager or env vars for sensitive values
165+
* To avoid cold starts, you can enable **minimum instance = 1**
166+
* Logs and metrics available via Cloud Console
167+
168+
---
169+
170+
## 🧩 Summary
171+
172+
| Feature | Supported |
173+
| -------------------- | ----------------------- |
174+
| HTTPS (built-in) | ✅ |
175+
| Custom domains | ✅ |
176+
| Postgres (Cloud SQL) | ✅ |
177+
| Redis (Memorystore) | ✅ |
178+
| Auto-scaling | ✅ |
179+
| Scale-to-zero | ✅ |
180+
| Max instance limit | ✅ |
181+
182+
---
183+
184+
## 🧠 Resources
185+
186+
* [Cloud Run documentation](https://cloud.google.com/run/docs)
187+
* [Cloud SQL connection tips](https://cloud.google.com/sql/docs/postgres/connect-run)
188+
* [Memorystore overview](https://cloud.google.com/memorystore/docs/redis)

‎docs/docs/deployment/ibm-code-engine.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Deploying MCP Gateway to IBM Code Engine
1+
# ⚙️ IBM Code Engine
22

33
This guide covers two supported deployment paths for the **MCP Gateway**:
44

‎docs/docs/deployment/kubernetes.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Kubernetes / OpenShift Deployment
1+
# ☸️ Kubernetes / OpenShift Deployment
22

33
You can deploy MCP Gateway to any K8s-compliant platform — including vanilla Kubernetes, OpenShift, and managed clouds like GKE, AKS, and EKS.
44

‎docs/docs/deployment/local.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Local Deployment
1+
# 🐍 Local Deployment
22

33
This guide walks you through running MCP Gateway on your local machine using a virtual environment or directly via Python.
44

0 commit comments

Comments
 (0)