envbuilder

package module
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2024 License: Apache-2.0 Imports: 48 Imported by: 0

README

Envbuilder

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 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, 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:

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').
# 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.

Unsupported Features

Development Containers

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
Devfile

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

Issue: #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.

Documentation

Index

Constants

This section is empty.

Variables

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

ErrNoFallbackImage is returned when no fallback image has been specified.

Functions

func Run

func Run(ctx context.Context, opts options.Options, preExec ...func()) error

Run runs the envbuilder. Logger is the logf to use for all operations. Filesystem is the filesystem to use for all operations. Defaults to the host filesystem. preExec are any functions that should be called before exec'ing the init command. This is useful for ensuring that defers get run.

func RunCacheProbe added in v1.0.0

func RunCacheProbe(ctx context.Context, opts options.Options) (v1.Image, error)

RunCacheProbe performs a 'dry-run' build of the image and checks that all of the resulting layers are present in options.CacheRepo.

Types

type DockerConfig added in v0.0.3

type DockerConfig = configfile.ConfigFile

DockerConfig represents the Docker configuration file.

Directories

Path Synopsis
cmd
internal
scripts
testutil

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL