devcontainer

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 2024 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultShell = "/bin/sh"
View Source 
const DefaultWorkingDir = "/workspace"

Variables

View Source 
var DefaultContainerCommand = []string{DefaultShell, "-c", "while sleep 1000; do :; done"}

Functions

This section is empty.

Types

type AppPort 

type AppPort []int

func (*AppPort) UnmarshalJSON 

func (a *AppPort) UnmarshalJSON(data []byte) error

type BuildProps 

type BuildProps struct {
	// Required when using a Dockerfile. The location of a Dockerfile that defines the contents of the container.
	// The path is relative to the devcontainer.json file.
	Dockerfile string `json:"dockerfile,omitempty"`

	// Path that the Docker build should be run from relative to devcontainer.json. For example, a value of ".." would allow you to reference content in sibling directories. Defaults to ".".
	Context string `json:"context,omitempty"`

	// A set of name-value pairs containing Docker image build arguments that should be passed when building a Dockerfile. Environment and pre-defined variables may be referenced in the values. Defaults to not set. For example: "build": { "args": { "MYARG": "MYVALUE", "MYARGFROMENVVAR": "${localEnv:VARIABLE_NAME}" } }
	Args map[string]*string `json:"args,omitempty"`

	// An array of Docker image build options that should be passed to the build command when building a Dockerfile. Defaults to []. For example: "build": { "options": [ "--add-host=host.docker.internal:host-gateway" ] }
	// NOTE: this options are currently ignored because it's too cumbersome to manually parse them into the types.ImageBuildOptions, there should be a better way to do it
	Options []string `json:"options,omitempty"`

	// A string that specifies a Docker image build target that should be passed when building a Dockerfile. Defaults to not set. For example: "build": { "target": "development" }
	Target string `json:"target,omitempty"`

	// A string or array of strings that specify one or more images to use as caches when building the image. Cached image identifiers are passed to the docker build command with --cache-from.
	CacheFrom StringArray `json:"cacheFrom,omitempty"`
}

func (*BuildProps) Equals 

func (b *BuildProps) Equals(other *BuildProps) bool

type Config 

type Config struct {
	Path string
	DockerImageProps
	DockerComposeProps
	LifecycleProps
	HostRequirements
	GeneralProperties
}

func ParseConfig 

func ParseConfig(configFile File) (*Config, error)

func (*Config) Equals 

func (c *Config) Equals(other *Config) bool

func (*Config) IsComposeDevContainer added in v0.4.0 

func (c *Config) IsComposeDevContainer() bool

func (*Config) IsDockerfileDevContainer added in v0.4.0 

func (c *Config) IsDockerfileDevContainer() bool

func (*Config) IsImageDevContainer added in v0.4.0 

func (c *Config) IsImageDevContainer() bool

type ContainerManager added in v0.4.0 

type ContainerManager interface {
	CreateContainer(ctx context.Context, image string, projectPath string, config Config) (string, error)
	StartContainer(ctx context.Context, containerId string) error
	StopContainer(ctx context.Context, containerId string) error
	Exec(ctx context.Context, containerId string, command []string) (ExecResult, error)
}

func NewDockerContainerManager added in v0.4.0 

func NewDockerContainerManager(dockerContainerCli client.ContainerAPIClient) ContainerManager

type Customizations 

type Customizations struct {
	Hide *HideCustomization `json:"hide,omitempty"`
}

func (Customizations) Equals 

func (c Customizations) Equals(other Customizations) bool

type DockerComposeProps 

type DockerComposeProps struct {
	// Required when using Docker Compose.
	DockerComposeFile StringArray `json:"dockerComposeFile,omitempty"`

	// Required when using Docker Compose.
	Service string `json:"service,omitempty"`

	RunServices []string `json:"runServices,omitempty"`
}

func (*DockerComposeProps) Equals 

func (d *DockerComposeProps) Equals(other *DockerComposeProps) bool

type DockerContainerManager added in v0.4.0 

type DockerContainerManager struct {
	client.ContainerAPIClient
}

func (*DockerContainerManager) CreateContainer added in v0.4.0 

func (cm *DockerContainerManager) CreateContainer(ctx context.Context, image string, projectPath string, config Config) (string, error)

func (*DockerContainerManager) Exec added in v0.4.0 

func (cm *DockerContainerManager) Exec(ctx context.Context, containerId string, command []string) (ExecResult, error)

