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

main
mdx 284 lines 7.71 KB
Raw
1 ---
2 title: "Part 1: Your First Server"
3 description: Install Alchemy, create a Stack with a Hetzner Server, and deploy it.
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/hetzner@latest effect @effect/platform-bun @effect/platform-node`;
12
13 In this first part you'll install Alchemy and Effect, create a Stack
14 with a Hetzner Cloud Server, deploy it, and SSH in — all in under
15 five minutes.
16
17 ## Prerequisites
18
19 - [Bun](https://bun.sh) or Node.js 22+
20 - A Hetzner project and an API token — see [Setup](/hetzner/setup)
21 if you haven't created those yet
22
23 :::note[Costs]
24 Hetzner bills servers by the hour. The `cx22` used in this tutorial
25 costs about €4/month — a few cents for the time it takes to finish
26 all four parts. `alchemy destroy` tears everything down when you're
27 done.
28 :::
29
30 ## Create a project
31
32 Start with an empty directory and initialize a `package.json`:
33
34 <PackageManagers init dir="my-app" />
35
36 ## Install dependencies
37
38 Install `alchemy@latest`, `@alchemy.run/hetzner`, and `effect`:
39
40 <PackageManagers add={pkgs} />
41
42 ## Create the Stack
43
44 Every Alchemy program starts with a `Stack` — a collection of
45 Resources managed by Providers with state tracked between deploys.
46
47 Create an `alchemy.run.ts` file:
48
49 ```typescript
50 // alchemy.run.ts
51 import * as Alchemy from "alchemy";
52 import * as Effect from "effect/Effect";
53 import * as Layer from "effect/Layer";
54
55 export default Alchemy.Stack(
56 "MyApp",
57 {
58 // @error: ts(2345) Argument of type '{ providers: Layer.Layer<never, never, never>; }' is not assignable to parameter of type 'StackProps<never>'.
59 // @error: Property 'state' is missing in type '{ providers: Layer.Layer<never, never, never>; }' but required in type 'StackProps<never>'.
60 providers: Layer.empty,
61 },
62 Effect.gen(function* () {
63 // we'll add resources here next
64 }),
65 );
66 ```
67
68 TypeScript is unhappy: the `state` property is required. Every Stack
69 needs a **state store** so Alchemy can persist resource state between
70 deploys and compute diffs against your infrastructure.
71
72 ## Configure state
73
74 Hetzner has no state backend of its own, so we'll keep state on disk
75 with `Alchemy.localState()` — it writes to `.alchemy/` next to your
76 code, no setup required:
77
78 ```diff lang="typescript"
79 // alchemy.run.ts
80 import * as Alchemy from "alchemy";
81 import * as Effect from "effect/Effect";
82 import * as Layer from "effect/Layer";
83
84 export default Alchemy.Stack(
85 "MyApp",
86 {
87 providers: Layer.empty,
88 + state: Alchemy.localState(),
89 },
90 Effect.gen(function* () {
91 // we'll add resources here next
92 }),
93 );
94 ```
95
96 :::note[Other state stores]
97 Local state is perfect for a solo project. When you need state your
98 team and CI can share, swap in `Cloudflare.state()` or `AWS.state()`
99 — see [State Store](/state-store).
100 :::
101
102 ## Add a Server
103
104 Resources represent cloud infrastructure. Each resource is
105 `yield*`-ed inside the Stack's Effect generator.
106
107 Let's declare a Server — Hetzner's virtual machine — and observe the
108 type error:
109
110 ```diff lang="typescript"
111 // alchemy.run.ts
112 import * as Alchemy from "alchemy";
113 +import * as Hetzner from "@alchemy.run/hetzner";
114 import * as Effect from "effect/Effect";
115 import * as Layer from "effect/Layer";
116
117 export default Alchemy.Stack(
118 "MyApp",
119 {
120 providers: Layer.empty,
121 // @error: ts(2322) Type 'Layer<never, never, never>' is not assignable to type 'Layer<NoInfer<Providers>, never, StackServices>'.
122 // @error: Type 'Providers' is not assignable to type 'never'.
123 state: Alchemy.localState(),
124 },
125 Effect.gen(function* () {
126 + const server = yield* Hetzner.Server("box", {
127 + serverType: "cx22",
128 + image: "ubuntu-24.04",
129 + location: "nbg1",
130 + });
131 }),
132 );
133 ```
134
135 The props map directly onto Hetzner's console: `serverType` is the
136 size (`cx22` = 2 vCPU / 4 GB), `image` is the OS, and `location` is
137 the datacenter (`nbg1` is Nuremberg; `fsn1`, `hel1`, `ash`, `hil`,
138 and `sin` also exist).
139
140 TypeScript is telling us that `Layer.empty` doesn't provide
141 `Hetzner.Providers` — the layer required by `Server`.
142
143 ## Fix the Providers
144
145 Replace `Layer.empty` with `Hetzner.providers()` to resolve the type
146 error:
147
148 ```diff lang="typescript"
149 // alchemy.run.ts
150 import * as Alchemy from "alchemy";
151 import * as Hetzner from "@alchemy.run/hetzner";
152 import * as Effect from "effect/Effect";
153 -import * as Layer from "effect/Layer";
154
155 export default Alchemy.Stack(
156 "MyApp",
157 {
158 + providers: Hetzner.providers(),
159 state: Alchemy.localState(),
160 },
161 Effect.gen(function* () {
162 const server = yield* Hetzner.Server("box", {
163 serverType: "cx22",
164 image: "ubuntu-24.04",
165 location: "nbg1",
166 });
167 }),
168 );
169 ```
170
171 Now the program type-checks. The providers layer tells Alchemy how to
172 talk to the Hetzner Cloud API, and the type system ensures you never
173 forget to wire it up.
174
175 ## Add your SSH key
176
177 The server will boot without one, but registering your public key
178 lets you SSH straight in (and stops Hetzner emailing you a root
179 password). Declare an `SshKey` and pass it to the server:
180
181 ```diff lang="typescript"
182 Effect.gen(function* () {
183 + const key = yield* Hetzner.SshKey("laptop", {
184 + publicKey: "ssh-ed25519 AAAA... you@laptop",
185 + });
186
187 const server = yield* Hetzner.Server("box", {
188 serverType: "cx22",
189 image: "ubuntu-24.04",
190 location: "nbg1",
191 + sshKeys: [key],
192 });
193 }),
194 ```
195
196 Paste your own key from `~/.ssh/id_ed25519.pub` (create one with
197 `ssh-keygen -t ed25519` if you don't have it). Passing the resolved
198 `key` to `sshKeys` is your first **resource reference** — Alchemy
199 sees the dependency and orders the deploy so the key exists before
200 the server boots.
201
202 ## Return Stack outputs
203
204 Stack outputs let you see important values after a deploy. Return an
205 object from the generator to expose the server's public addresses:
206
207 ```diff lang="typescript"
208 const server = yield* Hetzner.Server("box", {
209 serverType: "cx22",
210 image: "ubuntu-24.04",
211 location: "nbg1",
212 sshKeys: [key],
213 });
214
215 + return {
216 + ipv4: server.ipv4,
217 + ipv6: server.ipv6,
218 + };
219 }),
220 ```
221
222 ## Deploy
223
224 Run `alchemy deploy` to create the key and the server:
225
226 <PackageManagers run="alchemy deploy" />
227
228 The first time you deploy, Alchemy prompts for Hetzner credentials —
229 paste the API token you generated in [Setup](/hetzner/setup). The
230 token is verified and saved to your **`default`**
231 [profile](/environments/profiles), so you won't be asked again.
232
233 <Terminal content={`[u]Plan[/u]: [g]2 to create[/g]
234
235 [g]+[/g] [b]laptop[/b] [d](Hetzner.SshKey)[/d]
236 [g]+[/g] [b]box[/b] [d](Hetzner.Server)[/d]
237
238 Proceed?
239 ◉ Yes ○ No
240 [g]✓[/g] [b]laptop[/b] [d](Hetzner.SshKey)[/d] [g]created[/g]
241 [g]✓[/g] [b]box[/b] [d](Hetzner.Server)[/d] [g]created[/g]
242 {
243 [s2]ipv4: "203.0.113.10",
244 [s2]ipv6: "2001:db8::1",
245 }`} />
246
247 Alchemy shows a plan, asks for confirmation, creates both resources,
248 and prints the stack outputs. A Hetzner server boots in about ten
249 seconds.
250
251 ## Verify it worked
252
253 The server is listed in your project in the
254 [Hetzner Cloud Console](https://console.hetzner.com), and you can SSH
255 straight in:
256
257 ```sh
258 ssh root@203.0.113.10
259 ```
260
261 Run `alchemy deploy` again. Because nothing changed, both resources
262 show as no-ops:
263
264 <Terminal content={`[u]Plan[/u]: [d]no changes[/d]
265
266 {
267 [s2]ipv4: "203.0.113.10",
268 [s2]ipv6: "2001:db8::1",
269 }`} />
270
271 This is the core loop — declare resources in code, deploy, and
272 Alchemy figures out what changed.
273
274 ## Recap
275
276 You now have:
277
278 - An `alchemy.run.ts` with a Stack, an SSH key, and a Server
279 - A live VM running Ubuntu in Nuremberg, booted in seconds
280 - Stack outputs showing its public IPv4 and IPv6 addresses
281
282 In [Part 2](/hetzner/tutorial/part-2), you'll deploy code to this
283 server — a `Hetzner.Service` that serves HTTP without you ever
284 writing a systemd unit or a Dockerfile.