Envbuilder

(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

Getting Started

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

Setup Script

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 existsif command -v systemd >/dev/null; then  echo "Hey 👋 $TARGET_USER"  echo ENVBUILDER_INIT_COMMAND=systemd >> $ENVBUILDER_ENVelse  echo 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  ...

Environment Variables

You can see all the supported environment variables inthis document.

Development Containers

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.

Devfile

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

Issue:#113

Contributing

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.

Constants¶

Variables¶

var ErrNoFallbackImage =errors.New("no fallback image has been specified")

Functions¶

func Run(ctxcontext.Context, optsoptions.Options, preExec ...func())error

func RunCacheProbe(ctxcontext.Context, optsoptions.Options) (v1.Image,error)

Types¶

type DockerConfig =configfile.ConfigFile