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 and Registry Caches

// Dockerfile: FROM registry.example.com/base:v1
const image = yield* Docker.Image("app", {
  name: "registry.example.com/app",
  build: {
    context: "./app",
    cacheFrom: ["type=registry,ref=registry.example.com/app:buildcache"],
    cacheTo: ["type=registry,ref=registry.example.com/app:buildcache,mode=max"],
  },
  // Authenticates the base-image pull and cache import/export, then the push.
  registry: {
    server: "registry.example.com",
    username: "deploy",
    password: Config.Redacted("REGISTRY_PASSWORD"),
  },
});

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",
});