@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, 06:00 UTC

main
mdx 362 lines 9.83 KB
Raw
1 ---
2 title: Services
3 description: A container in a Railway Project — a public image, or an Effect program Railway builds from a generated Dockerfile.
4 ---
5
6 A [`Service`](/providers/railway/service) is a container in a
7 Railway [Project](/railway/compute/projects). Point it at a public
8 image (`hashicorp/http-echo`), an Effect program (`main`), or a
9 GitHub repo (`repo` + `branch`). Several Services
10 share one Project. Canvas Functions — Effect-native or one TypeScript file, no
11 Docker, no registry — are [`Railway.Function`](/railway/compute/functions).
12
13 ## Image service
14
15 Pass `image` without `main`. Railway pulls the image and runs it.
16 No Docker. No registry. `url` is the generated `*.up.railway.app`
17 hostname.
18
19 ```typescript
20 const site = yield* Railway.Project("Site");
21 const api = yield* Railway.Service("Api", {
22 project: site,
23 image: "hashicorp/http-echo",
24 port: 5678,
25 });
26 ```
27
28 `project` is the parent [Project](/railway/compute/projects). Pass
29 the declaration directly, yielded or module-scope. Changing `project`
30 replaces the Service.
31
32 ## Declare an Effect-native Service
33
34 A Service is a class. Props describe the container. The Effect is
35 the program that runs in it.
36
37 ```typescript
38 // src/api.ts
39 import * as Railway from "@alchemy.run/railway";
40 import * as Effect from "effect/Effect";
41 import { Site } from "./project.ts";
42
43 export default class Api extends Railway.Service<Api>()(
44 "Api",
45 {
46 project: Site,
47 main: import.meta.url,
48 },
49 Effect.gen(function* () {
50 return {};
51 }),
52 ) {}
53 ```
54
55 `main: import.meta.url` is the bundle entrypoint. Alchemy bundles
56 this file with Rolldown, generates a Dockerfile (default
57 `FROM oven/bun:1`), and uploads the context. Railway builds the
58 image.
59
60 ## Serve HTTP with `fetch`
61
62 Return `fetch` from the constructor Effect to boot an HTTP server.
63
64 ```diff lang="typescript"
65 import * as Railway from "@alchemy.run/railway";
66 import * as Effect from "effect/Effect";
67 +import * as HttpServerResponse from "effect/http/HttpServerResponse";
68 import { Site } from "./project.ts";
69
70 export default class Api extends Railway.Service<Api>()(
71 "Api",
72 {
73 project: Site,
74 main: import.meta.url,
75 },
76 Effect.gen(function* () {
77 - return {};
78 + return {
79 + fetch: Effect.succeed(HttpServerResponse.text("hello")),
80 + };
81 }),
82 ) {}
83 ```
84
85 Omit `fetch` for a [background service](#background-services).
86
87 ## Schemaless RPC
88
89 Return methods next to `fetch`. Bind the class from another Service
90 or Function with `bindService` / `bindFunction`. Calls stay on
91 `{name}.railway.internal` with a shared token. Public
92 `*.up.railway.app` requests to `/__rpc__/*` get 401.
93
94 ```typescript
95 export default class Query extends Railway.Service<Query>()(
96 "Query",
97 { project: Site, main: import.meta.url },
98 Effect.gen(function* () {
99 return {
100 greet: (name: string) => Effect.succeed(`hello ${name}`),
101 };
102 }),
103 ) {}
104 ```
105
106 ```typescript
107 const query = yield* Railway.bindService(Query);
108 const greeting = yield* query.greet("sam");
109 ```
110
111 See [Functions](/railway/compute/functions#schemaless-rpc) for the
112 Function side of the same stub.
113
114 ## Pin a region
115
116 Railway picks a default region if you omit `region`. Updating it
117 is in place. See [Regions](/railway/compute/regions).
118
119 ```diff lang="typescript"
120 export default class Api extends Railway.Service<Api>()(
121 "Api",
122 - { project: Site, main: import.meta.url },
123 + { project: Site, main: import.meta.url, region: "us-west2" },
124 ```
125
126 ## Set the port
127
128 `port` is the port the process listens on. Alchemy writes it to
129 `PORT` and uses it as the generated `*.up.railway.app` `targetPort`.
130 Default `3000` for Effect-native Services. Pass `5678` for
131 `hashicorp/http-echo`.
132
133 ```diff lang="typescript"
134 export default class Api extends Railway.Service<Api>()(
135 "Api",
136 - { project: Site, main: import.meta.url, region: "us-west2" },
137 + { project: Site, main: import.meta.url, region: "us-west2", port: 3000 },
138 ```
139
140 ## The public URL
141
142 Yield the Service in the Stack. `api.url` is
143 `https://{name}.up.railway.app`. Alchemy creates that hostname with
144 `serviceDomainCreate`.
145
146 ```typescript
147 export default Alchemy.Stack(
148 "MyApp",
149 { providers: Railway.providers(), state: Alchemy.localState() },
150 Effect.gen(function* () {
151 const api = yield* Api;
152 return { url: api.url };
153 }),
154 );
155 ```
156
157 There is no IpAssignment resource. Railway's edge terminates TLS on
158 443 and forwards to `port`.
159
160 ## Healthcheck
161
162 `healthcheck` / `healthcheckPath` is the HTTP path Railway probes.
163 `healthcheckTimeout` is seconds. Railway load-balances public traffic
164 across whatever replicas are running. Alchemy does not pin a count.
165
166 ```typescript
167 const api = yield* Railway.Service("Api", {
168 project: site,
169 image: "hashicorp/http-echo",
170 port: 5678,
171 healthcheck: "/health",
172 healthcheckTimeout: 30,
173 });
174 ```
175
176 ## GitHub source, build, start, cron
177
178 `repo` is the third source, next to `image` and `main`. Requires a
179 GitHub connection on the Railway account. `buildCommand` /
180 `startCommand` are Railway's build/start (distinct from hosted
181 `build.install`). `cronSchedule` runs the service on a cron
182 expression.
183
184 ```typescript
185 const api = yield* Railway.Service("Api", {
186 project: site,
187 repo: "acme/web",
188 branch: "main",
189 rootDirectory: "apps/api",
190 buildCommand: "pnpm build",
191 startCommand: "pnpm start",
192 healthcheck: "/health",
193 });
194 ```
195
196 ## Canvas groups
197
198 [`Railway.Group`](/providers/railway/group) organizes services,
199 databases, volumes, and buckets on the canvas. IaC:
200 `group("Backend", [api, worker, db])`.
201
202 ```typescript
203 const backend = yield* Railway.Group("Backend", {
204 project: site,
205 resources: [api, worker, db],
206 });
207 ```
208
209 ## What a deploy does
210
211 For an image Service, Alchemy sets `source.image` and deploys with
212 `serviceInstanceDeployV2`. Docker is not required.
213
214 For an Effect-native Service, Alchemy bundles `main` with Rolldown
215 and generates a Dockerfile (`FROM oven/bun:1` unless you pass
216 `image`). If the hash matches the last successful deploy, it skips
217 the upload. Otherwise it tars the context and uploads it the same
218 way `railway up` does. Railway builds and deploys. No local Docker
219 daemon. No registry.
220
221 Changed code is a new Railway build and an in-place update.
222 Unchanged code is a no-op.
223
224 `build.install` ships packages unbundled, installed with npm inside
225 the image. Use it for native addons such as `sharp`.
226
227 ```typescript
228 export default class Api extends Railway.Service<Api>()(
229 "Api",
230 {
231 project: Site,
232 main: import.meta.url,
233 build: { install: ["sharp"] },
234 },
235 Effect.gen(function* () {
236 return {
237 fetch: Effect.succeed(HttpServerResponse.text("hello")),
238 };
239 }),
240 ) {}
241 ```
242
243 Override the base image with `image` (must still run bun when `main`
244 is set).
245
246 ## Config
247
248 Yield `Config` in the constructor. Alchemy reads the value from the env of
249 whoever deploys and writes it onto the Service. Do not pass
250 `env: { ... }` on a Service unless you are packing a known-plain
251 value.
252
253 ```typescript
254 import * as Config from "effect/Config";
255 import * as Redacted from "effect/Redacted";
256
257 export default class Api extends Railway.Service<Api>()(
258 "Api",
259 {
260 project: Site,
261 main: import.meta.url,
262 port: 3000,
263 },
264 Effect.gen(function* () {
265 const apiKey = yield* Config.Redacted("API_KEY");
266
267 return {
268 fetch: Effect.gen(function* () {
269 const token = Redacted.value(apiKey);
270 // ...
271 }),
272 };
273 }),
274 ) {}
275 ```
276
277 `Config.Redacted("API_KEY")` is `Redacted<string>`. Unwrap with
278 `Redacted.value` only where you need the raw string.
279
280 Alchemy also injects `PORT` (when `port` is set) and stack metadata.
281 For a secret Railway should own and inject into services, use
282 [`Railway.Variable`](/railway/data/variables).
283
284 ## Background services
285
286 Omit `fetch`. Use `ServerHost.run` for a long-running loop:
287
288 ```typescript
289 // src/worker.ts
290 import * as Railway from "@alchemy.run/railway";
291 import { ServerHost } from "alchemy/Runtime/Process";
292 import * as Effect from "effect/Effect";
293 import { Site } from "./project.ts";
294
295 export default class Worker extends Railway.Service<Worker>()(
296 "Worker",
297 {
298 project: Site,
299 main: import.meta.url,
300 region: "us-west2",
301 },
302 Effect.gen(function* () {
303 const host = yield* ServerHost;
304
305 yield* host.run(
306 Effect.gen(function* () {
307 return yield* Effect.never;
308 }).pipe(Effect.orDie),
309 );
310 }),
311 ) {}
312 ```
313
314 If the process exits, Railway restarts it.
315
316 ## Multiple Services, one Project
317
318 Each Service has its own image, env, and lifecycle. Point several
319 at the same `project`.
320
321 ```typescript
322 class Api extends Railway.Service<Api>()(
323 "Api",
324 { project: Site, main: import.meta.url, port: 3000 },
325 /* HTTP */
326 ) {}
327
328 class Worker extends Railway.Service<Worker>()(
329 "Worker",
330 { project: Site, main: import.meta.url },
331 /* mounts a disk, writes files */
332 ) {}
333 ```
334
335 A Volume attaches to one Service. See
336 [Volumes](/railway/data/volumes).
337
338 ## Logs
339
340 Service logs live in the Railway dashboard. `alchemy logs` (including
341 `--tail`) doesn't support Railway Services yet.
342
343 ## Where next
344
345 The [tutorial](/railway/tutorial/part-2) builds a Service step by
346 step. [Functions](/railway/compute/functions) covers Effect-native
347 and canvas Functions, including [schemaless RPC](/railway/compute/functions#schemaless-rpc).
348 [Volumes](/railway/data/volumes) covers `MountVolume`.
349 [Postgres](/railway/data/postgres) binds with `ConnectPostgres`.
350 [MySQL](/railway/data/mysql) and [Mongo](/railway/data/mongo) are the
351 same shape.
352 [Redis](/railway/data/redis) binds with `ReadWriteRedis`.
353 [Buckets](/railway/data/buckets) bind with `PutObject` / `GetObject`.
354 [Variables](/railway/data/variables) covers `Config.Redacted`,
355 `Railway.Variable`, and `Railway.ref`.
356 The [`Service` reference](/providers/railway/service) lists every
357 prop.
358 [Example: railway-project](https://github.com/alchemy-run/alchemy/tree/main/examples/railway-project)
359 is an image Service.
360 [Example: railway-service](https://github.com/alchemy-run/alchemy/tree/main/examples/railway-service)
361 is an Effect-native Service bound to Postgres, MySQL, Redis, an
362 Effect Function, and a Group.