Deploy the Neon Law Navigator

Agenda

Six steps, each tagged with its Bloom verb. You are the operator; the navigator CLI is the instrument:

• Create — stand up a billed project and authenticate.
• Predict — run --dry-run and read every API call before sending one.
• Identify — name the thirteen Google Cloud APIs the provisioner enables.
• Explain — describe the VPC, the Cloud SQL instance, and the three buckets.
• Execute — bring up the cluster, the static IP, and Fleet membership.
• Verify — ship the web image and confirm /readyz answers 200.

Bring your own project

navigator gcp setup provisions into a project; it does not create one. Start by creating a project and attaching a billing account, then authenticate so the CLI can act as you:

gcloud projects create your-project-id --name "Neon Law Navigator"
gcloud billing projects link your-project-id --billing-account "$BILLING_ACCOUNT_ID"
gcloud auth application-default login

Dry-run first

Before you change anything, read the plan. The --dry-run flag records every REST call and gcloud shell-out and prints them without sending traffic:

cargo run -p cli -- gcp setup --project-id your-project-id --dry-run

Network, SQL, and three buckets

With the APIs on, the CLI provisions the data plane over REST:

• A custom-mode VPC — no auto-created subnets, regional routing. A Cloud SQL for Postgres instance running Postgres 15, with a navigator database and a web user. Three Cloud Storage buckets, all uniform bucket-level access: -assets (public), -documents (private client documents), -logs (Nearline audit logs).

Secrets: the invariants that gate the boot

web fails loudly rather than degrading silently: a missing required value crashes startup with a structured enforce_prod_invariants error naming exactly what is absent. So a CrashLoopBackOff is almost always a missing secret:

kubectl logs deploy/navigator-web -n navigator

Sign-in: bring an OIDC provider, never store passwords

Neon Law Navigator never stores a password — no password column, no hashing crate. Identity is delegated to an OIDC-compatible provider you bring, via the standard Authorization Code + PKCE flow. Four env vars wire it:

OAUTH_ISSUER_URL=...        # the provider's issuer; discovery hangs off /.well-known/openid-configuration
OAUTH_CLIENT_ID=...
OAUTH_CLIENT_SECRET=...
OAUTH_REDIRECT_URI=https://www.your-domain.example/auth/callback

The external surface — every third party, in one place

Neon Law Navigator's whole external surface is six services, in two kinds — platform services (the cloud the stack runs on) and feature vendors (each lights up one capability and stubs out cleanly when unconfigured):

Ship and verify

Provisioning gives you an empty cluster; now ship web onto it. GitHub Actions builds and publishes every image publicly, so the cluster pulls anonymously — pin the dated tag and reconcile the overlay:

kubectl apply -k examples/deploy/k8s/gke

Drive it from the CLI

Once your instance answers /readyz, the navigator CLI runs the firm's whole matter flow against it from your terminal. It authenticates like gcloud auth login and lands a short-lived (~8h) token at ~/.navigator.json:

cargo install --path cli          # installs `navigator` on your PATH
# …or skip installing — the bin/navigator wrapper builds + runs it on first call:
export PATH="$PWD/bin:$PATH"       # then just call `navigator`

Make it yours — white-label under your own brand

Neon Law Navigator runs two brands from one binary, and every brand-identifying string is env-driven — so you can ship it under your own name without forking source. Describe your organization once in a navigator.yaml brand pack:

cp navigator.example.yaml navigator.yaml   # then edit: names, emails, domain, logos
cargo run -p cli -- rebrand verify           # validate the pack
cargo run -p cli -- rebrand apply --out .devx/brand.env   # NAVIGATOR_* env + logos copied to web/public/
source .devx/brand.env