Get Started on GCP

Deploy Velt full self-hosting into your own GCP project. Hand the install guide to an AI coding agent, answer a handful of inputs, and complete the five human steps.

You do not run this deployment by hand. You give an AI coding agent the Install guide, and it executes the phases, stopping to ask you whenever a step needs a human.

Budget roughly 2 to 4 hours of wall clock. Most of that is waiting on Terraform and Firestore index creation, not typing.

New to full self-hosting? Read the Overview first for what the deployment contains and how it differs from partial self-hosting.

1. Check the prerequisites

   People and access

   • A GCP project you can administer (or create), with billing enabled.
   • Ability to create a Google OAuth client for console sign-in. This is one human console step.
   • Someone available to run an AI coding agent, or the shell commands themselves, for the duration.

   Tooling

   Tool	Why
   gcloud, firebase CLI	Project bootstrap, Hosting, Auth
   Terraform ≥ 1.5	Backend apply
   oras	Pull manifest, module, console, and SDK artifacts
   cosign	Verify signatures
   Node ≥ 20	Deployment-profiles CLI inside the module archive
   curl, python3, jq	Verify steps

   The agent checks exact versions itself in Phase 0 and stops if anything is missing.

2. Decide your inputs

   Decide these once, up front. The agent asks for all of them at the start of Phase 0 rather than interrupting you later.

   Input	Meaning
   PROJECT_ID / REGION	Where Cloud Run and Firebase live (us-central1 recommended)
   PROFILE + OPT_IN_MODULES	Feature surface, see Deployment profiles
   OWNER_EMAIL / admin emails	Console login identities
   appDomains	Production API key allowedDomains (SDK gate)
   GOOGLE_GEN_AI_API_KEY / ANTHROPIC_API_KEY	Operator-owned LLM keys
   Console host + SDK CDN base	Where static assets are served

   The Gemini and Anthropic keys are required even on the core profile. Memory embeddings and knowledge search run on Gemini; agent paths use Anthropic. Placeholder values pass the install and then fail at runtime, so use real keys you control.

3. Give your agent the guides

   This is the step that does the work. Point your AI coding agent at these two pages:

   • Install guide, the phase-by-phase procedure it executes.
   • Reference, the field-level contract it checks shapes against.

   Then start it with a prompt like this, filled in with the values you decided in step 2:

   You are deploying Velt full self-hosting into our own GCP project.
   
   Read the Velt full self-hosting Install guide and Reference pages I linked
   before you begin, and follow the Install guide phase by phase. Do not invent
   your own procedure.
   
   Inputs:
     PROJECT_ID      = <your-gcp-project-id>
     REGION          = us-central1
     PROFILE         = core
     OPT_IN_MODULES  =
     OWNER_EMAIL     = <[e-mail]>
     CONSOLE_BASE    = <https origin where the console will be served>
     CDN_BASE        = <https origin where the SDK will be served>
   
   Maintain velt-selfhost-state.json after every phase so this run can be
   resumed in a fresh session. Stop and ask me whenever a step needs a human.
   

   Keep velt-selfhost-state.json in your working directory. It is what lets a fresh session pick up where the last one stopped.

4. Stay available for the human steps

   Five moments need a person. The agent pauses and asks at each one.

   Moment	What you do
   Billing	Link a billing account to the GCP project
   OAuth client	Create the Google OAuth client for console sign-in
   Infosec scan	Sign off the image scan against the manifest’s signed findings
   DNS	Add the record, only if you use a custom domain
   Sign-in test	Sign in to the console for the first time

5. Wire your app

   Serving the SDK from your CDN only moves code. Runtime still defaults to SaaS until you pass selfHosted.

   import selfHosted from './velt-selfhosted-config.json';
   
   <VeltProvider
     apiKey="<production key from install Phase 3>"
     config={{
       proxyDomain: 'https://static.acme.com',  // origin only — path stays /lib/sdk@…/velt.js
       version: '6.0.0',                        // must match the hosted folder
       selfHosted,                              // generated in install Phase 5.1
     }}
   >
   

   Vanilla and Vue use initVelt(apiKey, { proxyDomain, version, selfHosted }).

   Rules that break production if violated:

   1. Path on the CDN is exactly /lib/sdk@<version>/velt.js with all chunks flat in that directory (@ is literal).
   2. CORS: Access-Control-Allow-Origin on every .js file (app origin or *). This is the number one failure mode.
   3. selfHosted.strict: true and deploymentProfile set to Terraform’s resolved enabledModules, never hand-derived.
   4. CSP: allow your CDN in script-src, and remove cdn.velt.dev once you cut over.

   Field-level shape: Reference, selfHosted config.

6. Confirm it is done

   The deployment is complete only when all four pass:

   1. Console sign-in as a seeded admin lands on the dashboard with the workspace and keys.
   2. The app loads velt.js and its chunks from your CDN, and window.Velt.version matches the pin.
   3. Creating a comment in the app persists and appears in the console data browser.
   4. A Network audit on both the app and console sessions shows no requests to velt.dev or other Velt-owned hosts.

What the agent does

Phase	What happens	You care because
0	Pull and cosign-verify the umbrella manifest; collect inputs; preflight tooling	A wrong or unsigned release means stop
1	Bootstrap GCP/Firebase; copy the image by digest into your Artifact Registry; infosec scan sign-off	The image never runs from Velt’s registry long-term
2	Terraform apply (Cloud Run, queues, IAM, secrets, console config emission)	The profile decides which services exist
3	Provision CLI: workspace, API keys, seeded planInfo	First admin and keys for the app
4	Deploy console bundle and velt-console-config.json; OAuth; sign-in test	Admin surface on your domain
5	Host the SDK on your CDN; generate velt-selfhosted-config.json; wire the app	Zero-egress requires selfHosted, proxyDomain, and a pinned version
6	Acceptance: console login, create a comment, see it in the console data browser, Network audit	Done only when all four pass

Maintain velt-selfhost-state.json after every phase so a fresh session can resume without guessing.

Troubleshooting

Symptom	Likely cause
SDK never loads	Missing CORS on CDN .js files, or path is not /lib/sdk@<version>/velt.js
SDK loads but data goes to Velt, or features are dead	Missing or incomplete selfHosted; strict is false; deploymentProfile is wrong
Console boots but can’t sign in	OAuth client or authorized domains not pointing at the console host
Callable returns “Api key not found” from a hand-built curl	Expected. Callables need a Firebase ID token, so use the app or console instead
Comment create fails with index errors	Check velt-sa Cloud Run logs for index-creation links, and report gaps to Velt

Full tables live in the Install guide’s troubleshooting appendix.

Upgrading later

Upgrades are a delta, not a reinstall. The Upgrade guide pulls and verifies the target manifest, diffs it against the release recorded in your state file, and runs only the tracks that changed.

Releases are migration-free today: new backend code reads existing data shapes. If that ever changes, the release notes and the manifest call it out and ship a dedicated migration runbook.