Skip to main content

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

Build docs developers (and LLMs) love

Get started for freeTalk to us