Skip to content

Setup

Check that the CLI reaches an engine:

Terminal window
docker version
Terminal window
pnpm add alchemy@latest @alchemy.run/docker@latest effect
alchemy.run.ts
import * as Alchemy from "alchemy";
import * as Docker from "@alchemy.run/docker";
import * as Effect from "effect/Effect";
export default Alchemy.Stack(
"MyApp",
{
providers: Docker.providers(),
state: Alchemy.localState(),
},
Effect.gen(function* () {
const web = yield* Docker.Container("web", {
image: "nginx:alpine",
ports: [{ external: 8080, internal: 80 }],
start: true,
});
return { ports: web.ports };
}),
);

There’s nothing to sign in to. Alchemy runs the docker CLI, and the CLI’s current context decides which engine it talks to. When Docker runs next to a cloud provider, merge the two: providers: Layer.merge(Cloudflare.providers(), Docker.providers()).

Terminal window
pnpm alchemy deploy

Pass the CLI to run:

providers: Docker.providers({ bin: "podman" }),

The DOCKER_BIN environment variable overrides bin on one machine, without changing the code:

Terminal window
DOCKER_BIN=/opt/homebrew/bin/docker pnpm alchemy deploy

A CI runner needs the docker CLI and an engine, and nothing else: no profile, no token. GitHub’s hosted Linux runners have both. To deploy to a remote engine from CI, give the job the SSH key for that host and declare a Docker.Context for it. Registry passwords come from Config, like any other secret. See Registries & credentials and CI.

Next, choose where your containers run in Engines & contexts.