@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
mdx 210 lines 5.5 KB
Raw
1 ---
2 title: "Part 3: Persist Data with a Volume"
3 description: Mount a Railway disk into your Service with MountVolume and store files that survive deploys.
4 sidebar:
5 order: 3
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 Your Service from [Part 2](/railway/tutorial/part-2) is stateless.
12 Writes to the container's root disk die with the container. In this
13 part you mount a Volume so files survive deploys.
14
15 ## Declare a Volume
16
17 A Volume is a standalone resource on the Project. Add it next to
18 the Project:
19
20 ```diff lang="typescript"
21 // src/project.ts
22 import * as Railway from "@alchemy.run/railway";
23
24 export const Site = Railway.Project("Site");
25 +
26 +export const Data = Railway.Volume("Data", {
27 + project: Site,
28 + mountPath: "/data",
29 + region: "us-west2",
30 +});
31 ```
32
33 The volume is disconnected until a Service mounts it. `mountPath` is
34 the path in the container. `region` must match the Service from
35 Part 2 — a Volume cannot move, and attaching across regions fails
36 the deploy.
37
38 ## Mount a disk into the Service
39
40 Inside the Service's constructor, `Railway.MountVolume(Data, { path })`
41 attaches that Volume at deploy time and hands you the path at
42 runtime:
43
44 ```diff lang="typescript"
45 // src/api.ts
46 import * as Railway from "@alchemy.run/railway";
47 import * as Effect from "effect/Effect";
48 import { HttpServerRequest } from "effect/http/HttpServerRequest";
49 import * as HttpServerResponse from "effect/http/HttpServerResponse";
50 -import { Site } from "./project.ts";
51 +import { Data, Site } from "./project.ts";
52
53 export default class Api extends Railway.Service<Api>()(
54 "Api",
55 {
56 project: Site,
57 main: import.meta.url,
58 region: "us-west2",
59 port: 3000,
60 },
61 Effect.gen(function* () {
62 + const mount = yield* Railway.MountVolume(Data, { path: "/data" });
63
64 return {
65 fetch: /* ... */,
66 };
67 }),
68 ) {}
69 ```
70
71 `MountVolume` is a **binding**: at deploy time it tells the Service
72 "attach this Volume at `/data`", and at runtime it hands you the
73 resolved `mount.path`.
74
75 ## Provide the binding layer
76
77 Bindings declare a capability; layers implement it. Provide
78 `MountVolumeLive` on the Service's constructor Effect:
79
80 ```diff lang="typescript"
81 Effect.gen(function* () {
82 const mount = yield* Railway.MountVolume(Data, { path: "/data" });
83
84 return {
85 fetch: /* ... */,
86 };
87 - }),
88 + }).pipe(Effect.provide(Railway.MountVolumeLive)),
89 ) {}
90 ```
91
92 ## Resolve FileSystem in the constructor
93
94 Yield `FileSystem` in the outer Effect. Close over it in `fetch`.
95 Do not yield it per request.
96
97 ```diff lang="typescript"
98 // src/api.ts
99 +import * as FileSystem from "effect/FileSystem";
100 // ...
101 Effect.gen(function* () {
102 const mount = yield* Railway.MountVolume(Data, { path: "/data" });
103 + const fs = yield* FileSystem.FileSystem;
104
105 return {
106 fetch: /* ... */,
107 };
108 }).pipe(Effect.provide(Railway.MountVolumeLive)),
109 ```
110
111 ## Write files with `PUT /:name`
112
113 The Volume is a directory. Use `fs` from the constructor:
114
115 ```diff lang="typescript"
116 fetch: Effect.gen(function* () {
117 const request = yield* HttpServerRequest;
118 const url = new URL(request.url, "http://service");
119 if (url.pathname === "/health") {
120 return HttpServerResponse.json({ ok: true });
121 }
122 + const file = `${mount.path}${url.pathname}`;
123 +
124 + if (request.method === "PUT") {
125 + const body = yield* request.text;
126 + yield* fs.writeFileString(file, body).pipe(Effect.orDie);
127 + return HttpServerResponse.empty({ status: 204 });
128 + }
129 +
130 return HttpServerResponse.text("Hello from Railway!");
131 }),
132 ```
133
134 ## Read files with `GET /:name`
135
136 Add the read branch, turning a missing file into a 404:
137
138 ```diff lang="typescript"
139 if (request.method === "PUT") {
140 const body = yield* request.text;
141 yield* fs.writeFileString(file, body).pipe(Effect.orDie);
142 return HttpServerResponse.empty({ status: 204 });
143 }
144
145 +if (request.method === "GET") {
146 + const text = yield* fs.readFileString(file).pipe(
147 + Effect.catch(() => Effect.succeed(undefined)),
148 + );
149 + if (text === undefined) {
150 + return HttpServerResponse.text("Not found", { status: 404 });
151 + }
152 + return HttpServerResponse.text(text);
153 +}
154
155 return HttpServerResponse.text("Hello from Railway!");
156 ```
157
158 ## Yield the Volume from the Stack
159
160 ```diff lang="typescript"
161 // alchemy.run.ts
162 -import { Site } from "./src/project.ts";
163 +import { Data, Site } from "./src/project.ts";
164
165 Effect.gen(function* () {
166 const site = yield* Site;
167 + yield* Data;
168 const api = yield* Api;
169 ```
170
171 ## Deploy
172
173 <PackageManagers run="alchemy deploy" />
174
175 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g], [y]1 to update[/y]
176
177 [g]+[/g] [b]Data[/b] [d](Railway.Volume)[/d]
178 [y]~[/y] [b]Api[/b] [d](Railway.Service)[/d]
179
180 Proceed?
181 ◉ Yes ○ No
182 [g]✓[/g] [b]Data[/b] [d](Railway.Volume)[/d] [g]created[/g]
183 [g]✓[/g] [b]Api[/b] [d](Railway.Service)[/d] [y]updated[/y]`} />
184
185 During the Service's deploy, Alchemy attaches the Volume at `/data`.
186
187 ## Try it out
188
189 ```sh
190 # Store a file on the Volume
191 curl -X PUT https://myapp-api-dev-a1b2c3d4.up.railway.app/hello.txt -d 'Hello, Volume!'
192
193 # Read it back
194 curl https://myapp-api-dev-a1b2c3d4.up.railway.app/hello.txt
195 # → Hello, Volume!
196 ```
197
198 Ship another code change and deploy — the file is still there.
199
200 ## Recap
201
202 You now have:
203
204 - A Volume in the Project mounted at `/data` on the API Service
205 - A Service reading and writing it through Effect's `FileSystem` —
206 no SDK, just files
207 - Data that outlives deploys
208
209 In [Part 4](/railway/tutorial/part-4), you'll store a Variable on
210 the Project and read it from the Service, then tear the stack down.