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
andDockerfile
- 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/envbuilder
directory 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/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
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 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 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.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 the environment variables documentation.