(Video created using asciinema and agg)

Build development environments from a Dockerfile on Docker, Kubernetes, and OpenShift. Allow developers to modify their environment in a tight feedback loop.

• Supports devcontainer.json and Dockerfile
• Cache image layers with registries for speedy builds
• Runs on Kubernetes, Docker, and OpenShift

Browse the Coder Registry for example templates that use envbuilder to deploy DevContainers.

The easiest way to get started is by running the envbuilder Docker container that clones a repository specified by ENVBUILDER_GIT_URL, builds the image from a Dockerfile or devcontainer.json, and runs the $ENVBUILDER_INIT_SCRIPT in the freshly built container.

Tips:

• The /tmp/envbuilder directory persists demo data between commands. You can choose a different directory if needed.
• To clone a different branch, you append it to ENVBUILDER_GIT_URL in the form #refs/heads/my-branch. For example: https://github.com/coder/envbuilder-starter-devcontainer#refs/heads/boring-prompt.

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

Edit .devcontainer/Dockerfile to add htop:

vim .devcontainer/Dockerfile

- RUN apt-get install vim sudo -y
+ RUN apt-get install vim sudo htop -y

Exit the container and re-run the docker run command. After the build completes, htop should be available in the container! 🥳

To explore more examples, tips, and advanced usage, check out the following guides:

• Using Local Files
• Usage with Coder
• Container Registry Authentication
• Git Authentication
• Caching
• Custom Certificates & Proxies
• Users

The ENVBUILDER_SETUP_SCRIPT environment variable dynamically configures the user and init command (PID 1) after the container build process.

Note: TARGET_USER is passed to the setup script to specify who will execute ENVBUILDER_INIT_COMMAND (e.g., code).

Write the following to $ENVBUILDER_ENV to shape the container's init process:

• TARGET_USER: Identifies the ENVBUILDER_INIT_COMMAND executor (e.g., root).
• ENVBUILDER_INIT_COMMAND: Defines the command executed by TARGET_USER (e.g. /bin/bash).
• ENVBUILDER_INIT_ARGS: Arguments provided to ENVBUILDER_INIT_COMMAND (e.g., -c 'sleep infinity').

# init.sh - Change the init if systemd exists
if command -v systemd >/dev/null; then
  echo "Hey 👋 $TARGET_USER"
  echo ENVBUILDER_INIT_COMMAND=systemd >> $ENVBUILDER_ENV
else
  echo ENVBUILDER_INIT_COMMAND=bash >> $ENVBUILDER_ENV
fi

# Run envbuilder with the setup script
docker run -it --rm \
  -v ./:/some-dir \
  -e ENVBUILDER_SETUP_SCRIPT=/some-dir/init.sh \
  ...

You can see all the supported environment variables in this document.

This document keeps track of what parts of the Dev Container specification Envbuilder currently supports.

Feel free to create a new issue if you'd like Envbuilder to support a particular feature.

Devfiles automate and simplify development by adopting existing devfiles available in the public community registry.

Issue: #113

See Development for build instructions, dependency management notes, and common troubleshooting.