Repository files navigation

(Video created usingasciinema andagg)

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

• Supportsdevcontainer.json andDockerfile
• Cache image layers with registries for speedy builds
• Runs on Kubernetes, Docker, and OpenShift

The easiest way to get started is by running theenvbuilder Docker container that clones a repository specified byENVBUILDER_GIT_URL, builds the image from a Dockerfile ordevcontainer.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 toENVBUILDER_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 addhtop:

vim .devcontainer/Dockerfile

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

Exit the container and re-run thedocker 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

TheENVBUILDER_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 executeENVBUILDER_INIT_COMMAND (e.g.,code).

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

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

# init.sh - Change the init if systemd existsifcommand -v systemd>/dev/null;thenecho"Hey 👋$TARGET_USER"echo ENVBUILDER_INIT_COMMAND=systemd>>$ENVBUILDER_ENVelseecho ENVBUILDER_INIT_COMMAND=bash>>$ENVBUILDER_ENVfi# Run envbuilder with the setup scriptdocker run -it --rm  -v ./:/some-dir  -e ENVBUILDER_SETUP_SCRIPT=/some-dir/init.sh  ...

You can see all the supported environment variables inthis document.

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

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

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

Issue:#113

Buildingenvbuilder currentlyrequires 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 tagsenvbuilder:latest for your current architecture.
• develop: Runsenvbuilder: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 theenvironment variables documentation.