func (*DockerContainerManager) StartContainer added in v0.4.0 

func (cm *DockerContainerManager) StartContainer(ctx context.Context, containerId string) error

func (*DockerContainerManager) StopContainer added in v0.4.0 

func (cm *DockerContainerManager) StopContainer(ctx context.Context, containerId string) error

type DockerHubRegistryCredentials added in v0.4.0 

type DockerHubRegistryCredentials struct {
	// contains filtered or unexported fields
}

func (*DockerHubRegistryCredentials) GetCredentials added in v0.4.0 

func (c *DockerHubRegistryCredentials) GetCredentials() (string, error)

Encodes the credentials as a base64 encoded JSON string

type DockerImageManager added in v0.4.0 

type DockerImageManager struct {
	client.ImageAPIClient
	// contains filtered or unexported fields
}

func (*DockerImageManager) BuildImage added in v0.4.0 

func (im *DockerImageManager) BuildImage(ctx context.Context, workingDir string, config Config) (string, error)

func (*DockerImageManager) PullImage added in v0.4.0 

func (im *DockerImageManager) PullImage(ctx context.Context, name string) error

type DockerImageProps 

type DockerImageProps struct {
	// Required when using an image.
	Image string `json:"image,omitempty"`

	// Dockerfile path. Duplicate of BuildProps.Dockerfile.
	Dockerfile string `json:"dockerfile,omitempty"`

	// Docker build context. Duplicate of BuildProps.Context.
	Context string `json:"context,omitempty"`

	// Docker build options
	Build *BuildProps `json:"build,omitempty"`

	// This property accepts a port or array of ports that should be published locally when the container is running. Unlike forwardPorts, your application may need to listen on all interfaces (0.0.0.0) not just localhost for it to be available externally. Defaults to [].
	AppPort AppPort `json:"appPort,omitempty"`

	// Requires workspaceFolder be set as well. Overrides the default local mount point for the workspace when the container is created. Supports the same values as the Docker CLI --mount flag.
	WorkspaceMount *Mount `json:"workspaceMount,omitempty"`

	// Requires workspaceMount be set. Sets the default path that devcontainer.json supporting services / tools should open when connecting to the container. Defaults to the automatic source code mount location.
	WorkspaceFolder string `json:"workspaceFolder,omitempty"`

	// An array of Docker CLI arguments that should be used when running the container. Defaults to [].
	// NOTE: this args are currently ignored because it's too cumbersome to manually parse them into the container.Config or container.HostConfig, there should be a better way to do it
	RunArgs []string `json:"runArgs,omitempty"`
}

func (*DockerImageProps) Equals 

func (d *DockerImageProps) Equals(other *DockerImageProps) bool

type DockerRunner 

type DockerRunner struct {
	// contains filtered or unexported fields
}

func (*DockerRunner) Exec 

func (r *DockerRunner) Exec(ctx context.Context, containerID string, command []string) (ExecResult, error)

func (*DockerRunner) Run 

func (r *DockerRunner) Run(ctx context.Context, projectPath string, config Config) (string, error)

func (*DockerRunner) Stop 

func (r *DockerRunner) Stop(ctx context.Context, containerId string) error

type ExecResult 

type ExecResult struct {
	StdOut   string
	StdErr   string
	ExitCode int
}

type Executor added in v0.4.0 

type Executor interface {
	Run(command []string, dir string, stdout, stderr io.Writer) error
}

func NewExecutorImpl added in v0.4.0 

func NewExecutorImpl() Executor

type ExecutorImpl added in v0.4.0 

type ExecutorImpl struct {
}

func (*ExecutorImpl) Run added in v0.4.0 

func (e *ExecutorImpl) Run(command []string, dir string, stdout, stderr io.Writer) error

type File 

type File struct {
	Path    string
	Content []byte
}

func FindConfig 

func FindConfig(fileSystem fs.FS) (File, error)

func (*File) Equals 

func (f *File) Equals(other *File) bool

type GeneralProperties 

