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

main
mdx 102 lines 3.08 KB
Raw
1 ---
2 title: Volumes
3 description: Durable network block storage for Hetzner Servers — attach with props or VolumeAttachment, mount into Services with the MountVolume binding.
4 ---
5
6 A [`Volume`](/providers/hetzner/volume) is Hetzner's network block
7 storage: a durable disk (10 GB minimum) with its own lifecycle,
8 attachable to one Server at a time in the same location. Servers
9 come and go; Volumes keep the data.
10
11 ## Create a Volume
12
13 ```typescript
14 import * as Hetzner from "@alchemy.run/hetzner";
15
16 export const Data = Hetzner.Volume("data", {
17 size: 10,
18 format: "ext4",
19 location: "nbg1",
20 });
21 ```
22
23 `size` is in GB and can **grow in place** on a later deploy —
24 shrinking is impossible. `format` (`ext4` or `xfs`) and `location`
25 are create-only: changing either **replaces the Volume and destroys
26 its data**. The location must match the Server's.
27
28 ## Mount into a Service (recommended)
29
30 The `MountVolume` binding is the highest-level path: inside a
31 [Service](/hetzner/compute/services)'s constructor, bind the Volume to a
32 path and use it as a plain directory at runtime. Pass the `Data`
33 declaration directly — no yielding required:
34
35 ```typescript
36 export default class Api extends Hetzner.Service<Api>()(
37 "Api",
38 { server: Box, main: import.meta.url, port: 3000 },
39 Effect.gen(function* () {
40 const mount = yield* Hetzner.MountVolume(Data, { path: "/data" });
41
42 return {
43 fetch: Effect.gen(function* () {
44 const fs = yield* FileSystem.FileSystem;
45 const text = yield* fs.readFileString(`${mount.path}/hello.txt`);
46 // ...
47 }),
48 };
49 }).pipe(Effect.provide(Hetzner.MountVolumeLive)),
50 ) {}
51 ```
52
53 At deploy time the binding attaches the Volume to the Service's
54 Server, creates the directory, mounts the device, and appends an
55 `/etc/fstab` entry (`defaults,nofail`) so the mount survives
56 reboots. At runtime it hands you the resolved `mount.path` and
57 `mount.device`. Every step is idempotent, and two Services binding
58 the same `(volume, path)` on the same Server share one attach and
59 one mount.
60
61 If the Server is ever replaced, the Volume is detached from the old
62 machine and re-attached to the new one on the next deploy — the
63 data rides along.
64
65 ## Attach without a Service
66
67 For servers that manage their own filesystems, attach declaratively
68 instead. Either from the Volume side:
69
70 ```typescript
71 export const Data = Hetzner.Volume("data", {
72 size: 10,
73 location: "nbg1",
74 server: Box,
75 automount: true,
76 });
77 ```
78
79 Or as a standalone
80 [`VolumeAttachment`](/providers/hetzner/volumeattachment) — useful
81 when the Volume and Server are declared far apart:
82
83 ```typescript
84 yield* Hetzner.VolumeAttachment("data-on-box", {
85 volume: Data,
86 server: Box,
87 automount: true,
88 });
89 ```
90
91 With `automount: true` Hetzner mounts the disk under
92 `/mnt/HC_Volume_<id>`; otherwise mount `volume.linuxDevice`
93 yourself (e.g. via cloud-init or `Hetzner.Ssh`).
94
95 ## Where next
96
97 - [Tutorial part 3](/hetzner/tutorial/part-3) — mount a Volume into
98 a Service step by step.
99 - [Services](/hetzner/compute/services) — the platform doing the
100 mounting.
101 - [`Volume` reference](/providers/hetzner/volume) — every prop and
102 attribute.