The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: Setup |
| 3 | description: Connect alchemy to Google Cloud — project, service-account key, the APIs to enable, and Docker. |
| 4 | --- |
| 5 | |
| 6 | import PackageManagers from "../../../components/PackageManagers.astro"; |
| 7 | |
| 8 | export const pkgs = `alchemy@latest @alchemy.run/gcp@latest effect @effect/platform-bun @effect/platform-node`; |
| 9 | |
| 10 | ## Install |
| 11 | |
| 12 | <PackageManagers add={pkgs} /> |
| 13 | |
| 14 | ## What you need |
| 15 | |
| 16 | - **A GCP project** and its id. |
| 17 | - **Credentials** with enough IAM to create what you deploy: your own |
| 18 | Google account through `gcloud`, or a service-account key. |
| 19 | A working starting point is Cloud Run Admin, Storage Admin, Pub/Sub |
| 20 | Admin, Service Account Admin (Alchemy creates an `alch-*` service |
| 21 | account for each runtime), and Project IAM Admin (it grants roles to that |
| 22 | account). Add the admin role for anything else you declare — |
| 23 | Firestore, BigQuery, Secret Manager. |
| 24 | - **Docker running locally.** `GCP.Function`, `GCP.Run.Service`, |
| 25 | `GCP.Run.Job`, and `GCP.Run.WorkerPool` bundle your code and build a |
| 26 | container image before pushing it to Artifact Registry. |
| 27 | - **The APIs enabled** on the project for whatever you use: |
| 28 | `run.googleapis.com`, `artifactregistry.googleapis.com`, |
| 29 | `iam.googleapis.com`, `cloudresourcemanager.googleapis.com`, plus the |
| 30 | service-specific ones (`firestore.googleapis.com`, |
| 31 | `secretmanager.googleapis.com`, `pubsub.googleapis.com`, |
| 32 | `bigquery.googleapis.com`, `redis.googleapis.com`). |
| 33 | |
| 34 | ```sh |
| 35 | gcloud services enable run.googleapis.com artifactregistry.googleapis.com \ |
| 36 | iam.googleapis.com cloudresourcemanager.googleapis.com |
| 37 | ``` |
| 38 | |
| 39 | ## Credentials |
| 40 | |
| 41 | Run `alchemy profile edit --add GCP` and choose **gcloud login**, then pick |
| 42 | a gcloud configuration. Alchemy signs in to it with `gcloud auth login` if |
| 43 | it has no login yet, and deploys as its account into its project and |
| 44 | `compute/region`. It never activates the configuration, so each Alchemy |
| 45 | profile can use a different Google account while your gcloud stays as it is. |
| 46 | |
| 47 | ```sh |
| 48 | alchemy profile edit --add GCP |
| 49 | # when the login expires or is revoked: |
| 50 | alchemy profile refresh --provider GCP |
| 51 | ``` |
| 52 | |
| 53 | The profile names the configuration and nothing else, so no token is copied |
| 54 | into it: |
| 55 | |
| 56 | ```jsonc |
| 57 | // ~/.alchemy/profiles/<name>/gcp.json |
| 58 | { "method": "gcloud", "configuration": "work" } |
| 59 | ``` |
| 60 | |
| 61 | To set it up without prompts, create the configuration with gcloud first: |
| 62 | |
| 63 | ```sh |
| 64 | gcloud config configurations create work --no-activate |
| 65 | gcloud auth login --configuration=work |
| 66 | gcloud config set project my-project --configuration=work |
| 67 | alchemy profile edit --add GCP --method gcloud --set configuration=work |
| 68 | ``` |
| 69 | |
| 70 | A `project` or `region` in the profile overrides the configuration's. |
| 71 | |
| 72 | This needs the [Google Cloud CLI](https://cloud.google.com/sdk/docs/install). |
| 73 | Creating projects without an organization or folder also needs it: Google |
| 74 | only lets user accounts do that. |
| 75 | |
| 76 | To deploy as a service account instead, choose **Service account JSON** |
| 77 | and point at the key file. Alchemy stores the path in the profile. |
| 78 | |
| 79 | Environment variables need no profile. When a token or key file is set, |
| 80 | Alchemy uses it instead of the profile, and in CI (`CI=true`) the |
| 81 | environment is the only source: |
| 82 | |
| 83 | - `GOOGLE_PROJECT_ID` — project id (`GOOGLE_CLOUD_PROJECT` is accepted |
| 84 | as an alias). |
| 85 | - `GOOGLE_APPLICATION_CREDENTIALS` — path to the key file. |
| 86 | |
| 87 | Or `GOOGLE_ACCESS_TOKEN` plus `GOOGLE_PROJECT_ID` for a short-lived |
| 88 | token. On GKE with Workload Identity, neither is needed — the metadata |
| 89 | server is the last link in the chain. |
| 90 | |
| 91 | See [Profiles](/environments/profiles) for how credentials are stored |
| 92 | and switched. |
| 93 | |
| 94 | ## Register the provider |
| 95 | |
| 96 | ```typescript |
| 97 | // alchemy.run.ts |
| 98 | import * as Alchemy from "alchemy"; |
| 99 | import * as GCP from "@alchemy.run/gcp"; |
| 100 | import * as Effect from "effect/Effect"; |
| 101 | |
| 102 | export default Alchemy.Stack( |
| 103 | "App", |
| 104 | { providers: GCP.providers(), state: GCP.state() }, |
| 105 | Effect.gen(function* () { |
| 106 | return {}; |
| 107 | }), |
| 108 | ); |
| 109 | ``` |
| 110 | |
| 111 | `GCP.providers()` merges next to any other cloud's providers, so a |
| 112 | single stack can span GCP and Cloudflare or AWS. |
| 113 | |
| 114 | ## Choose a region |
| 115 | |
| 116 | Regional resources created without a `location` / `region` prop land in |
| 117 | the default region. It comes with the credential (the profile's |
| 118 | `region`, which `alchemy profile` asks for), else `us-central1`. To pin |
| 119 | a stack to a region regardless of the credential, provide |
| 120 | `GCP.Region(...)`: |
| 121 | |
| 122 | ```typescript |
| 123 | export default Alchemy.Stack( |
| 124 | "App", |
| 125 | { |
| 126 | providers: GCP.providers().pipe( |
| 127 | Layer.provideMerge(GCP.Region("europe-west1")), |
| 128 | ), |
| 129 | state: GCP.state(), |
| 130 | }, |
| 131 | program, |
| 132 | ); |
| 133 | ``` |
| 134 | |
| 135 | A resource that should live elsewhere takes an explicit `location`. |
| 136 | Changing the stack region never moves a deployed resource: its recorded |
| 137 | location wins. |
| 138 | |
| 139 | Requests for regional resources that Google only serves from a regional |
| 140 | endpoint (Secret Manager, Parameter Manager) go to |
| 141 | `{service}.{region}.rep.googleapis.com` automatically. For data |
| 142 | residency, send every regional request to its regional endpoint: |
| 143 | |
| 144 | ```typescript |
| 145 | GCP.providers().pipe( |
| 146 | Layer.provideMerge(GCP.RegionalEndpoints("prefer")), |
| 147 | ); |
| 148 | ``` |
| 149 | |
| 150 | ## Cleaning up |
| 151 | |
| 152 | `alchemy destroy` removes what a stack created, including the per-host |
| 153 | service accounts and their role grants. For a test project that has |
| 154 | drifted, `pnpm nuke:gcp` deletes Alchemy-managed resources across the |
| 155 | whole project — including every service account stamped |
| 156 | `alchemy-host`. Do not point it at a project you care about. |
| 157 | |
| 158 | ## Next steps |
| 159 | |
| 160 | - [Tutorial](/gcp/tutorial/part-1) — deploy your first Stack. |
| 161 | - [Cloud Run](/gcp/compute/cloud-run) — the runtime the rest of these |
| 162 | docs build on. |