Mainframe Assist Wiki — GCP Deployment Guide¶

Overview¶

This document explains how to set up and deploy the Mainframe Assist developer wiki at:

App: https://mainframe-assist.itsaiplatform.com/
Wiki: https://wiki-mainframe-assist.itsaiplatform.com/

The wiki is a static site built with MkDocs Material and hosted on Google Cloud Platform using Cloud Storage as origin + Cloud CDN (via Load Balancer) for HTTPS delivery on a custom domain.

Architecture¶

┌─────────────────────────────────────────────────────────────────────────────────┐
│                         GCP Project                                              │
│                                                                                  │
│  ┌──────────────────┐     ┌──────────────────────┐     ┌────────────────────┐   │
│  │  Cloud Storage    │     │  Cloud Load Balancer  │     │  Cloud CDN         │   │
│  │  (Static Site)    │◄────│  (HTTPS Frontend)     │◄────│  (Cache Layer)     │   │
│  │                   │     │                       │     │                    │   │
│  │  Bucket:          │     │  Frontend:            │     │  Cache Policy:     │   │
│  │  wiki-mainframe-  │     │    - SSL cert (auto)  │     │    - 1hr TTL       │   │
│  │  assist           │     │    - HTTPS redirect   │     │    - Per-path      │   │
│  │                   │     │    - Path: /*         │     │                    │   │
│  │  Files:           │     │                       │     │                    │   │
│  │    index.html     │     │  Backend:             │     │                    │   │
│  │    assets/        │     │    - Cloud Storage    │     │                    │   │
│  │    search/        │     │      bucket backend   │     │                    │   │
│  └──────────────────┘     └──────────────────────┘     └────────────────────┘   │
│                                                                                  │
│  ┌──────────────────┐     ┌──────────────────────┐                              │
│  │  Cloud DNS        │     │  SSL Certificate      │                              │
│  │  (DNS Zone)       │     │  (Google-managed)     │                              │
│  │                   │     │                       │                              │
│  │  wiki-mainframe-  │     │  Domain:              │                              │
│  │  assist.          │     │  wiki-mainframe-      │                              │
│  │  itsaiplatform.   │     │  assist.              │                              │
│  │  com → LB IP      │     │  itsaiplatform.com    │                              │
│  └──────────────────┘     └──────────────────────┘                              │
└─────────────────────────────────────────────────────────────────────────────────┘

Flow: User → Cloud CDN → Load Balancer (HTTPS) → Cloud Storage bucket (static files)

Prerequisites¶

GCP project with billing enabled
gcloud CLI installed and authenticated
Python 3.8+ with pip (for MkDocs)
Domain DNS access for itsaiplatform.com

Project structure¶

mainframe-assist-wiki/
├── docs/
│   ├── index.md              # Home page (main wiki content)
│   ├── deployment/           # Deployment docs (this file lives here)
│   ├── reference/            # API + agent internals
│   └── ...
├── site/                     # Built output (gitignored)
├── mkdocs.yml                # MkDocs configuration
├── requirements.txt          # Python dependencies
├── deploy.sh                 # Deployment script
└── .gitignore

Step 1 — MkDocs setup (local)¶

Install dependencies¶

pip install -r requirements.txt

requirements.txt:

mkdocs==1.6.1
mkdocs-material==9.5.40
pymdown-extensions==10.11

Local development¶

# Serve locally with hot-reload (http://localhost:8000)
mkdocs serve

# Build static site to site/ folder
mkdocs build

Step 2 — GCP Cloud Storage setup¶

Set variables¶

export PROJECT_ID="your-gcp-project-id"
export BUCKET_NAME="wiki-mainframe-assist"
export REGION="us-central1"
export DOMAIN="wiki-mainframe-assist.itsaiplatform.com"

gcloud config set project $PROJECT_ID

Create the bucket¶

# Create the bucket (uniform bucket-level access)
gcloud storage buckets create gs://$BUCKET_NAME \
  --project=$PROJECT_ID \
  --location=$REGION \
  --uniform-bucket-level-access

# Make bucket publicly readable (required for static site serving)
gcloud storage buckets add-iam-policy-binding gs://$BUCKET_NAME \
  --member=allUsers \
  --role=roles/storage.objectViewer

# Configure as a static website
gcloud storage buckets update gs://$BUCKET_NAME \
  --web-main-page-suffix=index.html \
  --web-not-found-page=404.html

Upload the site¶

# Build the site
mkdocs build

# Upload site/ folder to bucket (with cache headers)
gcloud storage cp -r site/* gs://$BUCKET_NAME/ \
  --cache-control="public, max-age=3600"

Step 3 — Cloud CDN + Load Balancer (HTTPS)¶

Cloud Storage direct access only supports HTTP. For HTTPS on a custom domain, you need a Cloud Load Balancer with Cloud CDN and a Google-managed SSL certificate.

Reserve a static IP¶

gcloud compute addresses create wiki-mainframe-assist-ip \
  --global \
  --ip-version=IPV4

# Get the IP (you'll need this for DNS)
gcloud compute addresses describe wiki-mainframe-assist-ip --global \
  --format="get(address)"

Backend bucket (connects LB → Cloud Storage)¶

gcloud compute backend-buckets create wiki-mainframe-assist-backend \
  --gcs-bucket-name=$BUCKET_NAME \
  --enable-cdn \
  --cache-mode=CACHE_ALL_STATIC \
  --default-ttl=3600 \
  --max-ttl=86400

URL map (routing)¶

gcloud compute url-maps create wiki-mainframe-assist-urlmap \
  --default-backend-bucket=wiki-mainframe-assist-backend

SSL certificate (Google-managed, auto-renewing)¶

gcloud compute ssl-certificates create wiki-mainframe-assist-cert \
  --domains=$DOMAIN \
  --global

Note

The certificate won't provision until DNS points to the load balancer IP. It can take 15–60 minutes after DNS is configured.

HTTPS target proxy¶

gcloud compute target-https-proxies create wiki-mainframe-assist-https-proxy \
  --url-map=wiki-mainframe-assist-urlmap \
  --ssl-certificates=wiki-mainframe-assist-cert \
  --global

HTTP → HTTPS redirect (recommended)¶

gcloud compute url-maps import wiki-mainframe-assist-http-redirect \
  --source=/dev/stdin <<EOF
name: wiki-mainframe-assist-http-redirect
defaultUrlRedirect:
  httpsRedirect: true
  redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
EOF

gcloud compute target-http-proxies create wiki-mainframe-assist-http-proxy \
  --url-map=wiki-mainframe-assist-http-redirect \
  --global

Forwarding rules (attach IP → proxies)¶

# HTTPS forwarding rule (port 443)
gcloud compute forwarding-rules create wiki-mainframe-assist-https-rule \
  --global \
  --target-https-proxy=wiki-mainframe-assist-https-proxy \
  --address=wiki-mainframe-assist-ip \
  --ports=443

# HTTP forwarding rule (port 80 → redirects to HTTPS)
gcloud compute forwarding-rules create wiki-mainframe-assist-http-rule \
  --global \
  --target-http-proxy=wiki-mainframe-assist-http-proxy \
  --address=wiki-mainframe-assist-ip \
  --ports=80

Step 4 — DNS¶

Point the domain to the load balancer's static IP.

Get the reserved IP¶

gcloud compute addresses describe wiki-mainframe-assist-ip --global \
  --format="get(address)"
# Example: 34.120.xxx.xxx

Add DNS record¶

In your DNS provider (where itsaiplatform.com is managed), add:

Type	Name	Value	TTL
A	`wiki-mainframe-assist`	`34.120.xxx.xxx` (static IP)	300

If using Cloud DNS in GCP:

gcloud dns record-sets create $DOMAIN \
  --zone="itsaiplatform-com" \
  --type="A" \
  --ttl=300 \
  --rrdatas="34.120.xxx.xxx"

Warning

Wait 15–60 minutes for DNS propagation and SSL certificate provisioning (Google validates domain ownership via DNS).

Verify SSL certificate status¶

gcloud compute ssl-certificates describe wiki-mainframe-assist-cert --global \
  --format="get(managed.status)"

# Should show: ACTIVE (may show PROVISIONING initially)

Step 5 — Deploy script¶

The committed deploy.sh at the repo root wraps the recurring build + upload + invalidate flow:

#!/bin/bash
set -euo pipefail

PROJECT_ID="${PROJECT_ID:-your-gcp-project-id}"
BUCKET_NAME="${BUCKET_NAME:-wiki-mainframe-assist}"
URLMAP_NAME="${URLMAP_NAME:-wiki-mainframe-assist-urlmap}"

echo "🔨 Building MkDocs site..."
mkdocs build --clean --strict

echo "🚀 Uploading to Cloud Storage..."
gcloud storage cp -r site/* "gs://${BUCKET_NAME}/" \
  --project="${PROJECT_ID}" \
  --cache-control="public, max-age=3600"

echo "🗑️  Invalidating CDN cache..."
gcloud compute url-maps invalidate-cdn-cache "${URLMAP_NAME}" \
  --path="/*" --global --async

echo "✅ Deployed to https://wiki-mainframe-assist.itsaiplatform.com/"

Run it:

chmod +x deploy.sh
PROJECT_ID=my-project ./deploy.sh

Quick reference¶

Commands cheat sheet¶

# Local dev (hot reload)
mkdocs serve

# Build static site
mkdocs build

# Deploy to GCP (from local)
PROJECT_ID=my-project ./deploy.sh

# Manual upload only
gcloud storage cp -r site/* gs://wiki-mainframe-assist/

# Invalidate CDN cache (force refresh)
gcloud compute url-maps invalidate-cdn-cache wiki-mainframe-assist-urlmap \
  --path="/*" --global

# Check SSL cert status
gcloud compute ssl-certificates describe wiki-mainframe-assist-cert \
  --global --format="get(managed.status)"

# Check load balancer health
gcloud compute forwarding-rules list --global

# View bucket contents
gcloud storage ls gs://wiki-mainframe-assist/

Resource summary¶

Resource	GCP Service	Name
Static files	Cloud Storage	`gs://wiki-mainframe-assist`
CDN + HTTPS	Cloud Load Balancer	`wiki-mainframe-assist-urlmap`
SSL Cert	Compute (managed)	`wiki-mainframe-assist-cert`
Static IP	Compute	`wiki-mainframe-assist-ip`
Backend	Backend Bucket	`wiki-mainframe-assist-backend`
DNS	Cloud DNS / External	A record → LB IP

Architecture comparison (BA Assist vs Mainframe Assist Wiki)¶

Aspect	BA Assist Wiki	Mainframe Assist Wiki
Cloud	AWS	GCP
Static Hosting	S3 + CloudFront (via SST)	Cloud Storage + Cloud CDN
SSL	ACM (auto)	Google-managed cert (auto)
Deploy Tool	SST (`sst.aws.StaticSite`)	`gcloud` CLI (manual/script)
Build Tool	MkDocs Material	MkDocs Material
CDN Cache	CloudFront	Cloud CDN
Domain	`wiki.{ROOT_DOMAIN}`	`wiki-mainframe-assist.itsaiplatform.com`
Deploy From	CI (GitHub Actions)	Local (`./deploy.sh`)

Troubleshooting¶

SSL certificate stuck on PROVISIONING¶

Verify DNS A record points to the correct static IP.
Check: dig wiki-mainframe-assist.itsaiplatform.com
Wait up to 60 minutes after DNS is correct.
Verify domain has no CAA record blocking Google: dig CAA itsaiplatform.com

Site shows "Not Found" after deploy¶

Verify bucket has index.html at root: gcloud storage ls gs://wiki-mainframe-assist/index.html
Check bucket web configuration: gcloud storage buckets describe gs://wiki-mainframe-assist --format="get(website)"
Invalidate CDN cache: gcloud compute url-maps invalidate-cdn-cache ...

403 Forbidden¶

Bucket must be publicly readable:

gcloud storage buckets get-iam-policy gs://wiki-mainframe-assist
# Should show allUsers with objectViewer role

Changes not reflecting¶

Cloud CDN caches aggressively (1 hr default TTL).
Invalidate cache after deploy (included in deploy.sh).
Or reduce TTL: --default-ttl=300 on backend bucket.

Local `mkdocs serve` fails¶

Install deps: pip install -r requirements.txt
Ensure docs/index.md exists.
Check mkdocs.yml indentation (YAML is indent-sensitive).

Adding new wiki pages¶

Create a new .md file in docs/:
```
touch docs/new-page.md
```

Add it to navigation in mkdocs.yml:

nav:
  - Home: index.md
  - New Page: new-page.md

Build and deploy:
```
./deploy.sh
```

Cost estimate¶

Resource	Monthly cost (approx)
Cloud Storage (< 1 GB)	~$0.02
Cloud CDN (light traffic)	~$0.01–1.00
Load Balancer (forwarding rule)	~$18.00
SSL Certificate	Free (Google-managed)
Static IP	Free (when attached)
Total	~$18–20/month

Tip

The load balancer forwarding rule is the primary cost. For budget-conscious setups, consider Firebase Hosting (free tier) as an alternative that includes CDN + SSL without a load balancer.

Alternative: Firebase Hosting¶

If cost or complexity is a concern, Firebase Hosting is simpler and free for this use case:

# Install Firebase CLI
npm install -g firebase-tools

# Initialize (select Hosting, use 'site' as public dir)
firebase init hosting

firebase.json:

{
  "hosting": {
    "site": "wiki-mainframe-assist",
    "public": "site",
    "ignore": ["firebase.json", "**/.*"],
    "rewrites": [{ "source": "**", "destination": "/index.html" }]
  }
}

# Build and deploy
mkdocs build
firebase deploy --only hosting:wiki-mainframe-assist

# Custom domain: Firebase Console → Hosting → Add custom domain
# Point: wiki-mainframe-assist.itsaiplatform.com → Firebase

Firebase Hosting includes CDN + SSL + custom domain for free (up to 10 GB/month bandwidth).