envbuilder

README

envbuilder

Build a development environment from devcontainer.json or Dockerfile inside of a container. Enable developers to customize their environment on pre-defined infrastructure.

• Supports devcontainer.json and Dockerfile
• Cache image layers with registries
• Runs in Docker, Kubernetes, or gVisor

Quickstart

The easiest way to play with envbuilder is to launch a Docker container that builds a sample image.

docker run -it --rm \
    -e REPO_URL=https://github.com/vercel/next.js \
    ghcr.io/coder/envbuilder

Documentation

Index

• Constants
• func CloneRepo(ctx context.Context, opts CloneRepoOptions) error
• func DefaultWorkspaceFolder(repoURL string) (string, error)
• func HijackLogrus(callback func(entry *logrus.Entry))
• func Run(ctx context.Context, options Options) error
• func SendLogsToCoder(ctx context.Context, client *agentsdk.Client, ...) (func(log agentsdk.StartupLog), error)
• type BuildParameters
• type CloneRepoOptions
• type DevContainer
  • func ParseDevcontainer(content []byte) (*DevContainer, error)
  • func (d *DevContainer) Compile(fs billy.Filesystem, devcontainerDir, scratchDir string) (*BuildParameters, error)
• type DevContainerBuild
• type Options
  • func SystemOptions(getEnv func(string) string) Options

Constants

const (
	// WorkspacesDir is the path to the directory where
	// all workspaces are stored by default.
	WorkspacesDir = "/workspaces"

	// EmptyWorkspaceDir is the path to a workspace that has
	// nothing going on... it's empty!
	EmptyWorkspaceDir = WorkspacesDir + "/empty"

	// MagicDir is where all envbuilder related files are stored.
	// This is a special directory that must not be modified
	// by the user or images.
	MagicDir = "envbuilder"
)

Functions

func CloneRepo

func CloneRepo(ctx context.Context, opts CloneRepoOptions) error

CloneRepo will clone the repository at the given URL into the given path. If a repository is already initialized at the given path, it will not be cloned again.

func DefaultWorkspaceFolder

func DefaultWorkspaceFolder(repoURL string) (string, error)

DefaultWorkspaceFolder returns the default workspace folder for a given repository URL.

func HijackLogrus

func HijackLogrus(callback func(entry *logrus.Entry))

HijackLogrus hijacks the logrus logger and calls the callback for each log entry. This is an abuse of logrus, the package that Kaniko uses, but it exposes no other way to obtain the log entries.

func Run

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

Run runs the envbuilder.

func SendLogsToCoder

func SendLogsToCoder(ctx context.Context, client *agentsdk.Client, logf func(format string, args ...any)) (func(log agentsdk.StartupLog), error)

SendLogsToCoder returns a function that will automatically queue and debounce logs to send to Coder.

Types

type BuildParameters

type BuildParameters struct {
	DockerfilePath string
	BuildContext   string
	BuildArgs      []string
	Cache          bool

	User string
	Env  []string
}

type CloneRepoOptions

type CloneRepoOptions struct {
	Path    string
	Storage billy.Filesystem

	RepoURL  string
	RepoAuth transport.AuthMethod
	Progress sideband.Progress
	Insecure bool
}

type DevContainer

type DevContainer struct {
	Image      string            `json:"image"`
	Build      DevContainerBuild `json:"build"`
	RemoteUser string            `json:"remoteUser"`
	RemoteEnv  map[string]string `json:"remoteEnv"`
}

func ParseDevcontainer

func ParseDevcontainer(content []byte) (*DevContainer, error)

ParseDevcontainer parses a devcontainer.json file.

func (*DevContainer) Compile

func (d *DevContainer) Compile(fs billy.Filesystem, devcontainerDir, scratchDir string) (*BuildParameters, error)

Compile returns the build parameters for the workspace. devcontainerDir is the path to the directory where the devcontainer.json file is located. scratchDir is the path to the directory where the Dockerfile will be written to if one doesn't exist.

type DevContainerBuild

type DevContainerBuild struct {
	Dockerfile string            `json:"dockerfile"`
	Context    string            `json:"context"`
	Args       map[string]string `json:"args"`
	Target     string            `json:"target"`
	CacheFrom  string            `json:"cache_from"`
}

type Options

type Options struct {
	// InitCommand is the command to run to initialize the workspace.
	// This is ran immediately after the container has been built.
	InitCommand string

	// InitArguments are the arguments to pass to the init command.
	InitArguments []string

	// CacheRepo is the name of the container registry
	// to push the cache image to. If this is empty, the cache
	// will not be pushed.
	CacheRepo string

	// DockerfilePath is a relative path to the workspace
	// folder that will be used to build the workspace.
	// This is an alternative to using a devcontainer
	// that some might find simpler.
	DockerfilePath string

	// FallbackImage is the image to use if no image is
	// specified in the devcontainer.json file and
	// a Dockerfile is not found.
	FallbackImage string

	// Logger is the logger to use for all operations.
	Logger func(format string, args ...interface{})

	// Filesystem is the filesystem to use for all operations.
	// Defaults to the host filesystem.
	Filesystem billy.Filesystem

	// ForceSafe ignores any filesystem safety checks.
	// This could cause serious harm to your system!
	// This is used in cases where bypass is needed
	// to unblock customers!
	ForceSafe bool

	// Insecure bypasses TLS verification when cloning
	// and pulling from container registries.
	Insecure bool

	// RepoURL is the URL of the Git repository to clone.
	// This is optional!
	RepoURL string

	// WorkspaceFolder is the path to the workspace folder
	// that will be built. This is optional!
	WorkspaceFolder string
}

func SystemOptions

func SystemOptions(getEnv func(string) string) Options

SystemOptions returns a set of options from environment variables.