Documentation
¶
Overview ¶
Package docker executes commands and transfers files inside a running container. It implements invoke.Environment, verified against the invoketest contract suite.
The daemon is found the way the docker command finds it: an endpoint passed to WithHost, then DOCKER_HOST, then the endpoint recorded by the current context — which is where installations that do not use the conventional socket, such as Colima and Rancher Desktop, put theirs.
Commands are delivered to the daemon as a real argument vector, so nothing is reinterpreted by a shell, and environment variables travel over the API rather than on a command line. Signal delivery needs a shell in the container to record the in-container process id; a container without one reports the capability as unavailable rather than accepting signals and dropping them.
Index ¶
- type Config
- type Environment
- func (e *Environment) Capabilities() invoke.Capabilities
- func (e *Environment) Close() error
- func (e *Environment) Download(ctx context.Context, remotePath, localPath string, ...) error
- func (e *Environment) LookPath(ctx context.Context, name string) (string, error)
- func (e *Environment) OS() invoke.TargetOS
- func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
- func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, ...) error
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Container is the container name or ID to execute in. Required.
Container string
// User is the user commands run as, in the same form docker accepts
// ("root", "1000", "1000:1000"). Empty means the container's own
// default.
User string
// Privileged runs commands with elevated privileges.
Privileged bool
// Host is the daemon endpoint. Empty means the endpoint the local
// docker installation is configured to use: DOCKER_HOST when set,
// otherwise the current context's.
Host string
// Context names a docker context to take the endpoint from,
// overriding whichever one is current.
Context string
// Timeout bounds daemon calls that must not block indefinitely;
// zero means 30s.
Timeout time.Duration
}
Config holds the settings for executing in a container. Callers normally build it with New and the With options rather than by hand; NewFromConfig accepts one directly.
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
Environment is a connection to a running container.
func New ¶
New connects to the daemon and returns an Environment for the named container, which must already be running.
ctx bounds establishing the connection only — which is several round trips to the daemon, not one. It does not govern the Environment afterwards, which lives until Close.
func NewFromConfig ¶
func NewFromConfig(ctx context.Context, cfg *Config) (*Environment, error)
NewFromConfig connects using a Config assembled directly. ctx bounds establishing the connection, as in New.
func (*Environment) Capabilities ¶
func (e *Environment) Capabilities() invoke.Capabilities
Capabilities reports the container's optional features.
Signal delivery requires a shell to record the in-container process id; without one the capability is not declared, so signal requests fail rather than being silently dropped.
Terminal allocation is available: the daemon's exec API takes a terminal flag and an initial size.
func (*Environment) Close ¶
func (e *Environment) Close() error
Close releases the daemon connection, terminating commands still running.
func (*Environment) Download ¶
func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.TransferOption) error
Download copies a path out of the container to the local filesystem, with the same staging guarantee as Upload.
func (*Environment) OS ¶
func (e *Environment) OS() invoke.TargetOS
OS reports the container's operating system, detected once at connect time.
func (*Environment) Start ¶
func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
Start runs cmd in the container and returns a handle to it.
func (*Environment) Upload ¶
func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.TransferOption) error
Upload copies a local file or directory tree into the container.
The archive is unpacked into a staging directory and moved into place only once it has arrived whole, so a transfer that fails or is canceled part-way leaves an existing destination exactly as it was. The daemon's own unpacking offers no such guarantee: it writes as the bytes arrive.
type Option ¶
type Option func(*Config)
Option configures a Config.
func WithContext ¶ added in v0.3.0
WithContext takes the daemon endpoint from the named docker context, rather than from whichever one the installation currently selects.
Naming a context that cannot be read fails, rather than falling back to the default endpoint: the fallback is a different daemon, and commands would run somewhere the caller did not choose.
func WithPrivileged ¶
func WithPrivileged() Option
WithPrivileged runs commands with elevated privileges.
func WithTimeout ¶
WithTimeout bounds daemon calls that must not block indefinitely.
Source Files