Skip to content

feat(docker): introduce docker swarm resources - #972

Merged
sam-goodwin merged 11 commits into
alchemy-run:mainfrom
sbekrin:docker-swarm
Jul 28, 2026
Merged

sam-goodwin merged 11 commits into
alchemy-run:mainfrom
sbekrin:docker-swarm

Conversation

@sbekrin

@sbekrin sbekrin commented Jul 28, 2026 •

Copy link
Copy Markdown
Contributor

Adds Docker Swarm support, from provisioning the swarm to running effectful services on it:

  • Docker.Swarm — idempotent docker swarm init on a target engine; adoptable when the engine is already a swarm manager
  • Docker.Context — a named Docker CLI context (local socket, SSH host, TCP endpoint); existing Docker resources accept it via their context prop
  • Docker.Service — a replicated swarm service, promoted to an effectful platform like AWS.ECS.Service

Provision the swarm, deploy into it

const swarm = yield* Docker.Swarm("swarm"); // idempotent `docker swarm init`

const web = yield* Docker.Service("web", {
  context: swarm, // orders the service after the swarm + inherits its engine
  image: "nginx:alpine",
  replicas: 2,
  ports: [{ external: 8080, internal: 80 }],
});

Service and overlay Network take the swarm (or a Docker.Context / context name) as context. An engine that is already in swarm mode is foreign until adopt(true); destroying the swarm resource runs docker swarm leave --force. Multi-node membership (join tokens) remains host-level CLI setup for now.

Effectful services

Pass main and an Effect impl instead of a pre-built image. Alchemy bundles the program, builds a content-addressed image against the swarm's engine, and deploys it as a swarm service:

import * as Docker from "alchemy/Docker";
import { ServerHost } from "alchemy/Server/Process";

const Swarm = Docker.Swarm("swarm");

export default class Api extends Docker.Service<Api>()(
  "Api",
  // Class props may be an Effect: yield the swarm the service deploys into.
  Effect.gen(function* () {
    const swarm = yield* Swarm;
    return {
      context: swarm,
      main: import.meta.url,
      port: 3000,
      ports: [{ external: 8080, internal: 3000 }], // published via the routing mesh
      replicas: 2,
    };
  }),
  Effect.gen(function* () {
    const host = yield* ServerHost;
    yield* host.run(myBackgroundLoop); // long-running loops inside each replica

    return {
      fetch: Effect.gen(function* () {
        return yield* HttpServerResponse.json({ ok: true });
      }),
    };
  }),
) {}
  • the { fetch } handler is served by a Bun HTTP server on port; ports publishes it through the swarm routing mesh
  • the image is content-addressed (<name>:<hash>): unchanged code redeploys as a noop, changed code replaces the service with the new image
  • built on the target engine's local store, so single-node swarms need no registry; multi-node swarms build with Docker.Image + registry and pass the pushed ref as image

Tests

All deploy-through against real engines: the Docker.Swarm lifecycle (greenfield init, adopt-vs-refuse, destroy) runs on a disposable docker:dind engine so the host swarm is never touched; the Docker.Service suites self-provision a local single-node swarm and cover create/replace/adopt plus an end-to-end effectful service (fetch served, ServerHost.run loop observed over HTTP, noop redeploy, clean destroy).

See the step-by-step Docker Swarm guide covering local dev through remote SSH deployment.

sbekrin and others added 5 commits July 28, 2026 22:48
Docker.Service is now a Platform (like AWS.ECS.Service): pass `main` and an
Effect impl to bundle the program into a content-addressed image built
against the service's Docker context and deployed as a swarm service. The
impl returns `{ fetch }` (served by a Bun HTTP server on `port`) and can
register background loops via ServerHost.run.

- move createContainerRuntimeContext to Server/Process.ts (shared by ECS
  Task/Service and Docker.Service; re-exported from AWS/ECS/Task.ts)
- new internal Docker/ServiceImage.ts: rolldown bundle + bun bootstrap +
  generated Dockerfile, built with the Docker CLI against the target
  context; content hash drives diff and skips redundant builds
- diff compares the bundled code hash against output.code.hash; delete
  removes the built image best-effort
- cap swarm service physical names at 63 chars (swarm limit)
- full JSDoc (@section/@example) for Docker.Service and Docker.Context;
  relative imports in the PR alchemy-run#972 files
- e2e fixture + Service.platform.test.ts proving fetch serving, ServerHost
  background loops, noop redeploys, and clean destroy (service + image)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
# Conflicts:
#	packages/alchemy/src/Docker/Service.ts
@sam-goodwin

Copy link
Copy Markdown
Member

I updated your PR to include Effectful support for Docker.Service

sam-goodwin and others added 6 commits July 28, 2026 14:48
…swarm

Replace the provider-method diff unit tests with real engine lifecycle
deploys (replicas replace, context replace), and make the swarm suites
self-sufficient locally: ensureDockerSwarm idempotently runs
`docker swarm init --advertise-addr 127.0.0.1` when the engine is
swarm-inactive, so the tests run anywhere Docker runs. Every test ends
with stack.destroy() and the create test proves the service is gone.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The guide assumed an existing swarm without saying so. Add a "Setting up
the swarm" section (docker swarm init locally, over an SSH context, and
multi-node join + node labels) and state on the Service resource that the
target engine must be a swarm manager, pointing to Docker.Container for
non-swarm single containers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Docker.Swarm is an idempotent `docker swarm init` on a target engine:
observe swarm state, init when inactive (advertiseAddr/listenAddr/
defaultAddrPool/subnetSize apply at init only), adopt-gate engines that
are already swarm managers, and `docker swarm leave --force` on destroy.

Service and Network `context` now accept a Docker.Swarm (Docker.EngineRef)
so workloads deploy after the swarm exists and inherit its context:

```ts
const swarm = yield* Docker.Swarm("swarm");
const web = yield* Docker.Service("web", { context: swarm, image: "nginx:alpine" });
```

Tests run against a disposable docker:dind engine so the host's swarm
state is never touched: greenfield init + service deploy + destroy
(swarm dissolved, context removed), and adopt-vs-refuse on a
pre-initialized engine.

Rewrite the swarm guide step-by-step (one concept per snippet): create/
adopt the swarm, deploy services, overlay networks, effectful services,
remote SSH deploys, multi-node growth, dev-vs-prod stack.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
`main` only changes where the image comes from — the deploy still targets
a swarm manager, so every example now passes `context: swarm`, including
the class form via Effect-valued props yielding a module-level Swarm.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…t carries no credentials

- swarm.mdx "Use an existing swarm" now covers both paths: reference (pass
  a context to services; swarm lifecycle stays external) and adopt (swarm
  becomes stack-owned; destroy dissolves membership)
- same two examples on the Swarm resource JSDoc
- document on ContextProps.docker that the endpoint spec is connection
  metadata only — SSH auth is key/agent-based and TLS material is
  referenced by file path, so the string never needs Redacted

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit 1fd9bfc into alchemy-run:main Jul 28, 2026
sam-goodwin added a commit that referenced this pull request Jul 29, 2026
…swarm #972) into url redesign

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
sam-goodwin added a commit that referenced this pull request Jul 29, 2026
The website build's diff-indent check requires +/- markers as an extra
column before the code's full indentation, and at least one flush
context line so expressive-code doesn't strip a marker column from
every line. Fixes the telemetry tutorial's one-space-short markers and
anchors the swarm doc's fragment with its enclosing call.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants