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

main
mdx 138 lines 4.94 KB
Raw
1 ---
2 title: Build & push images
3 description: Build a container image from a Dockerfile, push it to a registry, and hand the resulting image reference to Cloudflare Containers or AWS ECS.
4 ---
5
6 This page is the canonical home for producing a **registry image
7 reference** — the artifact that cloud container platforms consume.
8 `Docker.Image` builds and pushes through your active Docker context;
9 what comes out the other end is an `imageRef` (and, after a push, a
10 `repoDigest`) that you pass to
11 [Cloudflare Containers](/cloudflare/compute/containers) or an
12 [AWS ECS task definition](/aws/compute/ecs).
13
14 All you need is a Docker daemon reachable from the CLI — see
15 [Setup](/docker/setup) if you haven't wired one up yet.
16
17 ## Build from a Dockerfile
18
19 ```typescript
20 // alchemy.run.ts
21 import * as Alchemy from "alchemy";
22 import * as Docker from "@alchemy.run/docker";
23 import * as Effect from "effect/Effect";
24
25 export default Alchemy.Stack(
26 "MyImages",
27 {
28 providers: Docker.providers(),
29 state: Alchemy.localState(),
30 },
31 Effect.gen(function* () {
32 const image = yield* Docker.Image("app", {
33 name: "my-app",
34 tag: "latest",
35 build: {
36 context: "./app",
37 dockerfile: "Dockerfile",
38 args: { NODE_ENV: "production" },
39 },
40 });
41
42 return { ref: image.imageRef, id: image.imageId };
43 }),
44 );
45 ```
46
47 The `build` block maps onto `docker build`: `context` (default: the
48 current working directory), `dockerfile` (default `"Dockerfile"`),
49 `args`, a multi-stage `target`, and a `platform` such as
50 `"linux/amd64"`, plus `cacheFrom`/`cacheTo` for build caching. Omit
51 `name` and alchemy generates one from the stack, stage, and logical
52 ID.
53
54 ## When it rebuilds
55
56 There is no source-hashing heuristic — `diff` literally runs
57 `docker build` and compares the resulting `imageId` against the last
58 deploy's output. If the build produces the same image, nothing
59 changed; if it produces a new one, the resource updates. The build
60 result is memoized per run (`Artifacts.cached`), so a plan followed
61 by a deploy builds once, not twice. Destroying the stack only
62 removes the local tag — nothing is deleted from any registry.
63
64 ## Push to a registry
65
66 ```typescript
67 const image = yield* Docker.Image("app", {
68 name: "my-app",
69 build: { context: "./app" },
70 registry: {
71 server: "ghcr.io",
72 username: "octocat",
73 password: Config.Redacted("GITHUB_TOKEN"),
74 },
75 });
76 ```
77
78 Set `registry` with the server (e.g. `ghcr.io`), a username, and a
79 `Redacted` password, and the image is pushed after every build —
80 `skipPush: true` keeps the build local while leaving the credentials
81 declared. The push never runs `docker login` and never touches your
82 global Docker config; credentials stay out of `argv` and your
83 keychain. On success the resource's `imageRef` includes the registry
84 host and `repoDigest` carries the immutable content digest.
85
86 ## Mirror and pin remote images
87
88 ```typescript
89 const mirrored = yield* Docker.RemoteImage("nginx-mirror", {
90 name: "nginx",
91 tag: "alpine",
92 targetName: "acme/nginx",
93 targetTag: "alpine",
94 registry: {
95 server: "ghcr.io",
96 username: "octocat",
97 password: Config.Redacted("GITHUB_TOKEN"),
98 },
99 });
100 ```
101
102 `Docker.RemoteImage` pulls an existing image instead of building
103 one, and `targetName`/`targetTag` re-tag it before pushing — the
104 standard shape for mirroring a public image into your own registry,
105 with the same `repoDigest` output as a built image. Set
106 `alwaysPull: false` to pin whatever tag is already in the daemon
107 rather than re-pulling on every deploy. Destroying the stack is a
108 deliberate no-op for remote images: the pulled tag may be shared by
109 unrelated stacks or developer workflows.
110
111 ## Hand the ref to your cloud
112
113 Pass `image.imageRef` (or `repoDigest`, for an immutable pin) to
114 whatever runs the container:
115 [Cloudflare Containers](/cloudflare/compute/containers) accept it as
116 a bring-your-own image, and an [ECS task definition](/aws/compute/ecs)
117 takes it as the container image, and a
118 [Kubernetes Deployment or Job](/kubernetes/workloads/images#build-images-with-dockerimage)
119 takes it as `image`. The registry reference is the
120 boundary — Cloudflare and AWS pull from the registry; no further
121 Docker wiring is involved. A reference already in Cloudflare's
122 managed registry (`registry.cloudflare.com/...`) is deployed as-is —
123 the Container skips its own pull-and-push round-trip.
124
125 Cloudflare Containers can also build and publish directly from their
126 `context` or `dockerfile` props, with caching enabled by default in the
127 application's generated repository. Set the Container's `publish.repository`
128 to choose a shared destination and reuse builds across stages;
129 see [Share published images across stages](/cloudflare/compute/containers#share-published-images-across-stages).
130 This is a Cloudflare Container option; standalone `Docker.Image` resources
131 continue to use the `registry` configuration shown above.
132
133 ## Where next
134
135 Reference:
136
137 - [Image API reference](/providers/docker/image)
138 - [RemoteImage API reference](/providers/docker/remoteimage)