Skip to main content

@cdktn/bundler-docker

Container-based asset bundler for CDK Terrain.

DockerBundler runs a command in a docker container and stages the files the command writes as a TerraformAsset. To build a docker image, use @cdktn/provider-docker. Because the command runs in an image the caller pins, the artifact is reproducible across machines that share the same image, without requiring the toolchain on the host. For a build that runs directly on the host use @cdktn/bundler-local instead.

Usage

import { TerraformAsset, AssetType } from "cdktn";
import { DockerBundler, BundlingFileAccess } from "@cdktn/bundler-docker";

new TerraformAsset(this, "asset", {
  path: "./src",
  type: AssetType.DIRECTORY,
  bundler: new DockerBundler({
    image: "node:20",
    command: [
      "sh",
      "-c",
      "cp -r /asset-input /tmp/src && cd /tmp/src && npm ci && npm run build -- --out /asset-output",
    ],
    environment: { HOME: "/tmp" },
    bundlingFileAccess: BundlingFileAccess.BIND_MOUNT,
  }),
});

The container mounts the source directory read-only at /asset-input in both file access modes. The build writes its output to /asset-output. A build step that writes to /asset-input fails. Copy the source to a writable path inside the container first.

DockerBundler accepts only directory sources. A file source throws before the container starts.

Output type

outputType declares the shape of the artifact. The default, BundleOutputType.DIRECTORY, stages /asset-output as a directory. Set BundleOutputType.FILE when the command writes exactly one file, for example an archive. Use FILE with AssetType.FILE.

outputFileName names the staged file. When you set outputFileName and omit outputType, the output type is FILE.

Entrypoint

The entrypoint option sets --entrypoint to the first array element. The remaining elements go before command in the container arguments.

Bundler key

The bundler key covers the image, command, file access mode, environment, entrypoint, working directory, platform, network, security option, user, output type, and helper image.

Host paths

Bind mounts use --mount type=bind. Host paths that contain : (for example C:\work) or , work. The bundler resolves relative host paths to absolute paths.

Images

DockerBundler accepts only a registry reference in image. Build and push a custom image before you use it.

File access modes

  • BIND_MOUNT (default) — bind-mounts the host source and output directories into the container. Fastest, but requires the host paths to be shareable with the docker daemon.
  • VOLUME_COPY — copies the source into a named volume, runs the build, and copies the output back out. Works with a remote docker daemon where bind mounts are unavailable. Helper containers and volumes are cleaned up even when the build fails.

VOLUME_COPY uses a short-lived helper container to seed the input volume and set the ownership of the output volume. The build container mounts the input volume read-only and the output volume read-write. The helper runs as root (-u 0) with --entrypoint sh. It uses the same platform, network, and securityOpt as the build container. It reuses the build image for this by default, so the bundler never pulls an image the caller did not specify. If the build image has no POSIX shell or chown (e.g. a scratch- or distroless-based image), set volumeCopyHelperImage to any small image that does.

VOLUME_COPY accepts only user values that match /^\w[\w.:-]*$/.

The docker binary can be overridden with the CDK_DOCKER environment variable. If the docker binary is missing or not executable, bundle declines, so a ChainBundler continues with the next bundler. The bundler spawns the binary without a shell, so CDK_DOCKER must name an executable, not a .cmd or .bat wrapper.

License

Mozilla Public License 2.0

Metadata

Release files for cdktn-bundler-docker 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cdktn-bundler-docker 0.1.0
File Size Uploaded Provenance Actions
cdktn_bundler_docker-0.1.0.tar.gz 50.4 kB With provenance Details for cdktn_bundler_docker-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cdktn-bundler-docker 0.1.0
File Interpreter ABI Platform Actions
cdktn_bundler_docker-0.1.0-py3-none-any.whl Python 3 none any Details for cdktn_bundler_docker-0.1.0-py3-none-any.whl

Total release size: 98.4 kB

Release files / cdktn_bundler_docker-0.1.0.tar.gz

Download URL cdktn_bundler_docker-0.1.0.tar.gz
Size 50.4 kB
Tags Source
SHA-256 checksum
How to use checksums
89e424efdba16747a7d53457e466a53de9b3cfb912587d5f59865bdf3eade265
BLAKE2b-256 checksum
How to use checksums
ca1aa23436de4c4c10db8055fea9c41cb7a42ebefd0c22e62de5548214951644
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / cdktn_bundler_docker-0.1.0-py3-none-any.whl

Download URL cdktn_bundler_docker-0.1.0-py3-none-any.whl
Size 48.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5d617f98017d132319ea1e3265e299bf93bdf2944a6bcb3addf9e697e2154b06
BLAKE2b-256 checksum
How to use checksums
b45308f9ca6656d546f2a4138890905e4ea9d3ab4ece9ed049cffaabb32b5b3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for cdktn-bundler-docker 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cdktn_bundler_docker-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page