The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 182 lines 4.28 KB
Raw
1 ---
2 title: "Part 1: Your First Stack"
3 description: Install Alchemy, create a Stack with a Cloud Storage Bucket, and deploy it to Google Cloud.
4 sidebar:
5 order: 1
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 export const pkgs = `alchemy@latest @alchemy.run/gcp@latest effect @effect/platform-bun @effect/platform-node`;
12
13 In this part you install Alchemy, create a Stack with a Cloud Storage
14 Bucket, and deploy it to your Google Cloud project.
15
16 ## Prerequisites
17
18 - [Bun](https://bun.sh) or Node.js 24.11.1+
19 - A Google Cloud project and a service-account key that can create
20 what you deploy. See [Setup](/gcp/setup).
21
22 ## Create a project
23
24 Start with an empty directory and a `package.json`:
25
26 <PackageManagers init dir="my-app" />
27
28 ## Install dependencies
29
30 Install Alchemy, the GCP provider, and Effect:
31
32 <PackageManagers add={pkgs} />
33
34 ## Create the Stack
35
36 Every Alchemy program starts with a `Stack`. Create `alchemy.run.ts`:
37
38 ```typescript
39 // alchemy.run.ts
40 import * as Alchemy from "alchemy";
41 import * as GCP from "@alchemy.run/gcp";
42 import * as Effect from "effect/Effect";
43
44 export default Alchemy.Stack(
45 "MyApp",
46 {
47 providers: GCP.providers(),
48 state: GCP.state(),
49 },
50 Effect.gen(function* () {
51 // resources go here next
52 }),
53 );
54 ```
55
56 The first argument, `"MyApp"`, names the Stack. Alchemy uses it as a
57 prefix when it generates names for your resources.
58
59 `GCP.providers()` registers every GCP resource.
60
61 ## Where state lives
62
63 `state: GCP.state()` keeps deploy state in a Cloud Storage bucket in
64 your project, `alchemy-state-{project}`, created on the first deploy.
65 Because state lives in your project and not on your machine, the same
66 setup works on your laptop and in CI.
67
68 :::note[Other state stores]
69 For purely local iteration, use `Alchemy.localState()` instead. It
70 writes state under `.alchemy/` next to your code. See
71 [State store](/state-store).
72 :::
73
74 ## Connect your project
75
76 Point Alchemy at your project once:
77
78 ```sh
79 bun alchemy profile edit --add GCP
80 ```
81
82 Choose **gcloud login**, pick a gcloud configuration and sign in with your
83 Google account. (**Service account JSON** works too, with a
84 key file.) The choice is saved to your `default`
85 [profile](/environments/profiles).
86
87 ## Add a Bucket
88
89 Declare a Cloud Storage Bucket inside the Stack:
90
91 ```diff lang="typescript"
92 // alchemy.run.ts
93 import * as Alchemy from "alchemy";
94 import * as GCP from "@alchemy.run/gcp";
95 import * as Effect from "effect/Effect";
96
97 export default Alchemy.Stack(
98 "MyApp",
99 {
100 providers: GCP.providers(),
101 state: GCP.state(),
102 },
103 Effect.gen(function* () {
104 + const bucket = yield* GCP.Storage.Bucket("Bucket", {});
105 }),
106 );
107 ```
108
109 `Bucket` is the logical id. Alchemy generates a globally unique bucket
110 name from the Stack, stage, and logical id.
111
112 ## Return Stack outputs
113
114 Return the values you want to see after a deploy:
115
116 ```diff lang="typescript"
117 Effect.gen(function* () {
118 const bucket = yield* GCP.Storage.Bucket("Bucket", {});
119 +
120 + return {
121 + bucketName: bucket.bucketName,
122 + };
123 }),
124 ```
125
126 `bucket.bucketName` is an Output. It resolves during the deploy and
127 prints with the rest of the outputs.
128
129 ## Deploy
130
131 <PackageManagers run="alchemy deploy" />
132
133 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
134 [g]+[/g] [b]Bucket[/b] [d](GCP.Storage.Bucket)[/d]
135
136 Proceed?
137 ◉ Yes ○ No
138 [g]✓[/g] [b]Bucket[/b] [d](GCP.Storage.Bucket)[/d] [g]created[/g]
139 {
140 [s2]bucketName: "myapp-live-sam-bucket-a1b2c3d4",
141 }`} />
142
143 Alchemy shows the plan, asks for confirmation, creates the Bucket, and
144 prints the outputs.
145
146 ## Verify it worked
147
148 The Bucket shows up under **Cloud Storage → Buckets** in the console,
149 or with:
150
151 ```sh
152 gcloud storage ls
153 ```
154
155 Deploy again. Nothing changed, so there is nothing to do:
156
157 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
158
159 {
160 [s2]bucketName: "myapp-live-sam-bucket-a1b2c3d4",
161 }`} />
162
163 ## Destroy (optional)
164
165 `destroy` deletes everything the Stack created:
166
167 ```sh
168 bun alchemy destroy
169 ```
170
171 Deploy again afterwards if you try it. Part 2 builds on the Bucket.
172
173 ## Recap
174
175 You now have:
176
177 - An `alchemy.run.ts` with a Stack and a Cloud Storage Bucket
178 - A live Bucket in your Google Cloud project
179 - Stack outputs showing the Bucket name
180
181 In [Part 2](/gcp/tutorial/part-2), you put an HTTP service on Cloud
182 Run that reads and writes objects in this Bucket.