Docker

Manage Docker containers, images, networks, and volumes

Container

Create and manage Docker containers with support for port mappings, volumes, networks, and healthchecks.

Properties

image · Image | RemoteImage | string · required

Image to use for the container. Can be an Alchemy Image or RemoteImage resource or a string image reference.

name · string

Container name.

Default: ${app}-${stage}-${id}

command · string[]

Command to run in the container.

environment · Record<string, string | Secret>

Environment variables for the container.

ports · PortMapping[]

Port mappings between host and container.

Each mapping has:

• external: Host port
• internal: Container port
• protocol: “tcp” or “udp” (optional)

volumes · VolumeMapping[]

Volume mappings between host and container.

Each mapping has:

• hostPath: Path on host
• containerPath: Path in container
• readOnly: Whether volume is read-only (optional)

restart · 'no' | 'always' | 'on-failure' | 'unless-stopped'

Restart policy for the container.

networks · NetworkMapping[]

Networks to connect the container to.

Each mapping has:

• name: Network name or ID
• aliases: Network aliases (optional)

removeOnExit · boolean

Whether to remove the container when it exits.

start · boolean

Start the container after creation.

healthcheck · HealthcheckConfig

Healthcheck configuration with:

• cmd: Command to run (string or array)
• interval: Time between checks (Duration)
• timeout: Max time for check (Duration)
• retries: Consecutive failures needed
• startPeriod: Initialization time (Duration)
• startInterval: Check interval during start (Duration)

adopt · boolean

Whether to adopt the container if it already exists.

Default: false

Returns

id · string

Container ID assigned by Docker.

name · string

Container name.

state · 'created' | 'running' | 'paused' | 'stopped' | 'exited'

Current state of the container.

createdAt · number

Timestamp when the container was created.

inspect · () => Promise<ContainerRuntimeInfo>

Function to inspect the container and get detailed runtime information including port mappings.

Examples

Create a simple Nginx container

const webContainer = await Container("web", {
  image: "nginx:latest",
  ports: [
    { external: 8080, internal: 80 }
  ],
  start: true
});

console.log(webContainer.id);
console.log(webContainer.state); // "running"

Container with environment and volumes

const appContainer = await Container("app", {
  image: customImage,
  environment: {
    NODE_ENV: "production",
    API_KEY: alchemy.secret.env.API_KEY
  },
  volumes: [
    { hostPath: "./data", containerPath: "/app/data" }
  ],
  ports: [
    { external: 3000, internal: 3000 }
  ],
  restart: "always",
  start: true
});

Container with healthcheck

const apiContainer = await Container("api", {
  image: "my-api:latest",
  ports: [
    { external: 3000, internal: 3000 }
  ],
  healthcheck: {
    cmd: ["curl", "-f", "http://localhost:3000/health"],
    interval: "30s",
    timeout: "10s",
    retries: 3,
    startPeriod: "1m"
  },
  start: true
});

// Inspect container to get runtime info
const info = await apiContainer.inspect();
console.log(info.ports); // { "3000/tcp": 3000 }

---

Image

Build and manage Docker images from Dockerfiles with support for multi-stage builds, build arguments, and registry push.

Properties

name · string

Repository name for the image (e.g., “username/image”).

Default: The resource ID

tag · string

Tag for the image (e.g., “latest”).

Default: "latest"

build · DockerBuildOptions

Build configuration with:

• context: Build context directory
• dockerfile: Path to Dockerfile
• platform: Target platform (e.g., “linux/amd64”)
• args: Build arguments
• target: Target build stage
• cacheFrom: Cache sources
• cacheTo: Cache destinations
• options: Additional Docker build options

image · string | Image | RemoteImage

Image reference to tag (alternative to build).

registry · ImageRegistry

Registry credentials for pushing:

• username: Registry username
• password: Registry password (Secret)
• server: Registry server URL

skipPush · boolean

Whether to skip pushing the image to registry.

Default: false

Returns

name · string

Image name.

imageRef · string

Full image reference (name:tag).

imageId · string

Docker image ID.

repoDigest · string

Repository digest if pushed to registry.

builtAt · number

Timestamp when the image was built.

Examples

Build an image from Dockerfile

const appImage = await Image("app-image", {
  name: "myapp",
  tag: "latest",
  build: {
    context: "./app",
    dockerfile: "Dockerfile",
    args: {
      NODE_ENV: "production"
    }
  }
});

console.log(appImage.imageRef); // "myapp:latest"

Build and push to registry

const prodImage = await Image("prod-image", {
  name: "mycompany/myapp",
  tag: "v1.0.0",
  build: {
    context: ".",
    platform: "linux/amd64"
  },
  registry: {
    server: "ghcr.io",
    username: "mycompany",
    password: alchemy.secret.env.GITHUB_TOKEN
  }
});

console.log(prodImage.repoDigest); // Registry digest

---

RemoteImage

Pull and reference Docker images from remote registries.

Properties

name · string · required

Docker image name (e.g., “nginx”).

tag · string

Tag for the image (e.g., “latest” or “1.19-alpine”).

Default: "latest"

alwaysPull · boolean

Always attempt to pull the image, even if it exists locally.

Returns

imageRef · string

Full image reference (name:tag).

createdAt · number

Timestamp when the image was pulled.

Examples

const nginxImage = await RemoteImage("nginx", {
  name: "nginx",
  tag: "alpine"
});

const container = await Container("web", {
  image: nginxImage,
  start: true
});

---

Network

Create and manage Docker networks for container connectivity.

Properties

name · string

Network name.

Default: ${app}-${stage}-${id}

driver · 'bridge' | 'host' | 'none' | 'overlay' | 'macvlan' | string

Network driver to use.

Default: "bridge"

enableIPv6 · boolean

Enable IPv6 on the network.

Default: false

labels · Record<string, string>

Custom metadata labels for the network.

Returns

id · string

Network ID assigned by Docker.

name · string

Network name.

createdAt · number

Timestamp when the network was created.

Examples

const appNetwork = await Network("app-network", {
  name: "app-network",
  driver: "bridge"
});

const container1 = await Container("api", {
  image: "api:latest",
  networks: [{ name: appNetwork.name }]
});

const container2 = await Container("worker", {
  image: "worker:latest",
  networks: [{ name: appNetwork.name, aliases: ["task-worker"] }]
});

---

Volume

Create and manage Docker volumes for persistent data storage.

Properties

name · string

Volume name.

Default: ${app}-${stage}-${id}

driver · string

Volume driver to use.

Default: "local"

driverOpts · Record<string, string>

Driver-specific options (e.g., NFS configuration).

labels · VolumeLabel[] | Record<string, string>

Custom metadata labels for the volume.

adopt · boolean

Whether to adopt the volume if it already exists.

Default: false

Returns

id · string

Volume ID (same as name for Docker volumes).

name · string

Volume name.

mountpoint · string

Volume mountpoint path on the host.

createdAt · number

Timestamp when the volume was created.

Examples

Simple volume

const dataVolume = await Volume("data-volume", {
  name: "data-volume"
});

const container = await Container("app", {
  image: "myapp:latest",
  volumes: [
    { hostPath: dataVolume.name, containerPath: "/app/data" }
  ]
});

NFS volume

const dbVolume = await Volume("db-data", {
  name: "db-data",
  driver: "local",
  driverOpts: {
    "type": "nfs",
    "o": "addr=10.0.0.1,rw",
    "device": ":/path/to/dir"
  },
  labels: {
    "com.example.usage": "database-storage",
    "com.example.backup": "weekly"
  }
});