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

main
mdx 234 lines 6.53 KB
Raw
1 ---
2 title: "Part 4: Networking & Load Balancing"
3 description: Put your Service behind a managed Load Balancer on a private network, and lock the Server down with a Firewall.
4 sidebar:
5 order: 4
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 Right now your Service is served straight off the Server's public
12 IP, and every port on the Server is open to the internet. In this
13 final part you'll make it production-shaped: a **private Network**
14 between the machines, a managed **Load Balancer** in front, and a
15 **Firewall** that closes the app port to everyone but the LB.
16
17 :::note[Costs]
18 The `lb11` Load Balancer costs about €5.39/month, billed hourly like
19 everything else. The [cleanup step](#clean-up) at the end tears it
20 all down.
21 :::
22
23 ## Create a private Network
24
25 Add a Network to `src/server.ts` and attach the Server to it:
26
27 ```diff lang="typescript"
28 // src/server.ts
29 import * as Hetzner from "@alchemy.run/hetzner";
30
31 +export const Net = Hetzner.Network("net", {
32 + ipRange: "10.0.0.0/16",
33 + subnets: [
34 + { type: "cloud", networkZone: "eu-central", ipRange: "10.0.1.0/24" },
35 + ],
36 +});
37
38 export const Box = Hetzner.Server("box", {
39 serverType: "cx22",
40 image: "ubuntu-24.04",
41 location: "nbg1",
42 sshKeys: [Key],
43 + networks: [Net],
44 });
45
46 export const Data = Hetzner.Volume("data", { /* ... */ });
47 ```
48
49 `nbg1` lives in the `eu-central` network zone. Passing `Net` — a
50 module-scope resource declaration — directly in `networks` is
51 enough: resource-valued props accept the resource or an Effect
52 producing it, and Alchemy resolves the reference and orders the
53 deploy.
54
55 ## Add a Load Balancer
56
57 Declare the Load Balancer in `src/server.ts`, targeting the Server
58 over its **private** IP:
59
60 ```diff lang="typescript"
61 // src/server.ts
62 +export const Edge = Hetzner.LoadBalancer("edge", {
63 + location: "nbg1",
64 + loadBalancerType: "lb11",
65 + networks: [Net],
66 + targets: [{ type: "server", server: Box, usePrivateIp: true }],
67 + services: [
68 + {
69 + protocol: "http",
70 + listenPort: 80,
71 + destinationPort: 3000,
72 + healthCheck: {
73 + protocol: "http",
74 + port: 3000,
75 + interval: 3,
76 + timeout: 2,
77 + retries: 2,
78 + http: { path: "/health" },
79 + },
80 + },
81 + ],
82 +});
83 ```
84
85 The LB listens on port 80 and forwards to port 3000 on the Server,
86 reaching it through the private Network (`usePrivateIp: true`). Its
87 health check polls the same `/health` route the deploy already
88 uses — an unhealthy Service is pulled out of rotation automatically.
89
90 ## Lock down the Server
91
92 With traffic flowing through the private network, close the public
93 app port. Apply a Firewall to the Server that allows SSH from
94 anywhere but port 3000 only from inside the Network:
95
96 ```diff lang="typescript"
97 // src/server.ts
98 +export const Wall = Hetzner.Firewall("wall", {
99 + applyTo: [Box],
100 + rules: [
101 + {
102 + direction: "in",
103 + protocol: "tcp",
104 + port: "22",
105 + sourceIps: ["0.0.0.0/0", "::/0"],
106 + description: "ssh",
107 + },
108 + {
109 + direction: "in",
110 + protocol: "tcp",
111 + port: "3000",
112 + sourceIps: ["10.0.0.0/16"],
113 + description: "api via private net",
114 + },
115 + ],
116 +});
117 ```
118
119 A Hetzner Firewall is default-deny for inbound traffic: once
120 applied, only what a rule allows gets through. Outbound stays open.
121
122 ## Surface the Load Balancer URL
123
124 Yield the new resources from the Stack and output the LB address
125 instead of the Server's:
126
127 ```diff lang="typescript"
128 // alchemy.run.ts
129 import * as Alchemy from "alchemy";
130 import * as Hetzner from "@alchemy.run/hetzner";
131 +import * as Output from "alchemy/Output";
132 import * as Effect from "effect/Effect";
133 import Api from "./src/api.ts";
134 -import { Box } from "./src/server.ts";
135 +import { Box, Edge, Wall } from "./src/server.ts";
136
137 // ...
138 Effect.gen(function* () {
139 const server = yield* Box;
140 + const lb = yield* Edge;
141 + yield* Wall;
142 const api = yield* Api;
143
144 return {
145 ipv4: server.ipv4,
146 - url: api.url,
147 + url: Output.interpolate`http://${lb.ipv4}`,
148 };
149 }),
150 ```
151
152 `Output.interpolate` builds a string from resource outputs — the
153 LB's IP isn't known until it's created, so the template resolves
154 after deploy.
155
156 ## Deploy
157
158 <PackageManagers run="alchemy deploy" />
159
160 <Terminal content={`[u]Plan[/u]: [g]3 to create[/g], [y]1 to update[/y]
161
162 [g]+[/g] [b]net[/b] [d](Hetzner.Network)[/d]
163 [g]+[/g] [b]edge[/b] [d](Hetzner.LoadBalancer)[/d]
164 [g]+[/g] [b]wall[/b] [d](Hetzner.Firewall)[/d]
165 [y]~[/y] [b]box[/b] [d](Hetzner.Server)[/d]
166
167 Proceed?
168 ◉ Yes ○ No
169 [g]✓[/g] [b]net[/b] [d](Hetzner.Network)[/d] [g]created[/g]
170 [g]✓[/g] [b]box[/b] [d](Hetzner.Server)[/d] [y]updated[/y]
171 [g]✓[/g] [b]edge[/b] [d](Hetzner.LoadBalancer)[/d] [g]created[/g]
172 [g]✓[/g] [b]wall[/b] [d](Hetzner.Firewall)[/d] [g]created[/g]
173 {
174 [s2]ipv4: "203.0.113.10",
175 [s2]url: "http://198.51.100.7",
176 }`} />
177
178 ## Try it out
179
180 The app now answers on the Load Balancer:
181
182 ```sh
183 curl http://198.51.100.7/hello.txt
184 # → Hello, Volume!
185 ```
186
187 And the direct route is gone — the Firewall drops it:
188
189 ```sh
190 curl --max-time 5 http://203.0.113.10:3000/hello.txt
191 # → curl: (28) Connection timed out
192 ```
193
194 :::tip[Your own domain?]
195 Hetzner DNS is part of the provider too: declare a `Hetzner.Zone`
196 and a `Hetzner.RecordSet` pointing at `lb.ipv4`, and add a managed
197 `Hetzner.Certificate` to terminate TLS on the Load Balancer. See
198 [DNS](/hetzner/networking/dns) and
199 [Networking](/hetzner/networking#load-balancer).
200 :::
201
202 ## Clean up
203
204 You're done — tear everything down so the hourly billing stops:
205
206 <PackageManagers run="alchemy destroy" />
207
208 Alchemy deletes everything in reverse dependency order — Service,
209 Load Balancer, Firewall, Volume, Server, Network, SSH key.
210
211 ## Recap
212
213 Over four parts you built a complete, production-shaped deployment:
214
215 - A Server provisioned in seconds, with an Alchemy-managed deploy
216 key
217 - An HTTP Service bundled, shipped over SSH, and supervised by
218 systemd — updated only when its code hash changes
219 - A Volume mounted at `/data` whose contents outlive deploys
220 - A private Network, a health-checked Load Balancer, and a
221 default-deny Firewall
222
223 ## Where next
224
225 - [Services](/hetzner/compute/services) — background workers,
226 environment variables, multiple Services per Server.
227 - [Servers](/hetzner/compute/servers) — SSH access, snapshots,
228 placement groups, cloud-init.
229 - [DNS](/hetzner/networking/dns) — zones and records for your own
230 domain.
231 - [Testing](/testing) — deploy this stack from an integration test
232 and drive it over HTTP.
233 - [CI](/environments/ci) — run `alchemy deploy` from GitHub Actions
234 with `HCLOUD_TOKEN`.