type GeneralProperties struct {
	// A name for the dev container.
	Name string `json:"name,omitempty"`

	// An array of port numbers or "host:port" values (e.g. [3000, "db:5432"]) that should always be forwarded from inside the primary container to the local machine (including on the web). Defaults to [].
	// TODO: how to use this?
	ForwardPorts []string `json:"forwardPorts,omitempty"`

	// Object that maps a port number, "host:port" value, range, or regular expression to a set of default options.
	PortsAttributes map[string]PortAttributes `json:"portsAttributes,omitempty"`

	// Default options for ports, port ranges, and hosts that aren’t configured using portsAttributes.
	OtherPortsAttributes PortAttributes `json:"otherPortsAttributes,omitempty"`

	// A set of name-value pairs that sets or overrides environment variables for the container. Sets the variable on the Docker container itself, so all processes spawned in the container will have access to it.
	ContainerEnv map[string]string `json:"containerEnv,omitempty"`

	// A set of name-value pairs that sets or overrides environment variables for the devcontainer.json supporting service / tool (or sub-processes like terminals) but not the container as a whole.
	// TODO: how to use it?
	RemoteEnv map[string]string `json:"remoteEnv,omitempty"`

	// Overrides the user that Hide uses to run processes inside the container. Defaults to the user the container as a whole is running as (often root).
	// TODO: use when running commands?
	RemoteUser string `json:"remoteUser,omitempty"`

	// Overrides the user for all operations run as inside the container. Defaults to either root or the last USER instruction in the related Dockerfile used to create the image.
	ContainerUser string `json:"containerUser,omitempty"`

	// On Linux, if containerUser or remoteUser is specified, the user’s UID/GID will be updated to match the local user’s UID/GID to avoid permission problems with bind mounts. Defaults to true.
	// TODO: how to use it?
	UpdateRemoteUserUID bool `json:"updateRemoteUserUID,omitempty"`

	// Indicates the type of shell to use to “probe” for user environment variables: "none", "interactiveShell", "loginShell", or "loginInteractiveShell" (default)
	// NOTE: most likely we don't need this
	UserEnvProbe string `json:"userEnvProbe,omitempty"`

	// Tells devcontainer.json supporting services / tools whether they should run /bin/sh -c "while sleep 1000; do :; done" when starting the container instead of the container’s default command (since the container can shut down if the default command fails). Set to false if the default command must run for the container to function properly. Defaults to true for when using an image or Dockerfile and false when referencing a Docker Compose file.
	// TODO: how to use it?
	OverrideCommand bool `json:"overrideCommand,omitempty"`

	// Indicates whether devcontainer.json supporting tools should stop the containers when the related tool window is closed / shut down. Values are none, stopContainer (default for image or Dockerfile), and stopCompose (default for Docker Compose).
	// TODO: how to use it?
	ShutdownAction string `json:"shutdownAction,omitempty"`

	// Defaults to false. Cross-orchestrator way to indicate whether the tini init process should be used to help deal with zombie processes.
	Init bool `json:"init,omitempty"`

	// Defaults to false. Cross-orchestrator way to cause the container to run in privileged mode (--privileged). Required for things like Docker-in-Docker, but has security implications particularly when running directly on Linux.
	Privileged bool `json:"privileged,omitempty"`

	// Defaults to []. Cross-orchestrator way to add capabilities typically disabled for a container.
	CapAdd []string `json:"capAdd,omitempty"`

	// Defaults to []. Cross-orchestrator way to set container security options.
	SecurityOpt []string `json:"securityOpt,omitempty"`

	// Defaults to unset. Cross-orchestrator way to add additional mounts to a container.
	Mounts []Mount `json:"mounts,omitempty"`

	// By default, Features will attempt to automatically set the order they are installed based on a installsAfter property within each of them. This property allows you to override the Feature install order when needed.
	OverrideFeatureInstallOrder []string `json:"overrideFeatureInstallOrder,omitempty"`

	// Product specific properties, defined in supporting tools like Hide.
	Customizations Customizations `json:"customizations,omitempty"`
}

func (*GeneralProperties) Equals 

func (g *GeneralProperties) Equals(other *GeneralProperties) bool

type HideCustomization 

type HideCustomization struct {
	Tasks []Task `json:"tasks,omitempty"`
}

func (*HideCustomization) Equals 

func (h *HideCustomization) Equals(other *HideCustomization) bool

type HostRequirements 

type HostRequirements struct {
	Cpus    int    `json:"cpus,omitempty"`
	Memory  string `json:"memory,omitempty"`
	Storage string `json:"storage,omitempty"`
}

Can be useful when provisioning cloud resources

func (*HostRequirements) Equals 

func (h *HostRequirements) Equals(other *HostRequirements) bool

