Neon LawCall +1 510 800 2090
  • Navigator
  • Notations
  • Legal Aid
  • Sign in

← Operating Neon Law Navigator

Prepare Google Cloud

Chapter 2 of 7 · Section 9 of 54

Sections

1. Intro

  • 1. Deploy your own
  • 2. Agenda

2. Prepare Google Cloud

  • 3. Bring your own project
  • 4. Dry-run first
  • 5. Private assets and domain restricted sharing
  • 6. The Navigator deployment matrix
  • 7. The `/app` mount and HTTP route ownership
  • 8. `neon` — the whole brand seam
  • 9. Live rollout checkpoint
  • 10. Set one site to one version

3. Provision the Infrastructure

  • 11. The APIs that light up
  • 12. Network and storage buckets
  • 13. How a matter's pages reach a client
  • 14. A document's bytes and authorization are separate
  • 15. A private image registry
  • 16. The cluster comes up
  • 17. What setup owns — and what follows it

4. Operate Forgejo beside Navigator

  • 18. Deploy the forge before switching repositories
  • 19. Separate people, Git transport, and machine access
  • 20. Require the gate and protected-main policy
  • 21. Bind the workflow to one Project and one commit
  • 22. Notify failures even when the manifest is broken
  • 23. Restore the repository before cutting over

5. Environment Matrix

  • 24. Three operating modes, two deployment profiles
  • 25. The deployment that says its matters are sample
  • 26. Deployment and release switches
  • 27. Workflow host and routing switches
  • 28. Capability and storage switches
  • 29. Configuration precedence: the first source wins
  • 30. Local dev controls: inputs read by `hudson dev`
  • 31. Local runtime: what `.devx/env` generates
  • 32. The store: SurrealDB
  • 33. Where SurrealDB authorization lives
  • 34. Deployed runtime: core web and worker wiring
  • 35. Deployed runtime: identity and access
  • 36. Deployed runtime: email, signatures, and billing
  • 37. Deployed runtime: repositories, content, AI, and scheduled work
  • 38. Provision and ship: variables read by the operator CLI
  • 39. Ancillary operations and opt-in test controls
  • 40. When sample data appears

6. Configure the Trust Boundaries

  • 41. Secrets: the invariants that gate the boot
  • 42. Secret access, encryption, and audit
  • 43. Sign-in: bring an OIDC provider; passwords live there, not here
  • 44. Role rings: who can do what
  • 45. Provider setup and parity across deployment rows
  • 46. The external surface — every third party, in one place
  • 47. The two service deployments
  • 48. Security architecture

7. Ship the Instance

  • 49. Ship and verify
  • 50. Point your domain at the instance (optional)
  • 51. Drive it from the CLI
  • 52. Make it yours — white-label under your own brand
  • 53. First-ship lessons
  • 54. Canonical references

Live rollout checkpoint

The rollout checkpoint is the repository's deployment contract:

Six unconditional private buckets — assets, documents, exports, logs, PostgreSQL backups, and applications — plus optional archive and telemetry lanes when named. Project growth adds rows and logical key space; it never creates a cloud bucket per Project. The retired Portal's objects remain under a {project-code}/portal/ prefix in the applications bucket until an operator deletes them by hand. The documents bucket stores Project-scoped content-addressed projects/<code>/documents/<sha> objects, while Surreal asset rows carry the Project association, visibility, and provenance used for authorization. Marketing bytes remain available through the same-origin /assets/* application route while the bucket itself stays private and does not grant allUsers.

New clusters are created with --enable-fleet; the subsequent idempotent reconciliation can therefore report Changing existing fleet membership is not supported. Navigator treats only that exact response as already reconciled and continues; unrelated Fleet errors still stop setup.

Infrastructure is not deployment. A completed setup provisions infrastructure but not a running application. Ship an immutable release and prove /readyz, /version, certificate readiness, Restate registration, and the browser surface before recording the release handoff.

For a prefix <name>, set NAVIGATOR_GKE_CLUSTER_NAME=<name>, NAVIGATOR_GKE_CONTEXT=gke_<project>_<region>_<name>, NAVIGATOR_K8S_NAMESPACE=<name>, NAVIGATOR_VPC_NAME=<name>-vpc, NAVIGATOR_SUBNETWORK_NAME=<name>-subnet, NAVIGATOR_GATEWAY_IP_NAME=<name>-gateway-ip, NAVIGATOR_ASSETS_BUCKET=<name>-assets, NAVIGATOR_DOCUMENTS_BUCKET=<name>-documents, NAVIGATOR_EXPORTS_BUCKET=<name>-exports, NAVIGATOR_LOGS_BUCKET=<name>-logs, NAVIGATOR_APPLICATIONS_BUCKET=<name>-applications, NAVIGATOR_GCP_SERVICE_ACCOUNT_ID=<name>-web, NAVIGATOR_DRIVE_GCP_SERVICE_ACCOUNT_ID=<name>-drive, and NAVIGATOR_WEB_SECRET_NAME=<name>-web-secrets. Bucket names are global; choose an available name under your organization's naming convention.

Also set NAVIGATOR_GCP_PROJECT_ID, NAVIGATOR_GCP_LOCATION, NAVIGATOR_PUBLIC_HOST, NAVIGATOR_WORKFLOWS_HOST, NAV_BASE_URL=https://$NAVIGATOR_PUBLIC_HOST, NAVIGATOR_WORKFLOWS_URL=https://$NAVIGATOR_WORKFLOWS_HOST/, NAVIGATOR_WEB_IMAGE, and NAVIGATOR_ASSET_BASE_URL=$NAV_BASE_URL/assets in that row's $NAVIGATOR_DEPLOYMENTS_DIR/deployments/<row>/config.toml. Set that row's own NAVIGATOR_SURREAL_* coordinates and credentials in its encrypted secrets.enc.yaml.

