Documentation
¶
Overview ¶
Package engine finds and operates the container engine (Docker Desktop, Docker Engine, or Podman) through the Engine API. It does not use the docker or podman command for the lifecycle of the container.
Index ¶
- Constants
- Variables
- func DataDir(c container.InspectResponse) string
- func DataVolume(instance string) string
- func FreeBytes(path string) (uint64, error)
- func HostPort(c container.InspectResponse) int
- func InstallHint(goos string) string
- func Labels(instance string) map[string]string
- func Overlap(a, b string) bool
- func Owned(c container.InspectResponse) error
- func SpoolVolume(instance string) string
- func Within(root, path string) bool
- type Candidate
- type Engine
- func (e *Engine) BindMounts(ctx context.Context) ([]Mount, error)
- func (e *Engine) Close() error
- func (e *Engine) Container(ctx context.Context, name string) (container.InspectResponse, bool, error)
- func (e *Engine) Create(ctx context.Context, s Spec) (string, error)
- func (e *Engine) Describe(ctx context.Context) string
- func (e *Engine) EnsureImage(ctx context.Context, ref string, noPull bool, log io.Writer) (id string, pulled bool, err error)
- func (e *Engine) EnsureVolumes(ctx context.Context, s Spec) (made []string, err error)
- func (e *Engine) Exec(ctx context.Context, id string, cmd []string, stdin io.Reader, ...) (int, error)
- func (e *Engine) Healthy(ctx context.Context, id string, out io.Writer) error
- func (e *Engine) LocalImage(ctx context.Context, ref string) (string, error)
- func (e *Engine) Logs(ctx context.Context, id string, follow bool, stdout, stderr io.Writer) error
- func (e *Engine) Pause(ctx context.Context, id string) error
- func (e *Engine) Pull(ctx context.Context, ref string, log io.Writer) error
- func (e *Engine) Remove(ctx context.Context, id string) error
- func (e *Engine) RemoveVolume(ctx context.Context, name string) error
- func (e *Engine) Resume(ctx context.Context, id string) error
- func (e *Engine) Start(ctx context.Context, id string) error
- func (e *Engine) Stop(ctx context.Context, id string) error
- func (e *Engine) WaitHealthy(ctx context.Context, id string, wait time.Duration) error
- type Env
- type Kind
- type Launcher
- type Mount
- type Spec
Constants ¶
const ( LabelManagedBy = "dev.mai.managed-by" ManagedByValue = "mai-cli" LabelInstance = "dev.mai.instance" )
Labels of each object that the CLI makes.
const ContainerPort = 8080
ContainerPort is the HTTP port of the server in the container.
const StartWait = 120 * time.Second
StartWait is the maximum time to wait for the engine or for the health of the container.
const StopTimeout = 60
StopTimeout is the time in seconds that a stop waits before a kill.
Variables ¶
var Capabilities = []string{"CHOWN", "DAC_OVERRIDE", "FOWNER", "SETGID", "SETUID", "KILL"}
Capabilities that the container adds after it drops all.
var ErrForeign = errors.New("engine: a container that the CLI did not make holds the name")
ErrForeign means that a container with the instance name exists without the label of the CLI.
var ErrNoResponse = errors.New("engine: the container engine gives no response")
ErrNoResponse means that the engine did not answer in the wait time.
var ErrNotInstalled = errors.New("engine: no container engine is installed")
ErrNotInstalled means that no engine is installed on this computer.
var ErrPullRefused = errors.New("engine: the image is not local and the pull is off")
ErrPullRefused means that the image is not local and the caller refused a pull.
var TmpfsPaths = []string{"/run", "/tmp", "/etc/postfix", "/etc/dovecot", "/var/lib/postgresql"}
TmpfsPaths are the tmpfs folders of the container. /var/lib/postgresql stops the anonymous volume that the base image declares.
Functions ¶
func DataDir ¶ added in v3.2.0
func DataDir(c container.InspectResponse) string
DataDir gives the host folder of the bind mount at /data of the container. It gives "" when /data is a volume, or when the container has no mount at /data.
func DataVolume ¶
DataVolume is the name of the data volume of an instance.
func HostPort ¶ added in v3.2.0
func HostPort(c container.InspectResponse) int
HostPort gives the host port of the HTTP port of the container, or 0 when the container has no binding of that port.
func InstallHint ¶
InstallHint is the one install step for the OS when no engine is installed.
func Overlap ¶ added in v3.2.0
Overlap tells if the folders a and b are the same folder, or if one of them holds the other.
func Owned ¶
func Owned(c container.InspectResponse) error
Owned returns ErrForeign when the container has no label of the CLI.
func SpoolVolume ¶
SpoolVolume is the name of the spool volume of an instance.
Types ¶
type Candidate ¶
type Candidate struct {
Host string // address for the Engine API, for example unix:///var/run/docker.sock
Source string // where the address came from
Kind Kind
}
Candidate is one engine address to try.
func Discover ¶
Discover returns the engine addresses to try, in sequence: DOCKER_HOST, the current Docker context, the default sockets of Docker Desktop and Docker Engine, then the default sockets of Podman. A socket file that does not exist is not in the list, but the default address of the OS is always in the list, so that the caller can start the engine.
type Engine ¶
Engine is a connection to one container engine.
func Connect ¶
Connect finds the engine. If no engine answers, it starts the first installed engine and waits up to StartWait. If no engine is installed, it returns ErrNotInstalled.
func ConnectSystem ¶
ConnectSystem is Connect with the environment of this process.
func (*Engine) BindMounts ¶ added in v3.2.0
BindMounts gives each bind mount of each container that has the label of an instance. The list of the containers can give a different path for the host folder, for example /host_mnt/private/tmp/x on Docker Desktop. Thus the inspect of each container gives the path.
func (*Engine) Container ¶
func (e *Engine) Container(ctx context.Context, name string) (container.InspectResponse, bool, error)
Find the container with the exact name. ok is false when no such container exists.
func (*Engine) EnsureImage ¶
func (e *Engine) EnsureImage(ctx context.Context, ref string, noPull bool, log io.Writer) (id string, pulled bool, err error)
EnsureImage makes sure that the image is local. It pulls the image with no registry credential when it is not local. pulled is true when this call pulled the image.
func (*Engine) EnsureVolumes ¶
EnsureVolumes makes each volume of the spec with the labels of the CLI. made is the list of volumes that this call made.
func (*Engine) Exec ¶
func (e *Engine) Exec(ctx context.Context, id string, cmd []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
Exec runs cmd in the container and returns its exit code. stdin can be nil.
func (*Engine) LocalImage ¶
LocalImage returns the ID of a local image with the reference, or "" when it is not local.
func (*Engine) Pull ¶
Pull gets the image through the Engine API with no registry credential, and writes the progress to log.
func (*Engine) RemoveVolume ¶
RemoveVolume removes one volume.
type Env ¶
type Env struct {
GOOS string
Home string
Getenv func(string) string
ReadFile func(string) ([]byte, error)
Exists func(string) bool
}
Env is the environment that discovery reads. Tests give a fake one.
type Mount ¶ added in v3.2.0
type Mount struct {
Instance string // The instance of the container.
Container string // The name of the container.
Source string // The host folder.
Target string // The folder in the container.
}
Mount is a bind mount of a container that has the label of an instance.
func HostMounts ¶ added in v3.2.0
func HostMounts(c container.InspectResponse) []Mount
HostMounts gives each bind mount of the container, when the container has the label of an instance.
type Spec ¶
type Spec struct {
Instance string
Port int
Image string
DataDir string // a host folder for /data; empty means the volume <instance>3-data
}
Spec is the input of the container definition.
func (Spec) CreateOptions ¶
func (s Spec) CreateOptions() client.ContainerCreateOptions
CreateOptions returns the container definition of the contract.