Provisioning ibl.ai on Google Cloud (GCP)

Mirrored from iblai/infra-cli · docs/GCP.md. This page is generated — edit it in the repository, not here.

This guide walks you through standing up a single-server ibl.ai deployment on GCP, start to finish. If you've used the AWS flow, this is the same experience — just point it at a GCP project.

Scope: single-server only. Multi-server and call-server remain AWS-only for now. Storage note: GCP creates no object storage. The platform keeps using AWS S3 — you supply AWS credentials at the setup step (details in Storage).

---

What you'll end up with

                 Internet
                    │
      ┌─────────────▼──────────────┐
      │  Global external HTTPS LB   │   ← one static IP, Google-managed TLS cert
      └─────────────┬──────────────┘
                    │ HTTP :80
      ┌─────────────▼──────────────┐
      │  1 VM (Ubuntu 22.04, Docker) │   ← external IP for SSH (locked to your IP)
      └─────────────────────────────┘
   VPC · 1 subnet · 2 firewall rules · Cloud DNS A-records → the LB IP

---

1. Prerequisites (one-time)

Roles + APIs (what permissions prints):

# Grant to your user or service account:
#   roles/compute.admin   roles/dns.admin   roles/iam.serviceAccountUser

# Enable the APIs:
gcloud services enable compute.googleapis.com dns.googleapis.com --project <PROJECT_ID>

Authentication — pick one

Option A — your Google account (easiest for local use):

gcloud auth application-default login

gcloud auth login alone is not enough — Terraform and the CLI read Application Default Credentials, which only the command above writes.

Option B — service-account key (for CI, or when your Workspace org blocks Option A's browser flow with an "Access blocked / admin needs to review" page):

PROJECT=<your-project-id>
gcloud iam service-accounts create infra-cli --project=$PROJECT
for R in roles/compute.admin roles/dns.admin roles/iam.serviceAccountUser; do
  gcloud projects add-iam-policy-binding $PROJECT \
    --member="serviceAccount:infra-cli@$PROJECT.iam.gserviceaccount.com" --role=$R --condition=None
done
gcloud iam service-accounts keys create ~/infra-cli-key.json \
  --iam-account="infra-cli@$PROJECT.iam.gserviceaccount.com"

Use it by choosing "Service-account key file" in the wizard, or setting GCP_CREDENTIALS_FILE=~/infra-cli-key.json in your .env. Keep the key file out of git; delete the service account when you no longer need it.

Verify you're ready (works with either option):

iblai infra permissions --provider gcp --check --project <PROJECT_ID>

---

2. Provision — the easy way (interactive)

iblai infra provision

1. Choose cloud → select GCP.
2. Authentication → project ID, region/zone, and ADC or a key file. (Validated on the spot.)
3. Project & compute → a name, environment, machine type (default e2-standard-8), disk.
4. Network & access → it auto-detects your public IP and locks SSH to it.
5. Domain & certificates → pick your Cloud DNS zone (or create one), or skip HTTPS.
6. Review → confirm, and it provisions.

When it finishes you'll see the VM IP, the app URL, and an SSH command.

AI heads-up: e2-standard-8 has 32 GB RAM. If you'll enable AI features at setup, choose a 64 GB machine (e2-standard-16 or n2-highmem-8).

---

3. Provision — the automated way (non-interactive)

Best for CI or repeatable runs.

cp .env.provision.gcp.example .env
# edit .env — set PROVIDER=gcp, GCP_PROJECT_ID, DOMAIN, etc.
iblai infra provision-env -f .env

Minimum .env:

PROVIDER=gcp
GCP_PROJECT_ID=my-proj-123456
# GCP_CREDENTIALS_FILE=/path/to/key.json   # omit to use `gcloud` ADC
PROJECT_NAME=mydeploy
DOMAIN=platform.example.com
VPN_IP=auto                                 # your current IP; or a literal IP
CERT_METHOD=auto                            # managed cert if a Cloud DNS zone matches, else HTTP-only
DNS_ZONE_NAME=my-zone                        # the zone's resource name (managed cert)

See .env.provision.gcp.example for every option (machine type, disk, upload certs, create-zone, etc.).

---

4. DNS & HTTPS

The certificate is a classic Google-managed SSL cert covering your base domain

• 19 ibl.ai subdomains. Two things to know:

1. It validates asynchronously. apply finishes while the cert is still PROVISIONING. HTTPS goes live 10–60 minutes later, once DNS resolves to the load balancer. This is normal — the CLI tells you so.
2. Your domain must be delegated to Cloud DNS. If you let the CLI create the zone (CREATE_DNS_ZONE=true or the wizard's "create" option), it prints the nameservers — set those at your registrar. The cert can't validate until delegation is live.

Check cert status any time:

gcloud compute ssl-certificates describe <project>-<env>-cert --global \
  --format="value(managed.status)"        # PROVISIONING → ACTIVE when ready

No domain yet? Choose CERT_METHOD=none (or "Skip HTTPS" in the wizard) to get an HTTP-only load balancer, and add TLS later.

---

5. Storage uses AWS S3

GCP provisions no buckets. Before (or during) setup, make sure you have three S3 buckets in an AWS account, named on the standard convention:

<project>-<environment>-<domain-with-dots-as-dashes>-backups
<project>-<environment>-<domain-with-dots-as-dashes>-dm-media
<project>-<environment>-<domain-with-dots-as-dashes>-dm-static   # public-read

Example, for PROJECT_NAME=mydeploy, ENVIRONMENT=prod, DOMAIN=platform.example.com:

mydeploy-prod-platform-example-com-backups
mydeploy-prod-platform-example-com-dm-media
mydeploy-prod-platform-example-com-dm-static   (public-read)

You provide the AWS access key + secret at the setup step (below); the app on the GCP box uses them to reach S3 — exactly as the AWS deployment does today.

---

6. Set up the platform

Provisioning creates the infrastructure; setup installs and configures ibl.ai on the VM (over SSH, via Ansible):

iblai infra setup <PROJECT_NAME>

It reads the VM's IP and SSH key from the saved state and prompts for the AWS credentials (for S3), a GitHub token, and admin details. This step is identical to the AWS flow.

---

7. Inspect and tear down

iblai infra list                 # all environments (GCP rows are marked "gcp · single")
iblai infra status <PROJECT_NAME> # details for one
iblai infra destroy <PROJECT_NAME>

destroy removes everything this tool created (VM, LB, firewall, DNS records, cert). A Cloud DNS zone you created outside the tool is left alone; a zone the tool created is removed.

---

Troubleshooting

---

How it maps to AWS (for reference)

Deeper internals live in CLAUDE.md under GCP Provider (single-server).