@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 162 lines 5.39 KB
Raw
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.