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
| 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. |