(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

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

Building envbuilder currently requires a Linux system.

On macOS or Windows systems, we recommend using a VM or the provided .devcontainer for development.

Additional Requirements:

• go 1.22
• make
• Docker daemon (for running tests)

Makefile targets:

• build: Builds and tags envbuilder:latest for your current architecture.
• develop: Runs envbuilder:latest against a sample Git repository.
• test: Runs tests.
• test-registry: Stands up a local registry for caching images used in tests.
• docs/env-variables.md: Updated the environment variables documentation.