Google Cloud Build & Deploy Guide
A step-by-step guide for students to build Docker images and deploy them to Google Cloud Run.
Prerequisites
- Docker installed on your machine
- A Google Cloud account
- A project with Docker files ready to deploy
Step 1: Setup Google Cloud Project
Create a new project (if needed)
# Template
gcloud projects create <PROJECT_ID> --name="<PROJECT_NAME>"
# Example
gcloud projects create technova-mcp-server --name="Technova MCP Server"
Set your project as active
# Template
gcloud config set project <PROJECT_ID>
# Example
gcloud config set project technova-mcp-server
Step 2: Install Google Cloud CLI
For macOS (using Homebrew)
brew install google-cloud-sdk
For Windows
Download from: https://cloud.google.com/sdk/docs/install
For Linux
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
Step 3: Authenticate with Google Cloud
gcloud auth login
This opens your browser to sign in with your Google account.
Step 4: Build Your Docker Image
Build your Docker image locally
# Template
docker build -t <IMAGE_NAME> .
# Example important we need to specify platform
docker build --platform linux/amd64 -t technova-mcp-server .
Verify your image was built
docker images
Step 5: Enable Required APIs
Enable Artifact Registry API
# Template
gcloud services enable artifactregistry.googleapis.com --project=<PROJECT_ID>
# Example
gcloud services enable artifactregistry.googleapis.com --project=technova-mcp-server
Enable Cloud Run API
# Template
gcloud services enable run.googleapis.com --project=<PROJECT_ID>
# Example
gcloud services enable run.googleapis.com --project=technova-mcp-server
Step 6: Create Artifact Registry Repository
# Template
gcloud artifacts repositories create <REPO_NAME> \
--repository-format=docker \
--location=<REGION> \
--project=<PROJECT_ID>
# Example
gcloud artifacts repositories create technova-repo \
--repository-format=docker \
--location=us-central1 \
--project=technova-mcp-server
Step 7: Configure Docker Authentication
# Template
gcloud auth configure-docker <REGION>-docker.pkg.dev
# Example
gcloud auth configure-docker us-central1-docker.pkg.dev
Step 8: Set Up IAM Permissions
Grant yourself editor permissions
# Template
gcloud projects add-iam-policy-binding <PROJECT_ID> \
--member="user:<YOUR_EMAIL>" \
--role="roles/editor"
# Example
gcloud projects add-iam-policy-binding technova-mcp-server \
--member="user:muellerjohannes93@gmail.com" \
--role="roles/editor"
Grant Artifact Registry writer permissions
# Template
gcloud projects add-iam-policy-binding <PROJECT_ID> \
--member="user:<YOUR_EMAIL>" \
--role="roles/artifactregistry.writer"
# Example
gcloud projects add-iam-policy-binding technova-mcp-server \
--member="user:muellerjohannes93@gmail.com" \
--role="roles/artifactregistry.writer"
Step 9: Tag and Push Image to Artifact Registry
Tag your image
# Template
docker tag <LOCAL_IMAGE_NAME> \
<REGION>-docker.pkg.dev/<PROJECT_ID>/<REPO_NAME>/<IMAGE_NAME>:<TAG>
# Example
docker tag technova-mcp-server \
us-central1-docker.pkg.dev/technova-mcp-server/technova-repo/technova-mcp-server:latest
Push image to registry
# Template
docker push <REGION>-docker.pkg.dev/<PROJECT_ID>/<REPO_NAME>/<IMAGE_NAME>:<TAG>
# Example
docker push \
us-central1-docker.pkg.dev/technova-mcp-server/technova-repo/technova-mcp-server:latest
Step 10: Deploy to Cloud Run
Deploy using the pushed image
# Template
gcloud run deploy <SERVICE_NAME> \
--image <REGION>-docker.pkg.dev/<PROJECT_ID>/<REPO_NAME>/<IMAGE_NAME>:<TAG> \
--region <REGION> \
--project <PROJECT_ID> \
--allow-unauthenticated \
--memory <MEMORY_SIZE> \
--platform managed \
--port <PORT>
# Example
gcloud run deploy technova-mcp-server \
--image us-central1-docker.pkg.dev/technova-mcp-server/technova-repo/technova-mcp-server:latest \
--region us-central1 \
--project technova-mcp-server \
--allow-unauthenticated \
--memory 1Gi \
--platform managed \
--port 8080
Note: This example uses the consistent project ID technova-mcp-server throughout._ID>
--allow-unauthenticated
--memory <MEMORY_SIZE>
--platform managed
--port
Example
gcloud run deploy technova-mcp-server
--image us-central1-docker.pkg.dev/technova-mcp-server/technova-repo/technova-mcp-server:latest
--region us-central1
--project technova-mcp-server
--allow-unauthenticated
--memory 1Gi
--platform managed
--port 8080
### ⭐ Recommended: Deploy directly from source (Cloud Build handles everything)
```bash
# Template
gcloud run deploy <SERVICE_NAME> \
--source . \
--port <PORT> \
--memory <MEMORY_SIZE> \
--allow-unauthenticated \
--region <REGION> \
--project <PROJECT_ID>
# Working example (from successful deployment)
gcloud run deploy technova-mcp-server \
--source . \
--port 8080 \
--memory 1Gi \
--allow-unauthenticated \
--region us-central1 \
--project technova-mcp-server
Why this method works better:
- Cloud Run automatically builds your Docker image using Cloud Build
- No manual Docker registry setup needed
- Handles dependencies and build process automatically
- Less prone to port configuration errors
Common Values Reference
| Parameter | Common Values | Description |
|---|---|---|
<REGION> |
us-central1, us-east1, europe-west1 |
Geographic location |
<MEMORY_SIZE> |
512Mi, 1Gi, 2Gi, 4Gi |
Memory allocation |
<PORT> |
8080, 3000, 5000 |
Application port |
<TAG> |
latest, v1.0, dev |
Image version tag |
Verification Steps
Check your deployment
gcloud run services list --project=<PROJECT_ID>
Get service URL
gcloud run services describe <SERVICE_NAME> \
--region=<REGION> \
--project=<PROJECT_ID> \
--format="value(status.url)"
View logs
gcloud logs tail --project=<PROJECT_ID>
Troubleshooting
Common Issues
Authentication Error: Run gcloud auth login again
Permission Denied: Check IAM permissions in Step 8
Image Not Found: Verify image was pushed successfully with gcloud artifacts docker images list --repository=<REPO_NAME> --location=<REGION>
🔥 Container Failed to Start (Port Issues)
Error Message: The user-provided container failed to start and listen on the port defined provided by the PORT=8080 environment variable
Root Cause: Your application isn't listening on the correct port that Cloud Run expects.
Solution Steps:
1. Check your application code
Your app must listen on the port specified by the PORT environment variable:
// Node.js/Express example
const port = process.env.PORT || 8080;
app.listen(port, '0.0.0.0', () => {
console.log(`Server running on port ${port}`);
});
# Python/Flask example
import os
from flask import Flask
app = Flask(__name__)
if __name__ == '__main__':
port = int(os.environ.get('PORT', 8080))
app.run(host='0.0.0.0', port=port)
2. Test locally with PORT environment variable
# Test locally to ensure your app respects PORT env var
PORT=8080 docker run -p 8080:8080 -e PORT=8080 technova-mcp-server
# Test if accessible
curl http://localhost:8080
3. Check your Dockerfile Ensure your Dockerfile doesn't hardcode a different port:
# ❌ Bad - hardcoded port
EXPOSE 3000
CMD ["node", "server.js"]
# ✅ Good - uses environment variable
EXPOSE 8080
CMD ["node", "server.js"]
4. Deploy with increased timeout
gcloud run deploy technova-mcp-server \
--image us-central1-docker.pkg.dev/technova-mcp-server/technova-repo/technova-mcp-server:latest \
--region us-central1 \
--project technova-mcp-server \
--allow-unauthenticated \
--memory 1Gi \
--port 8080 \
--timeout 300 \
--cpu 1
5. Check logs for more details
gcloud logs tail --project=technova-mcp-server
Debug Checklist:
- App listens on
process.env.PORTor equivalent - App binds to
0.0.0.0, notlocalhostor127.0.0.1 - Dockerfile exposes the correct port
- No firewall or security groups blocking the port
- App starts within Cloud Run's timeout (default 240 seconds)
Debugging Your Deployment
Get detailed logs
# Follow logs in real-time
gcloud logs tail --project=technova-mcp-server
# Get specific revision logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=technova-mcp-server" --project=technova-mcp-server --limit=50
Test your container locally first
# Build and test locally with same environment as Cloud Run
docker build -t technova-mcp-server .
docker run -p 8080:8080 -e PORT=8080 technova-mcp-server
# In another terminal, test if it responds
curl http://localhost:8080
Check service status
# Get service details
gcloud run services describe technova-mcp-server \
--region us-central1 \
--project technova-mcp-server
# List all revisions
gcloud run revisions list \
--service technova-mcp-server \
--region us-central1 \
--project technova-mcp-server
Quick Commands Summary
# Setup
gcloud config set project <PROJECT_ID>
gcloud services enable artifactregistry.googleapis.com run.googleapis.com
# Build & Push
docker build -t <IMAGE_NAME> .
docker tag <IMAGE_NAME> <REGION>-docker.pkg.dev/<PROJECT_ID>/<REPO_NAME>/<IMAGE_NAME>:latest
docker push <REGION>-docker.pkg.dev/<PROJECT_ID>/<REPO_NAME>/<IMAGE_NAME>:latest
# Deploy
gcloud run deploy <SERVICE_NAME> \
--image <REGION>-docker.pkg.dev/<PROJECT_ID>/<REPO_NAME>/<IMAGE_NAME>:latest \
--region <REGION> \
--allow-unauthenticated
Metadata
Release files for iflow-mcp_xamhans-mcp-course 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_xamhans_mcp_course-0.1.0.tar.gz | 8.1 kB | Without provenance | Details for iflow_mcp_xamhans_mcp_course-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_xamhans_mcp_course-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_xamhans_mcp_course-0.1.0-py3-none-any.whl |
Total release size: 16.5 kB
Release files / iflow_mcp_xamhans_mcp_course-0.1.0.tar.gz
| Download URL | iflow_mcp_xamhans_mcp_course-0.1.0.tar.gz |
|---|---|
| Size | 8.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fdfae0c8575af0338d34634f8cfc8188bec8a6dbc06c1d85b752620fa0c82788
|
|
BLAKE2b-256 checksum How to use checksums |
ce937edf31439d8bfb3d7f3dcc689de63f1e578a9b6f7425e105b6fed0acd81b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_xamhans_mcp_course-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_xamhans_mcp_course-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bd0d8ac3e5ecc548e8d627b29ca6be92331779fc74171a349a7e4de6824515f9
|
|
BLAKE2b-256 checksum How to use checksums |
4770cc4cc48ca6ec7c8b0b482612f5e58431eda31037d3c4f48b28b9846d9762
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_xamhans-mcp-course 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.