Build development environments from a Dockerfile on Docker, Kubernetes, and OpenShift. Allow developers to modify their environment in a tight feedback loop.
- Supports
devcontainer.jsonandDockerfile - 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, builds the image from a Dockerfile, and runs the $ENVBUILDER_INIT_SCRIPT in the freshly built container.
Note: The
/tmp/envbuilderdirectory persists demo data between commands. You can choose a different directory if needed.
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/envbuilderEdit .devcontainer/Dockerfile to add htop:
vim .devcontainer/Dockerfile- RUN apt-get install vim sudo -y
+ RUN apt-get install vim sudo htop -yExit 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
The ENVBUILDER_SETUP_SCRIPT environment variable dynamically configures the user and init command (PID 1) after the container build process.
Note:
TARGET_USERis 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_COMMANDexecutor (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 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.
The table below keeps track of features we plan to implement. Feel free to create a new issue if you'd like Envbuilder to support a particular feature.
| Name | Description | Known Issues |
|---|---|---|
| Volume mounts | Volumes are used to persist data and share directories between the host and container. | #220 |
| Port forwarding | Port forwarding allows exposing container ports to the host, making services accessible. | #48 |
| Script init & Entrypoint | init adds a tiny init process to the container, and entrypoint sets a script to run at container startup. |
#221 |
| Customizations | Product-specific properties, e.g., VS Code settings and extensions. | #43 |
| Composefile | Define multiple containers and services for more complex development environments. | #236 |
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.22make- Docker daemon (for running tests)
Makefile targets:
build: Builds and tagsenvbuilder:latestfor your current architecture.develop: Runsenvbuilder:latestagainst 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.