Docker.Image reference

Image

Source: packages/docker/src/Image.ts

Builds, tags, and optionally pushes Docker images through the active Docker context.

This resource uses the Docker CLI and whatever daemon or remote context the CLI is configured to target. It is separate from Cloudflare.Container; registry image references are the boundary between Docker-managed images and cloud container platforms.

Image always builds from a Dockerfile. To pull (and optionally re-tag and push) an existing registry image, use Docker.RemoteImage.

Image: Building Images

const image = yield* Docker.Image("app", {
  name: "my-app",
  tag: "latest",
  build: {
    context: "./app",
    dockerfile: "Dockerfile",
    args: { NODE_ENV: "production" },
  },
});

Image: Build Secrets

// Dockerfile:
//   RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
const image = yield* Docker.Image("app", {
  name: "my-app",
  build: {
    context: "./app",
    secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
  },
});

The secret is mounted only into the RUN step that asks for it; it never lands in an image layer or the build history.

Image: Registry Push

const image = yield* Docker.Image("app", {
  name: "my-app",
  build: { context: "./app" },
  registry: {
    server: "ghcr.io",
    username: "octocat",
    password: Config.Redacted("GITHUB_TOKEN"),
  },
});

Image: Private Base Images

// Dockerfile: FROM registry.example.com/base:v1
const image = yield* Docker.Image("app", {
  name: "registry.example.com/app",
  build: { context: "./app" },
  // Authenticates the base-image pull, then the push.
  registry: {
    server: "registry.example.com",
    username: "deploy",
    password: Config.Redacted("REGISTRY_PASSWORD"),
  },
});

Image: Caching Build Layers

Builds reuse the local BuildKit cache of the machine they run on, and nothing but the image is pushed. A builder that has never built the image, such as a fresh CI runner, reruns every step. Set build.cache: true to keep every stage’s layers at the image repository’s :buildcache tag, so fresh builders skip unchanged steps. For another backend, pass BuildKit’s own --cache-from / --cache-to values as from and to.

Cache layers in the image’s registry

const image = yield* Docker.Image("app", {
  name: "registry.example.com/app",
  build: { context: "./app", cache: true },
  registry: {
    server: "registry.example.com",
    username: "deploy",
    password: Config.Redacted("REGISTRY_PASSWORD"),
  },
});

Cache layers in GitHub Actions

const image = yield* Docker.Image("app", {
  name: "my-app",
  build: {
    context: "./app",
    cache: {
      from: ["type=gha,scope=app"],
      to: ["type=gha,scope=app,mode=max"],
    },
  },
});

Image: Docker Context

const image = yield* Docker.Image("app", {
  name: "my-app",
  context: "remote-build",
  build: { context: "./app" },
});

RemoteImage

Source: packages/docker/src/RemoteImage.ts

Makes a source Docker image available through the active Docker context, optionally re-tagging it and pushing it to a registry.

The image is available to other Docker resources by imageRef. Use alwaysPull: false reuses the source tag when it exists in the configured Docker daemon, pulling only when it is missing. Set targetName/targetTag to re-tag the source image, and registry to push it (mirroring it from a source registry into your own, for example).

RemoteImage: Pulling Images

Pull nginx

const nginx = yield* Docker.RemoteImage("nginx", {
  name: "nginx",
  tag: "alpine",
});

Reuse an existing daemon tag

const postgres = yield* Docker.RemoteImage("postgres", {
  name: "postgres",
  tag: "18-alpine",
  alwaysPull: false,
});

RemoteImage: Re-tagging and Pushing

const mirrored = yield* Docker.RemoteImage("nginx-mirror", {
  name: "nginx",
  tag: "alpine",
  targetName: "acme/nginx",
  targetTag: "alpine",
  registry: {
    server: "ghcr.io",
    username: "octocat",
    password: Config.Redacted("GITHUB_TOKEN"),
  },
});

RemoteImage: Docker Context

const nginx = yield* Docker.RemoteImage("nginx", {
  name: "nginx",
  tag: "alpine",
  context: "remote-build",
});