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

main
mdx 292 lines 8.42 KB
Raw
1 ---
2 title: "Part 2: Deploy a Service"
3 description: Bundle an Effect HTTP server, deploy it to your Hetzner Server as a systemd unit, and serve requests on a public URL.
4 sidebar:
5 order: 2
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 In [Part 1](/hetzner/tutorial/part-1) you deployed a Server. Now
12 you'll put code on it: a `Hetzner.Service` — an Effect program that
13 Alchemy bundles, copies over SSH, and runs as a systemd unit. No
14 Dockerfile, no unit files, no scp scripts.
15
16 ## Move the Server to a module
17
18 So far the resources live inside the Stack's generator. To let other
19 files reference them, declare them at **module scope** instead — a
20 resource declared this way is an Effect you can import and `yield*`
21 anywhere. Create `src/server.ts` and move the key and Server from
22 Part 1 into it:
23
24 ```typescript
25 // src/server.ts
26 import * as Hetzner from "@alchemy.run/hetzner";
27
28 export const Key = Hetzner.SshKey("laptop", {
29 publicKey: "ssh-ed25519 AAAA... you@laptop",
30 });
31
32 export const Box = Hetzner.Server("box", {
33 serverType: "cx22",
34 image: "ubuntu-24.04",
35 location: "nbg1",
36 sshKeys: [Key],
37 });
38 ```
39
40 Notice `sshKeys: [Key]` passes the declaration directly, without
41 yielding — resource-valued props accept the resource or an Effect
42 producing it. The logical ids are still `laptop` and `box`, so
43 Alchemy recognizes them as the same resources you deployed in
44 Part 1 — moving declarations between files doesn't recreate
45 anything.
46
47 ## Update the Stack
48
49 Import the Server and yield it from the Stack:
50
51 ```diff lang="typescript"
52 // alchemy.run.ts
53 import * as Alchemy from "alchemy";
54 import * as Hetzner from "@alchemy.run/hetzner";
55 import * as Effect from "effect/Effect";
56 +import { Box } from "./src/server.ts";
57
58 export default Alchemy.Stack(
59 "MyApp",
60 {
61 providers: Hetzner.providers(),
62 state: Alchemy.localState(),
63 },
64 Effect.gen(function* () {
65 - const key = yield* Hetzner.SshKey("laptop", {
66 - publicKey: "ssh-ed25519 AAAA... you@laptop",
67 - });
68 -
69 - const server = yield* Hetzner.Server("box", {
70 - serverType: "cx22",
71 - image: "ubuntu-24.04",
72 - location: "nbg1",
73 - sshKeys: [key],
74 - });
75 + const server = yield* Box;
76
77 return {
78 ipv4: server.ipv4,
79 ipv6: server.ipv6,
80 };
81 }),
82 );
83 ```
84
85 The key is still part of the graph — it's registered when the
86 Server's `sshKeys` reference resolves.
87
88 ## Create the Service file
89
90 A Service in Alchemy is a class — it has both an infrastructure
91 definition and a runtime implementation expressed as an Effect.
92 Create `src/api.ts` with the smallest possible declaration:
93
94 ```typescript
95 // src/api.ts
96 import * as Hetzner from "@alchemy.run/hetzner";
97 import * as Effect from "effect/Effect";
98 import { Box } from "./server.ts";
99
100 export default class Api extends Hetzner.Service<Api>()(
101 "Api",
102 { server: Box, main: import.meta.url },
103 Effect.gen(function* () {
104 return {};
105 }),
106 ) {}
107 ```
108
109 The `<Api>` type argument plus the empty `()` is a one-time bit of
110 ceremony — it lets TypeScript reason about `Api` as a typed handle.
111 `server: Box` says which machine this Service runs on, and
112 `main: import.meta.url` tells Alchemy this same file is the bundle
113 entrypoint: at deploy time it's bundled with Rolldown and shipped to
114 the Server.
115
116 ## Serve HTTP with `fetch`
117
118 Add a `fetch` field — Alchemy treats anything returned from the
119 `Effect.gen` block as the runtime API, and `fetch` specifically is
120 wired to an HTTP server listening on the Service's port:
121
122 ```diff lang="typescript"
123 // src/api.ts
124 import * as Hetzner from "@alchemy.run/hetzner";
125 import * as Effect from "effect/Effect";
126 +import * as HttpServerResponse from "effect/http/HttpServerResponse";
127 import { Box } from "./server.ts";
128
129 export default class Api extends Hetzner.Service<Api>()(
130 "Api",
131 { server: Box, main: import.meta.url },
132 Effect.gen(function* () {
133 - return {};
134 + return {
135 + fetch: Effect.succeed(HttpServerResponse.text("Hello from Hetzner!")),
136 + };
137 }),
138 ) {}
139 ```
140
141 `HttpServerResponse` is the same `effect/http` API used on
142 every other Alchemy runtime — the handler you write here would run
143 unchanged on Cloudflare Workers or AWS Lambda.
144
145 :::note
146 Notice the "Effect returning an Effect" pattern. The outer generator
147 is the **Construction phase** — it runs at deploy time and at process
148 startup. The inner `fetch` generator is the **Runtime phase** — it
149 runs per request.
150 :::
151
152 ## Set the port
153
154 Give the Service an explicit port so we know where to reach it:
155
156 ```diff lang="typescript"
157 export default class Api extends Hetzner.Service<Api>()(
158 "Api",
159 - { server: Box, main: import.meta.url },
160 + { server: Box, main: import.meta.url, port: 3000 },
161 ```
162
163 The port is written to the process environment as `PORT` and used to
164 build the Service's `url` attribute (`http://<server-ipv4>:<port>`).
165
166 ## Add a health route
167
168 When a Service declares a `port`, the deploy doesn't just start the
169 unit and hope — it polls `http://127.0.0.1:<port>/health` on the
170 Server until it answers, and fails the deploy (with the unit's
171 journal in the output) if it never does. Add the route:
172
173 ```diff lang="typescript"
174 // src/api.ts
175 +import { HttpServerRequest } from "effect/http/HttpServerRequest";
176 // ...
177 return {
178 - fetch: Effect.succeed(HttpServerResponse.text("Hello from Hetzner!")),
179 + fetch: Effect.gen(function* () {
180 + const request = yield* HttpServerRequest;
181 + const url = new URL(request.url, "http://service");
182 + if (url.pathname === "/health") {
183 + return yield* HttpServerResponse.json({ ok: true });
184 + }
185 + return HttpServerResponse.text("Hello from Hetzner!");
186 + }),
187 };
188 ```
189
190 ## Wire the Service into the Stack
191
192 The `Api` class is just a typed identifier — yielding it inside the
193 Stack's Effect is what registers the resource and starts the deploy:
194
195 ```diff lang="typescript"
196 // alchemy.run.ts
197 import * as Alchemy from "alchemy";
198 import * as Hetzner from "@alchemy.run/hetzner";
199 import * as Effect from "effect/Effect";
200 +import Api from "./src/api.ts";
201 import { Box } from "./src/server.ts";
202
203 export default Alchemy.Stack(
204 "MyApp",
205 {
206 providers: Hetzner.providers(),
207 state: Alchemy.localState(),
208 },
209 Effect.gen(function* () {
210 const server = yield* Box;
211 + const api = yield* Api;
212
213 return {
214 ipv4: server.ipv4,
215 - ipv6: server.ipv6,
216 + url: api.url,
217 };
218 }),
219 );
220 ```
221
222 Yielding `Api` returns the resolved Service outputs — the systemd
223 unit name, the port, and the public `url` we surface from the Stack.
224
225 ## Deploy
226
227 <PackageManagers run="alchemy deploy" />
228
229 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
230
231 [g]+[/g] [b]Api[/b] [d](Hetzner.Service)[/d]
232 [d]•[/d] [b]box[/b] [d](Hetzner.Server)[/d]
233
234 Proceed?
235 ◉ Yes ○ No
236 [g]✓[/g] [b]Api[/b] [d](Hetzner.Service)[/d] [g]created[/g]
237 {
238 [s2]ipv4: "203.0.113.10",
239 [s2]url: "http://203.0.113.10:3000",
240 }`} />
241
242 A lot just happened over one SSH connection:
243
244 1. `src/api.ts` was bundled with Rolldown into a single ESM file.
245 2. Alchemy connected to the Server using the **deploy key** it
246 injected when the Server was created — no SSH configuration on
247 your side.
248 3. It unpacked the bundle to `/opt/<unit>/` and wrote an
249 `EnvironmentFile` with `PORT` and the stack metadata. The
250 [Bun](https://bun.sh) runtime is already there — Alchemy's
251 cloud-init bootstrap installed it when the Server was created.
252 4. It wrote a systemd unit (`Restart=always`), enabled it, and
253 waited for `/health` to answer.
254
255 ## Try it out
256
257 ```sh
258 curl http://203.0.113.10:3000
259 # → Hello from Hetzner!
260 ```
261
262 The port is reachable because a fresh Hetzner server has **no
263 firewall** — every port is open until you apply one. In
264 [Part 4](/hetzner/tutorial/part-4) we'll lock this down.
265
266 ## Ship a change
267
268 Edit the greeting in `src/api.ts` and deploy again:
269
270 <Terminal content={`[u]Plan[/u]: [y]1 to update[/y]
271
272 [y]~[/y] [b]Api[/b] [d](Hetzner.Service)[/d]
273
274 Proceed?
275 ◉ Yes ○ No
276 [g]✓[/g] [b]Api[/b] [d](Hetzner.Service)[/d] [y]updated[/y]`} />
277
278 Alchemy hashes the bundle: if your code didn't change, the Service
279 is a no-op; if it did, the new bundle is copied up and the unit
280 restarted — a few seconds end to end.
281
282 ## Recap
283
284 You now have:
285
286 - An HTTP Service running on your Server as a systemd unit, with
287 `Restart=always` supervision
288 - A public URL serving requests, verified healthy at deploy time
289 - A code-hash-based update loop — edit, deploy, restarted
290
291 In [Part 3](/hetzner/tutorial/part-3), you'll attach a Volume and
292 persist data across deploys.