Envbuilder

Envbuilder is a tool used to build development environments from a Dockerfile or devcontainer.json on Docker, Kubernetes, and OpenShift. It allows developers to iterate on their environment configuration in a tight feedback loop by caching image layers with registries for fast builds.

Note: envbuilder is currently in maintenance mode and no new features are planned.

Envbuilder follows a specific hierarchy to decide which non-root user to use for the initialization command after dropping privileges:

1. devcontainer.json: It first attempts to use the containerUser defined in your devcontainer.json.
2. Dockerfile/Image: If containerUser is not specified, it looks up the last USER directive found in the specified Dockerfile or the base image.
3. Fallback: If no user is identified via the methods above, Envbuilder falls back to root.

Devcontainer Features Note: When installing Devcontainer Features, Envbuilder inserts a USER ${remoteUser} directive immediately after the feature installation directives. If remoteUser is not explicitly defined, it defaults to the containerUser.

When deciding how to provide sensitive information to your environment, choose based on the required lifecycle:

The fastest way to use Envbuilder is via its Docker container. The container performs the following steps:

1. Clones a repository specified by ENVBUILDER_GIT_URL.
2. Builds an image from a Dockerfile or devcontainer.json found in that repository.
3. Runs the command specified in $ENVBUILDER_INIT_SCRIPT (or $ENVBUILDER_INIT_COMMAND) inside the newly built container.

To clone a specific branch, append the ref to the URL in the format #refs/heads/branch-name (e.g., https://github.com/user/repo#refs/heads/my-branch).

To persist demo data between runs, mount a local directory to /tmp/envbuilder.

docker run -it --rm \
    -v /tmp/envbuilder:/workspaces \
    -e ENVBUILDER_GIT_URL=https://github.com/coder/envbuilder-starter-devcontainer \
    -e ENVBUILDER_INIT_SCRIPT=bash \
    ghcr.io/coder/envbuilder

If you do not have a remote Git repository or want to iterate quickly with local files, you can omit the ENVBUILDER_GIT_URL environment variable. Instead, mount your local directory containing your code to /workspaces/empty inside the Envbuilder container.

By default, Envbuilder searches for a devcontainer.json or Dockerfile in:

1. ${ENVBUILDER_WORKSPACE_FOLDER}
2. ${ENVBUILDER_WORKSPACE_FOLDER}/.devcontainer

# Create a sample Devcontainer and Dockerfile in the current directory
printf '{"build": { "dockerfile": "Dockerfile"}}' > devcontainer.json
printf 'FROM debian:bookworm\nRUN apt-get update && apt-get install -y cowsay' > Dockerfile

# Run envbuilder with the current directory mounted into `/workspaces/empty`.
docker run -it --rm -e ENVBUILDER_INIT_SCRIPT='bash' -v $PWD:/workspaces/empty ghcr.io/coder/envbuilder:latest

To target a specific branch when using ENVBUILDER_GIT_URL, use a refs/heads/ reference in the URL. This allows Envbuilder to pull from a branch other than the default one.

ENVBUILDER_GIT_URL=https://github.com/coder/envbuilder-starter-devcontainer/#refs/heads/my-feature-branch

If you want to test layer caching without setting up a remote registry, you can use a local directory by setting the ENVBUILDER_LAYER_CACHE_DIR environment variable and mounting a local volume to that path.

docker run -it --rm \
  -v /tmp/envbuilder-cache:/cache \
  -e ENVBUILDER_LAYER_CACHE_DIR=/cache \
  ...

To ensure that build secrets have not been accidentally persisted into your image layers or manifests, you can perform a manual inspection of the exported image.

1. Pull the image and save it as a tar archive.
2. Extract the archive.
3. Use tar and grep to scan all files within the image for the secret strings.

If the image is correctly built, the search for the secret values should return no results.

# 1. Save the image
docker pull localhost:5000/test-container:latest
docker save -o test-container.tar localhost:5000/test-container

# 2. Extract and scan
mkdir -p test-container
tar -xf test-container.tar -C test-container/
cd test-container

# Scan image layers for secrets
find . -type f | xargs tar -xOf 2>/dev/null | strings | grep -rn "secret-foo"

# Scan image manifests for secrets
find . -type f | xargs -n1 grep -rnI 'secret-foo'

To verify if a pre-built image already exists in your cache without actually performing a build, set ENVBUILDER_GET_CACHED_IMAGE=1.

This performs a "dry-run" build that consults ENVBUILDER_CACHE_REPO for each layer.

• If any layer is missing from the cache, Envbuilder exits with an error.
• If all layers are found, the image is emitted in the log output prefixed with ENVBUILDER_CACHED_IMAGE=....

# Set this to check for existing layers instead of building
ENVBUILDER_GET_CACHED_IMAGE=1