Keep the mail rail complete in every deployment's encrypted secrets.enc.yaml: SENDGRID_API_KEY, SENDGRID_FROM_EMAIL, SENDGRID_INBOUND_SECRET, SENDGRID_INBOUND_PUBLIC_KEY, SENDGRID_EVENTS_SECRET, and SENDGRID_EVENTS_PUBLIC_KEY. Use credentials appropriate to that row's environment and host.

Provision each row with the same region-agnostic command — one run per private deployment row, with its coordinates exported from that row's config.toml. Set the variables below from the operator-managed root; the example does not create, decrypt, or provision private rows. Each run creates six core buckets and one Autopilot cluster; configured archive and telemetry lanes are additional:


: "${NAVIGATOR_DEPLOYMENTS_DIR:?set this to the operator-managed private deployment root}"
ROW="${ROW:?set this to the selected row name}"
CONFIG="$NAVIGATOR_DEPLOYMENTS_DIR/deployments/$ROW/config.toml"
set -a; eval "$(grep ' = "' "$CONFIG" | sed 's/ = /=/')"; set +a
hudson ops gcp setup --dry-run

Check every printed project, region, resource prefix, and the two API batches. Provision the registry hub once before the runtime stacks; it runs no workloads:


hudson ops gcp hub setup \
  --project-id "$NAVIGATOR_IMAGE_REGISTRY_PROJECT" --region "$NAVIGATOR_GCP_LOCATION" --dry-run
hudson ops gcp hub setup \
  --project-id "$NAVIGATOR_IMAGE_REGISTRY_PROJECT" --region "$NAVIGATOR_GCP_LOCATION"

Then apply the already-reviewed plans one deployment at a time. Keep staging first, and do not begin production until its command finishes:


set -a; eval "$(grep ' = "' "$CONFIG" | sed 's/ = /=/')"; set +a
hudson ops gcp setup

That is the live resource boundary, per deployment: six core buckets, plus any named archive/telemetry lanes, one VPC/subnet pair, one reserved gateway address, one Autopilot cluster, one KMS key, and two deployment service accounts. The command also enables the twenty-four required APIs in that runtime project. A completed command is not yet a deployed website; ops ship, DNS, and the browser checks later in this workshop remain required.

Setup provisions no database and generates no credential, so there is nothing printed to record. The store's own credentials go into $NAVIGATOR_DEPLOYMENTS_DIR/deployments/<row>/secrets.enc.yaml (sops set — the plaintext never touches disk), then hudson ops secrets apply --deployment "$ROW" --deployments-dir "$NAVIGATOR_DEPLOYMENTS_DIR"; rotation happens at the provider first, per docs/deployment-secrets.md.

Resolve every reserved address and record the public value as NAVIGATOR_GATEWAY_IP in the matching private config.toml. Keep this public infrastructure coordinate in the operator-managed deployment root:


for CONFIG in "$NAVIGATOR_DEPLOYMENTS_DIR"/deployments/*/config.toml; do
  set -a; eval "$(grep ' = "' "$CONFIG" | sed 's/ = /=/')"; set +a
  echo "${CONFIG%/config.toml}:"
  gcloud compute addresses describe "$NAVIGATOR_GATEWAY_IP_NAME" \
    --global --project "$NAVIGATOR_GCP_PROJECT_ID" --format 'value(address)'
done

Populate the matching local Kubernetes context before shipping a row:


: "${ROW:?set this to the selected row name}"
CONFIG="$NAVIGATOR_DEPLOYMENTS_DIR/deployments/$ROW/config.toml"
set -a; eval "$(grep ' = "' "$CONFIG" | sed 's/ = /=/')"; set +a
gcloud container clusters get-credentials \
  "$NAVIGATOR_GKE_CLUSTER_NAME" --region "$NAVIGATOR_GCP_LOCATION" \
  --project "$NAVIGATOR_GCP_PROJECT_ID"

The resulting context name must equal that config's NAVIGATOR_GKE_CONTEXT. Repeat once for each deployment you are operating.

The canonical matrix is the compact reference for every row.

Presenter notes

Pause on the isolation boundary: staging proves the shared mounted application, while the production data planes stay isolated. Point to the resource prefix column and verify that every database, bucket set, cluster, namespace, service account, Secret, and gateway address carries the row's prefix. Then demonstrate the dry run before discussing any billable live command.

View all slidesOpen display
← PreviousNext →
Neon Law
  • X opens in a new tab
  • LinkedIn opens in a new tab
  • YouTube opens in a new tab
  • API
  • Blog
  • Contact
  • Design
  • Glossary
  • Navigator
  • Notations
  • Presentations
  • Privacy
  • Team opens in a new tab
  • Terms
  • Testimonials
  • contact@neonlaw.com
  • +1 510 800 2090
  • California
    1515 20th StreetBakersfield, CA 93301
  • Nevada
    5150 Mae Anne AveSte 405-9002Reno, NV 89523
  • New York
    12 E 49th St18th FloorNew York, NY 10017
  • Washington
    1111 Main StSTE 201EVancouver, WA 98660
  • Justice Technology AssociationMission-Aligned Partner opens in a new tab
  • Proud member of Greater Vancouver ChamberGVC opens in a new tab

Attorney advertisement. Nothing here is legal advice without a signed retainer for an active project. Past results do not guarantee future outcomes.

Everyone deserves access to justice.Made with ❤️ in 🗽.

© 2026 Guieb & Shook PC

Powered by neon-law/navigator opens in a new tab26.11.17-rc.1GitHub stars 5