diff --git a/options.go b/options.go index 807f3f18..7f2f039d 100644 --- a/options.go +++ b/options.go @@ -13,44 +13,127 @@ type LoggerFunc func(level codersdk.LogLevel, format string, args ...interface{} // Options contains the configuration for the envbuilder. type Options struct { - SetupScript string - InitScript string - InitCommand string - InitArgs string - CacheRepo string - BaseImageCacheDir string - LayerCacheDir string - DevcontainerDir string + // SetupScript is the script to run before the init script. It runs as the + // root user regardless of the user specified in the devcontainer.json file. + // SetupScript is ran as the root user prior to the init script. It is used to + // configure envbuilder dynamically during the runtime. e.g. specifying + // whether to start systemd or tiny init for PID 1. + SetupScript string + // InitScript is the script to run to initialize the workspace. + InitScript string + // InitCommand is the command to run to initialize the workspace. + InitCommand string + // InitArgs are the arguments to pass to the init command. They are split + // according to /bin/sh rules with https://github.com/kballard/go-shellquote. + InitArgs 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 + // BaseImageCacheDir is the path to a directory where the base image can be + // found. This should be a read-only directory solely mounted for the purpose + // of caching the base image. + BaseImageCacheDir string + // LayerCacheDir is the path to a directory where built layers will be stored. + // This spawns an in-memory registry to serve the layers from. + LayerCacheDir string + // DevcontainerDir is the path to the folder containing the devcontainer.json + // file that will be used to build the workspace and can either be an absolute + // path or a path relative to the workspace folder. If not provided, defaults + // to `.devcontainer`. + DevcontainerDir string + // DevcontainerJSONPath is a path to a devcontainer.json file + // that is either an absolute path or a path relative to + // DevcontainerDir. This can be used in cases where one wants + // to substitute an edited devcontainer.json file for the one + // that exists in the repo. + // If neither `DevcontainerDir` nor `DevcontainerJSONPath` is provided, + // envbuilder will browse following directories to locate it: + // 1. `.devcontainer/devcontainer.json` + // 2. `.devcontainer.json` + // 3. `.devcontainer//devcontainer.json` DevcontainerJSONPath string - DockerfilePath string - BuildContextPath string - CacheTTLDays int64 - DockerConfigBase64 string - FallbackImage string - ExitOnBuildFailure bool - ForceSafe bool - Insecure bool - IgnorePaths []string - SkipRebuild bool - GitURL string - GitCloneDepth int64 + // DockerfilePath is the relative path to the Dockerfile that will be used to + // build the workspace. This is an alternative to using a devcontainer that + // some might find simpler. + DockerfilePath string + // BuildContextPath can be specified when a DockerfilePath is specified + // outside the base WorkspaceFolder. This path MUST be relative to the + // WorkspaceFolder path into which the repo is cloned. + BuildContextPath string + // CacheTTLDays is the number of days to use cached layers before expiring + // them. Defaults to 7 days. + CacheTTLDays int64 + // DockerConfigBase64 is the base64 encoded Docker config file that will be + // used to pull images from private container registries. + DockerConfigBase64 string + // FallbackImage specifies an alternative image to use when neither an image + // is declared in the devcontainer.json file nor a Dockerfile is present. If + // there's a build failure (from a faulty Dockerfile) or a misconfiguration, + // this image will be the substitute. Set ExitOnBuildFailure to true to halt + // the container if the build faces an issue. + FallbackImage string + // ExitOnBuildFailure terminates the container upon a build failure. This is + // handy when preferring the FALLBACK_IMAGE in cases where no + // devcontainer.json or image is provided. However, it ensures that the + // container stops if the build process encounters an error. + ExitOnBuildFailure bool + // 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 + // IgnorePaths is the comma separated list of paths to ignore when building + // the workspace. + IgnorePaths []string + // SkipRebuild skips building if the MagicFile exists. This is used to skip + // building when a container is restarting. e.g. docker stop -> docker start + // This value can always be set to true - even if the container is being + // started for the first time. + SkipRebuild bool + // GitURL is the URL of the Git repository to clone. This is optional. + GitURL string + // GitCloneDepth is the depth to use when cloning the Git repository. + GitCloneDepth int64 + // GitCloneSingleBranch clone only a single branch of the Git repository. GitCloneSingleBranch bool - GitUsername string - GitPassword string - GitHTTPProxyURL string - WorkspaceFolder string - SSLCertBase64 string - ExportEnvFile string - PostStartScriptPath string + // GitUsername is the username to use for Git authentication. This is + // optional. + GitUsername string + // GitPassword is the password to use for Git authentication. This is + // optional. + GitPassword string + // GitHTTPProxyURL is the URL for the HTTP proxy. This is optional. + GitHTTPProxyURL string + // WorkspaceFolder is the path to the workspace folder that will be built. + // This is optional. + WorkspaceFolder string + // SSLCertBase64 is the content of an SSL cert file. This is useful for + // self-signed certificates. + SSLCertBase64 string + // ExportEnvFile is the optional file path to a .env file where envbuilder + // will dump environment variables from devcontainer.json and the built + // container image. + ExportEnvFile string + // PostStartScriptPath is the path to a script that will be created by + // envbuilder based on the postStartCommand in devcontainer.json, if any is + // specified (otherwise the script is not created). If this is set, the + // specified InitCommand should check for the presence of this script and + // execute it after successful startup. + PostStartScriptPath string // Logger is the logger to use for all operations. Logger LoggerFunc - // Filesystem is the filesystem to use for all operations. - // Defaults to the host filesystem. + // Filesystem is the filesystem to use for all operations. Defaults to the + // host filesystem. Filesystem billy.Filesystem - // These options are specifically used when envbuilder - // is invoked as part of a Coder workspace. - CoderAgentURL *url.URL - CoderAgentToken string + // These options are specifically used when envbuilder is invoked as part of a + // Coder workspace. + CoderAgentURL *url.URL + // CoderAgentToken is the authentication token for a Coder agent. + CoderAgentToken string + // CoderAgentSubsystem is the Coder agent subsystems to report when forwarding + // logs. The envbuilder subsystem is always included. CoderAgentSubsystem []string }