[](https://discord.gg/coder)

[](https://github.com/coder/envbuilder/releases/latest)

[](https://pkg.go.dev/github.com/coder/envbuilder)

[](./LICENSE)

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`

- Runs on Kubernetes, Docker, and OpenShift

<div align="center">

<a href="#gh-light-mode-only">

<img src="./scripts/diagram-light.svg">

</a>

<a href="#gh-dark-mode-only">

<img src="./scripts/diagram-dark.svg">

</a>

</div>

The easiest way to get started is to run the `envbuilder` Docker container that clones a repository, builds the image from a Dockerfile, and runs the `$INIT_SCRIPT` in the freshly built container.

-v /tmp/envbuilder:/workspaces \

-e GIT_URL=https://github.com/coder/envbuilder-starter-devcontainer \

-e INIT_SCRIPT=bash \

Edit `.devcontainer/Dockerfile` to add `htop`:

$ vim .devcontainer/Dockerfile

Exit the container, and re-run the `docker run` command... after the build completes, `htop` should exist in the container! 🥳

envbuilder uses Kaniko to build containers. You should [follow their instructions](https://github.com/GoogleContainerTools/kaniko#pushing-to-different-registries) to create an authentication configuration.

After you have a configuration that resembles the following:

{

"auths": {

"https://index.docker.io/v1/": {

"auth": "base64-encoded-username-and-password"

}

}

}

`base64` encode the JSON and provide it to envbuilder as the `DOCKER_CONFIG_BASE64` environment variable.

`GIT_USERNAME` and `GIT_PASSWORD` are environment variables to provide Git authentication for private repositories.

For access token-based authentication, follow the following schema (if empty, there's no need to provide the field):

| Provider | `GIT_USERNAME` | `GIT_PASSWORD` |

| ------------ | -------------- | -------------- |

| GitHub | [access-token] | |

| GitLab | oauth2 | [access-token] |

| BitBucket | x-token-auth | [access-token] |

| Azure DevOps | [access-token] | |

If using envbuilder inside of [Coder](https://github.com/coder/coder), you can use the `coder_git_auth` Terraform resource to automatically provide this token on workspace creation:

Cache layers in a container registry to speed up builds. To enable caching, [authenticate with your registry](#container-registry-authentication) and set the `CACHE_REPO` environment variable.

CACHE_REPO=ghcr.io/coder/repo-cache

Each layer is stored in the registry as a separate image. The image tag is the hash of the layer's contents. The image digest is the hash of the image tag. The image digest is used to pull the layer from the registry.

We don't support mounts, features, and many other primitives of `devcontainer.json`. We support the following:

- `image`

- `build`

- `runArgs`

- `workspaceFolder`

var cloned bool

var err error

cloned, err = CloneRepo(ctx, CloneRepoOptions{

image, err := executor.DoBuild(&config.KanikoOptions{

if err != nil {

return nil, err

}

endStage("🏗️ Built image!")

return image, err

// We only need to do this if we cloned!

// Git doesn't store file permissions as part of the repository.

if cloned {

endStage := startStage("🔄 Updating the ownership of the workspace...")

// By default, we clone the Git repository into the workspace folder.

// It will have root permissions, because that's the user that built it.

//

// We need to change the ownership of the files to the user that will

// be running the init script.

filepath.Walk(options.WorkspaceFolder, func(path string, info os.FileInfo, err error) error {

if err != nil {

return err

}

return os.Chown(path, uid, gid)

})

endStage("👤 Updated the ownership of the workspace!")

}

// Remove the Docker config secret file!

err = os.Remove(filepath.Join(os.Getenv("DOCKER_CONFIG"), "config.json"))

if err != nil && !os.IsNotExist(err) {

return fmt.Errorf("remove docker config: %w", err)

}

cloned, err := envbuilder.CloneRepo(context.Background(), envbuilder.CloneRepoOptions{

require.True(t, cloned)

cloned, err := envbuilder.CloneRepo(context.Background(), envbuilder.CloneRepoOptions{

require.False(t, cloned)

cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())

cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())

if strings.HasPrefix(scanner.Text(), "Error: ") {