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

main
mdx 275 lines 7.82 KB
Raw
1 ---
2 title: Docker Swarm
3 description: Provision a swarm and deploy replicated services to it, from local dev to a remote VPS
4 ---
5
6 Docker Swarm is orchestration built into Docker: replicated services, rolling
7 updates, and overlay networking, without running Kubernetes. Alchemy models
8 the swarm itself (`Docker.Swarm`) and its workloads (`Docker.Service`,
9 overlay `Docker.Network`), targeting any engine through a `Docker.Context`.
10
11 ## Create the swarm
12
13 ```typescript
14 import * as Docker from "@alchemy.run/docker";
15
16 const swarm = yield* Docker.Swarm("swarm");
17 ```
18
19 `Docker.Swarm` is an idempotent `docker swarm init`: it turns the engine into
20 a single-node swarm whose node is both manager and worker. Regular
21 `docker run` and `docker build` usage of the engine is unaffected, and if the
22 resource is destroyed the node leaves the swarm again.
23
24 ## Use an existing swarm
25
26 A swarm you didn't create with `Docker.Swarm` is still fully usable. There
27 are two ways in, depending on who should own the swarm's lifecycle.
28
29 ### Reference it
30
31 ```typescript
32 const vps = yield* Docker.Context("vps", {
33 docker: "host=ssh://deploy@example.com",
34 });
35
36 const web = yield* Docker.Service("web", {
37 context: vps,
38 image: "nginx:alpine",
39 replicas: 3,
40 });
41 ```
42
43 Services never require a `Docker.Swarm` resource — they only need the engine
44 behind `context` to already be a swarm manager. Pass a `Docker.Context` (or a
45 plain context name) and Alchemy manages the workloads while the swarm itself
46 stays someone else's responsibility: destroying the stack removes the
47 services and leaves the swarm untouched.
48
49 ### Adopt it
50
51 ```typescript
52 const swarm = yield* Docker.Swarm("swarm").pipe(Alchemy.adopt(true));
53 ```
54
55 Adoption makes the swarm's lifecycle part of the stack. An engine that is
56 already in swarm mode is treated as foreign — the deploy fails with
57 `OwnedBySomeoneElse` until you opt in with `adopt(true)` (or `--adopt`).
58 After adoption Alchemy manages the swarm like one it created, **including
59 dissolving the node's membership on destroy** — so adopt only when this
60 stack should own the swarm, and reference otherwise.
61
62 ## Deploy a service
63
64 ```typescript
65 const web = yield* Docker.Service("web", {
66 context: swarm,
67 image: "nginx:alpine",
68 replicas: 2,
69 ports: [{ external: 8080, internal: 80 }],
70 });
71 ```
72
73 Passing the swarm as `context` does two things: the service deploys **after**
74 the swarm exists, and it targets the same engine. The swarm keeps `replicas`
75 copies of the container running, and the published port is reachable on every
76 node through the routing mesh.
77
78 ## Roll out a new image
79
80 ```diff lang="typescript"
81 const web = yield* Docker.Service("web", {
82 context: swarm,
83 - image: "ghcr.io/acme/web:1.0.0",
84 + image: "ghcr.io/acme/web:1.1.0",
85 replicas: 2,
86 + updateConfig: { order: "start-first", failureAction: "rollback" },
87 });
88 ```
89
90 Changing the image, replicas, environment, labels, networks, ports, mounts,
91 secrets or policies updates the service in place with `docker service update`.
92 Swarm starts each new task before stopping the old one, and if the new tasks
93 fail it rolls the service back and the deploy fails with
94 `DockerServiceUpdateFailed`. Changing the name, context, command or endpoint
95 mode still replaces the service.
96
97 ## Connect services on an overlay network
98
99 ```typescript
100 const network = yield* Docker.Network("app-net", {
101 context: swarm,
102 driver: "overlay",
103 });
104
105 const db = yield* Docker.Service("db", {
106 context: swarm,
107 image: "postgres:18-alpine",
108 networks: [{ name: network.name, aliases: ["postgres"] }],
109 });
110 ```
111
112 Overlay networks span the whole swarm. Services attached to the same network
113 reach each other by service name or alias — here, other services resolve the
114 database as `postgres`.
115
116 ## Write an effectful service
117
118 ```typescript
119 import * as Effect from "effect/Effect";
120 import * as HttpServerResponse from "effect/http/HttpServerResponse";
121
122 const api = yield* Docker.Service(
123 "api",
124 {
125 context: swarm,
126 main: import.meta.url,
127 port: 3000,
128 ports: [{ external: 8080, internal: 3000 }],
129 replicas: 2,
130 },
131 Effect.gen(function* () {
132 return {
133 fetch: Effect.gen(function* () {
134 return yield* HttpServerResponse.json({ ok: true });
135 }),
136 };
137 }),
138 );
139 ```
140
141 Instead of a pre-built image, `main` points at this module. Alchemy bundles
142 the program, bakes it into a content-addressed image built on the swarm's
143 engine, and serves the returned `fetch` handler with a Bun HTTP server on
144 `port`. The image is only rebuilt when the code changes; unchanged redeploys
145 are no-ops.
146
147 ## Add background work
148
149 ```diff lang="typescript"
150 +import { ServerHost } from "alchemy/Runtime/Process";
151 +import * as Schedule from "effect/Schedule";
152
153 const api = yield* Docker.Service(
154 // ...
155 Effect.gen(function* () {
156 + const host = yield* ServerHost;
157 + yield* host.run(
158 + Effect.log("heartbeat").pipe(
159 + Effect.repeat(Schedule.spaced("30 seconds")),
160 + Effect.asVoid,
161 + ),
162 + );
163 return {
164 fetch: Effect.gen(function* () {
165 return yield* HttpServerResponse.json({ ok: true });
166 }),
167 };
168 }),
169 );
170 ```
171
172 `host.run` registers a long-running loop that executes alongside the HTTP
173 server inside every replica.
174
175 ## Deploy to a remote machine
176
177 ### Point a context at the machine
178
179 ```typescript
180 const vps = yield* Docker.Context("vps", {
181 docker: "host=ssh://deploy@example.com",
182 });
183 ```
184
185 A Docker context is a pointer to another engine. With an SSH endpoint, every
186 Docker operation — including image builds — runs on that machine; nothing
187 needs to be installed there beyond Docker.
188
189 ### Initialize the swarm there
190
191 ```typescript
192 const swarm = yield* Docker.Swarm("swarm", {
193 context: vps,
194 advertiseAddr: "10.0.0.1",
195 });
196 ```
197
198 The same `Docker.Swarm`, now initializing the remote engine. `advertiseAddr`
199 is the address other swarm members would use to reach this manager — Docker
200 requires it when the host has several network interfaces. Like the other init
201 props, it only applies when the swarm is first created.
202
203 ### Services follow the swarm
204
205 ```typescript
206 const web = yield* Docker.Service("web", {
207 context: swarm,
208 image: "nginx:alpine",
209 replicas: 3,
210 });
211 ```
212
213 Nothing else changes: services take the swarm as `context`, so the same stack
214 deploys locally or to the VPS depending on which engine the swarm targets.
215
216 ## Grow to more nodes
217
218 Adding machines to the swarm is host-level setup (there is no resource for
219 node membership yet). On the manager, print the join command:
220
221 ```sh
222 docker swarm join-token worker
223 ```
224
225 Run the printed `docker swarm join --token ... <manager-ip>:2377` on each new
226 machine, and label nodes to target them with `placement.constraints`:
227
228 ```sh
229 docker node update --label-add zone=eu <node>
230 ```
231
232 Alchemy keeps managing the swarm's workloads through the manager. Note that
233 `main`-bundled images are built on the manager's local store — multi-node
234 swarms need images on a registry every node can reach (build with
235 `Docker.Image` + `registry` and pass the pushed ref as `image`).
236
237 ## Local dev and production
238
239 Putting it together: one stack that deploys a single replica to your local
240 swarm during `alchemy dev`, and three replicas to a VPS over SSH in
241 production.
242
243 ```typescript
244 import * as Alchemy from "alchemy";
245 import * as Docker from "@alchemy.run/docker";
246 import * as Effect from "effect/Effect";
247
248 export default Alchemy.Stack(
249 "swarm-app",
250 {
251 providers: Docker.providers(),
252 state: Alchemy.localState(),
253 },
254 Effect.gen(function* () {
255 const dev = yield* Alchemy.ALCHEMY_DEV;
256
257 const vps = dev
258 ? undefined
259 : yield* Docker.Context("vps", {
260 docker: "host=ssh://deploy@example.com",
261 });
262
263 const swarm = yield* Docker.Swarm("swarm", { context: vps });
264
265 const app = yield* Docker.Service("app", {
266 context: swarm,
267 image: "ghcr.io/acme/app:latest",
268 replicas: dev ? 1 : 3,
269 ports: [{ external: 8080, internal: 80 }],
270 });
271
272 return { service: app.name };
273 }),
274 );
275 ```