type ImageDevContainer added in v0.4.0 

type ImageDevContainer struct {
	DockerImageProps
	LifecycleProps
	GeneralProperties
}

type ImageManager added in v0.4.0 

type ImageManager interface {
	PullImage(ctx context.Context, name string) error
	BuildImage(ctx context.Context, workingDir string, config Config) (string, error)
}

func NewImageManager added in v0.4.0 

func NewImageManager(dockerImageCli client.ImageAPIClient, randomString func(int) string, credentials RegistryCredentials) ImageManager

type LifecycleCommand 

type LifecycleCommand map[string][]string

func (*LifecycleCommand) Equals 

func (c *LifecycleCommand) Equals(other *LifecycleCommand) bool

func (*LifecycleCommand) UnmarshalJSON 

func (c *LifecycleCommand) UnmarshalJSON(data []byte) error

type LifecycleProps 

type LifecycleProps struct {
	// A command string or list of command arguments to run on the host machine during initialization, including during container creation and on subsequent starts. The command may run more than once during a given session.
	InitializeCommand LifecycleCommand `json:"initializeCommand,omitempty"`

	// This command is the first of three (along with updateContentCommand and postCreateCommand) that finalizes container setup when a dev container is created. It and subsequent commands execute inside the container immediately after it has started for the first time.
	OnCreateCommand LifecycleCommand `json:"onCreateCommand,omitempty"`

	// This command is the second of three that finalizes container setup when a dev container is created. It executes inside the container after onCreateCommand whenever new content is available in the source tree during the creation process.
	UpdateContentCommand LifecycleCommand `json:"updateContentCommand,omitempty"`

	// This command is the last of three that finalizes container setup when a dev container is created. It happens after updateContentCommand and once the dev container has been assigned to a user for the first time.
	PostCreateCommand LifecycleCommand `json:"postCreateCommand,omitempty"`

	// A command to run each time the container is successfully started.
	// TODO: should we run it inside of container?
	PostStartCommand LifecycleCommand `json:"postStartCommand,omitempty"`

	// A command to run each time a tool has successfully attached to the container.
	// TODO: should we run it inside of container?
	PostAttachCommand LifecycleCommand `json:"postAttachCommand,omitempty"`

	// An enum that specifies the command any tool should wait for before connecting. Defaults to updateContentCommand.
	// TODO: use it
	WaitFor string `json:"waitFor,omitempty"`
}

func (*LifecycleProps) Equals 

func (l *LifecycleProps) Equals(other *LifecycleProps) bool

type Mount 

type Mount struct {
	//Can be bind, volume, or tmpfs
	Type string `json:"type,omitempty"`

	// May be specified as source or src
	Source string `json:"source,omitempty"`

	// May be specified as destination, dst, or target
	Destination string `json:"destination,omitempty"`
}

func (*Mount) UnmarshalJSON 

func (m *Mount) UnmarshalJSON(data []byte) error

type PortAttributes 

type PortAttributes struct {
	Label string `json:"label,omitempty"`

	// enum
	Protocol string `json:"protocol,omitempty"`

	// enum
	OnAutoForward    string `json:"onAutoForward,omitempty"`
	RequireLocalPort bool   `json:"requireLocalPort,omitempty"`
	ElevateIfNeeded  bool   `json:"elevateIfNeeded,omitempty"`
}

func (*PortAttributes) Equals 

func (p *PortAttributes) Equals(other *PortAttributes) bool

type RegistryCredentials added in v0.4.0 

type RegistryCredentials interface {
	GetCredentials() (string, error)
}

func NewDockerHubRegistryCredentials added in v0.4.0 

func NewDockerHubRegistryCredentials(username, password string) RegistryCredentials

type Runner 

type Runner interface {
	Run(ctx context.Context, projectPath string, config Config) (string, error)
	Stop(ctx context.Context, containerId string) error
	Exec(ctx context.Context, containerId string, command []string) (ExecResult, error)
}

func NewDockerRunner 

func NewDockerRunner(commandExecutor Executor, imageManager ImageManager, containerManager ContainerManager) Runner

type StringArray 

type StringArray []string

func (*StringArray) UnmarshalJSON 

func (c *StringArray) UnmarshalJSON(data []byte) error

type Task 

type Task struct {
	Alias   string `json:"alias"`
	Command string `json:"command"`
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.