https://github.com/coder/envbuilder
Build development environments from a Dockerfile on Docker, Kubernetes, and OpenShift. Enable developers to modify their development environment quickly.
https://github.com/coder/envbuilder
Last synced: 17 days ago
JSON representation
Build development environments from a Dockerfile on Docker, Kubernetes, and OpenShift. Enable developers to modify their development environment quickly.
- Host: GitHub
- URL: https://github.com/coder/envbuilder
- Owner: coder
- License: apache-2.0
- Created: 2023-03-27T21:02:59.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-27T23:42:20.000Z (29 days ago)
- Last Synced: 2025-04-02T22:35:28.722Z (23 days ago)
- Language: Go
- Homepage:
- Size: 2.45 MB
- Stars: 209
- Watchers: 5
- Forks: 40
- Open Issues: 60
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Envbuilder
_(Video created using [asciinema](https://github.com/asciinema/asciinema) and [agg](https://github.com/asciinema/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`](https://containers.dev/) and `Dockerfile`
- 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 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`.
```bash
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`:
```bash
vim .devcontainer/Dockerfile
```
```diff
- 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](./docs/using-local-files.md)
- [Usage with Coder](./docs/usage-with-coder.md)
- [Container Registry Authentication](./docs/container-registry-auth.md)
- [Git Authentication](./docs/git-auth.md)
- [Caching](./docs/caching.md)
- [Custom Certificates & Proxies](./docs/proxy.md)
- [Users](./docs/users.md)
## Setup Script
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'`).
```bash
# 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
...
```
## Environment Variables
You can see all the supported environment variables in [this document](./docs/env-variables.md).
### Development Containers
[This document](./docs/devcontainer-spec-support.md) keeps track of what parts of the Dev Container specification Envbuilder currently supports.
Feel free to [create a new issue](https://github.com/coder/envbuilder/issues/new) if you'd like Envbuilder to support a particular feature.
### Devfile
> [Devfiles](https://devfile.io/) automate and simplify development by adopting existing devfiles available in the [public community registry](https://registry.devfile.io/viewer).
Issue: [#113](https://github.com/coder/envbuilder/issues/113)
## Contributing
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](./docs/env-variables.md).