dockerutil

package
v1.23.0 Latest Latest
Warning

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

 Go to latest Published: Apr 17, 2024 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Index

Constants

View Source 
const NetName = "ddev_default"

NetName provides the default network name for ddev.

Variables

View Source 
var DockerAPIVersion = ""

DockerAPIVersion is cached API version of Docker provider engine See https://docs.docker.com/engine/api/#api-version-matrix

View Source 
var DockerClient *dockerClient.Client
View Source 
var DockerComposeVersionConstraint = ">= 2.5.1"

DockerComposeVersionConstraint is the versions allowed for ddev REMEMBER TO CHANGE docs/ddev-installation.md if you touch this! The constraint MUST HAVE a -pre of some kind on it for successful comparison. See https://github.com/ddev/ddev/pull/738 and regression https://github.com/ddev/ddev/issues/1431

View Source 
var DockerContext string
View Source 
var DockerCtx context.Context
View Source 
var DockerHost string
View Source 
var DockerIP string
View Source 
var DockerVersion = ""

DockerVersion is cached version of Docker provider engine

View Source 
var DockerVersionConstraint = ">= 20.10.0-alpha1"

DockerVersionConstraint is the current minimum version of Docker required for DDEV. See https://godoc.org/github.com/Masterminds/semver#hdr-Checking_Version_Constraints for examples defining version constraints. REMEMBER TO CHANGE docs/ddev-installation.md if you touch this! The constraint MUST HAVE a -pre of some kind on it for successful comparison. See https://github.com/ddev/ddev/pull/738 and regression https://github.com/ddev/ddev/issues/1431

View Source 
var NoHealthCheck = dockerContainer.HealthConfig{
	Test: []string{"NONE"},
}

NoHealthCheck is a HealthConfig that disables any existing healthcheck when running a container. Used by RunSimpleContainer See https://pkg.go.dev/github.com/moby/docker-image-spec/specs-go/v1#HealthcheckConfig

Functions

func CheckAvailableSpace added in v1.21.5 

func CheckAvailableSpace()

CheckAvailableSpace outputs a warning if Docker space is low

func CheckDockerCompose added in v0.11.0 

func CheckDockerCompose() error

CheckDockerCompose determines if docker-compose is present and executable on the host system. This relies on docker-compose being somewhere in the user's $PATH.

func CheckDockerVersion 

func CheckDockerVersion(versionConstraint string) error

CheckDockerVersion determines if the Docker version of the host system meets the provided version constraints. See https://godoc.org/github.com/Masterminds/semver#hdr-Checking_Version_Constraints for examples defining version constraints.

func CheckForHTTPS added in v0.9.4 

func CheckForHTTPS(container dockerTypes.Container) bool

CheckForHTTPS determines if a container has the HTTPS_EXPOSE var set to route 443 traffic to 80

func ComposeCmd 

func ComposeCmd(cmd *ComposeCmdOpts) (string, string, error)

ComposeCmd executes docker-compose commands via shell. returns stdout, stderr, error/nil

func ComposeWithStreams added in v1.4.0 

func ComposeWithStreams(composeFiles []string, stdin io.Reader, stdout io.Writer, stderr io.Writer, action ...string) error

ComposeWithStreams executes a docker-compose command but allows the caller to specify stdin/stdout/stderr

func ContainerName 

func ContainerName(container dockerTypes.Container) string

ContainerName returns the container's human-readable name.

func ContainerWait 

func ContainerWait(waittime int, labels map[string]string) (string, error)

ContainerWait provides a wait loop to check for a single container in "healthy" status. waittime is in seconds. This is modeled on https://gist.github.com/ngauthier/d6e6f80ce977bedca601 Returns logoutput, error, returns error if not "healthy"

func ContainerWaitLog added in v1.21.5 

func ContainerWaitLog(waittime int, labels map[string]string, expectedLog string) (string, error)

ContainerWaitLog provides a wait loop to check for container in "healthy" status. with a given log output timeout is in seconds. This is modeled on https://gist.github.com/ngauthier/d6e6f80ce977bedca601 Returns logoutput, error, returns error if not "healthy"

func ContainersWait added in v1.21.5 

func ContainersWait(waittime int, labels map[string]string) error

ContainersWait provides a wait loop to check for multiple containers in "healthy" status. waittime is in seconds. Returns logoutput, error, returns error if not "healthy"

func CopyFromContainer added in v1.21.5 

func CopyFromContainer(containerName string, containerPath string, hostPath string) error

CopyFromContainer copies a path from a specified container and location to a dstPath on host

func CopyIntoContainer added in v1.21.5 

func CopyIntoContainer(srcPath string, containerName string, dstPath string, exclusion string) error

CopyIntoContainer copies a path (file or directory) into a specified container and location

func CopyIntoVolume added in v1.21.5 

func CopyIntoVolume(sourcePath string, volumeName string, targetSubdir string, uid string, exclusion string, destroyExisting bool) error

CopyIntoVolume copies a file or directory on the host into a Docker volume sourcePath is the host-side full path volumeName is the volume name to copy to targetSubdir is where to copy it to on the volume uid is the uid of the resulting files exclusion is a path to be excluded If destroyExisting the volume is removed and recreated

func CreateVolume added in v1.21.5 

func CreateVolume(volumeName string, driver string, driverOpts map[string]string, labels map[string]string) (vol dockerVolume.Volume, err error)

CreateVolume creates a Docker volume

func DownloadDockerCompose added in v1.21.5 

func DownloadDockerCompose() error

DownloadDockerCompose gets the docker-compose binary and puts it into ~/.ddev/.bin

func DownloadDockerComposeIfNeeded added in v1.21.5 

func DownloadDockerComposeIfNeeded() (bool, error)

DownloadDockerComposeIfNeeded downloads the proper version of docker-compose if it's either not yet installed or has the wrong version. Returns downloaded bool (true if it did the download) and err

func EnsureDdevNetwork added in v0.9.4 

func EnsureDdevNetwork()

EnsureDdevNetwork creates or ensures the DDEV network exists or exits with fatal.

func EnsureNetwork 

func EnsureNetwork(ctx context.Context, client *dockerClient.Client, name string, netOptions dockerTypes.NetworkCreate) error

EnsureNetwork will ensure the Docker network for DDEV is created.

func Exec added in v1.21.5 

func Exec(containerID string, command string, uid string) (string, string, error)

Exec does a simple docker exec, no frills, it executes the command with the specified uid (or defaults to root=0 if empty uid) Returns stdout, stderr, error

func FindContainerByLabels 

func FindContainerByLabels(labels map[string]string) (*dockerTypes.Container, error)

FindContainerByLabels takes a map of label names and values and returns any Docker containers which match all labels.

func FindContainerByName added in v1.21.5 

func FindContainerByName(name string) (*dockerTypes.Container, error)

FindContainerByName takes a container name and returns the container If container is not found, returns nil with no error

func FindContainersByLabels 

func FindContainersByLabels(labels map[string]string) ([]dockerTypes.Container, error)

FindContainersByLabels takes a map of label names and values and returns any Docker containers which match all labels. Explanation of the query: * docs: https://docs.docker.com/engine/api/v1.23/ * Stack Overflow: https://stackoverflow.com/questions/28054203/docker-remote-api-filter-exited

func FindContainersWithLabel added in v1.21.5 

func FindContainersWithLabel(label string) ([]dockerTypes.Container, error)

FindContainersWithLabel returns all containers with the given label It ignores the value of the label, is only interested that the label exists.

func FindNetworksWithLabel added in v1.22.4 

func FindNetworksWithLabel(label string) ([]dockerTypes.NetworkResource, error)

FindNetworksWithLabel returns all networks with the given label It ignores the value of the label, is only interested that the label exists.

func GetAppContainers 

func GetAppContainers(sitename string) ([]dockerTypes.Container, error)

GetAppContainers retrieves docker containers for a given sitename.

func GetContainerEnv 

func GetContainerEnv(key string, container dockerTypes.Container) string

GetContainerEnv returns the value of a given environment variable from a given container.

func GetContainerHealth 

func GetContainerHealth(container *dockerTypes.Container) (string, string)

GetContainerHealth retrieves the health status of a given container. returns status, most-recent-log

func GetContainerStateByName added in v1.21.5 

func GetContainerStateByName(name string) (string, error)

GetContainerStateByName returns container state for the named container

func GetDockerAPIVersion added in v1.22.7 

func GetDockerAPIVersion() (string, error)

GetDockerAPIVersion gets the cached or API-sourced API version of Docker provider engine

func GetDockerClient 

func GetDockerClient() (context.Context, *dockerClient.Client)

GetDockerClient returns a Docker client respecting the current Docker context but DOCKER_HOST gets priority

func GetDockerComposeVersion added in v1.21.5 

func GetDockerComposeVersion() (string, error)

GetDockerComposeVersion runs docker-compose -v to get the current version

func GetDockerContainers 

func GetDockerContainers(allContainers bool) ([]dockerTypes.Container, error)

GetDockerContainers returns a slice of all Docker containers on the host system.

func GetDockerContext added in v1.21.5 

func GetDockerContext() (string, string, error)

GetDockerContext returns the currently set Docker context, host, and error

func GetDockerHostID added in v1.21.5 

func GetDockerHostID() string

GetDockerHostID returns DOCKER_HOST but with all special characters removed It stands in for Docker context, but Docker context name is not a reliable indicator

func GetDockerIP added in v0.19.0 

func GetDockerIP() (string, error)

GetDockerIP returns either the default Docker IP address (127.0.0.1) or the value as configured by $DOCKER_HOST (if DOCKER_HOST is an tcp:// URL)

func GetDockerVersion added in v1.21.5 

func GetDockerVersion() (string, error)

GetDockerVersion gets the cached or API-sourced version of Docker provider engine

func GetExposedContainerPorts added in v1.21.5 

func GetExposedContainerPorts(containerID string) ([]string, error)

GetExposedContainerPorts takes a container pointer and returns an array of exposed ports (and error)

func GetHostDockerInternalIP added in v1.21.5 

func GetHostDockerInternalIP() (string, error)

GetHostDockerInternalIP returns either "" (will use the hostname as is) (for Docker Desktop on macOS and Windows with WSL2) or a usable IP address But there are many cases to handle Linux classic installation Gitpod (the Linux technique does not work during prebuild) WSL2 with Docker-ce installed inside WSL2 with PhpStorm or vscode running inside WSL2 And it matters whether they're running IDE inside. With docker-inside-wsl2, the bridge docker0 is what we want It's also possible to run vscode Language Server inside the web container, in which case host.docker.internal should actually be 127.0.0.1 Inside WSL2, the way to access an app like PhpStorm running on the Windows side is described in https://learn.microsoft.com/en-us/windows/wsl/networking#accessing-windows-networking-apps-from-linux-host-ip and it involves parsing /etc/resolv.conf.

func GetLiveDockerComposeVersion added in v1.21.5 

func GetLiveDockerComposeVersion() (string, error)

GetLiveDockerComposeVersion runs `docker-compose --version` and caches result

func GetNFSServerAddr added in v1.21.5 

func GetNFSServerAddr() (string, error)

GetNFSServerAddr gets the addrss that can be used for the NFS server. It's almost the same as GetDockerHostInternalIP() but we have to get the actual addr in the case of Linux; still, Linux rarely is used with NFS. Returns "host.docker.internal" by default (not empty)

func GetPublishedPort 

func GetPublishedPort(privatePort uint16, container dockerTypes.Container) int

GetPublishedPort returns the published port for a given private port.

func ImageExistsLocally added in v1.2.0 

func ImageExistsLocally(imageName string) (bool, error)

ImageExistsLocally determines if an image is available locally.

func InspectContainer added in v1.21.5 

func InspectContainer(name string) (dockerTypes.ContainerJSON, error)

InspectContainer returns the full result of inspection

func IsColima added in v1.21.5 

func IsColima() bool

IsColima detects if running on Colima

func IsDockerDesktop added in v1.21.5 

func IsDockerDesktop() bool

IsDockerDesktop detects if running on Docker Desktop

func IsErrNotFound added in v1.23.0 

func IsErrNotFound(err error) bool

IsErrNotFound returns true if the error is a NotFound error, which is returned by the API when some object is not found. It is an alias for errdefs.IsNotFound. Used as a wrapper to avoid direct import for docker client.

func IsLima added in v1.23.0 

func IsLima() bool

IsLima detects if running on lima

func IsOrbstack added in v1.23.0 

func IsOrbstack() bool

IsOrbstack detects if running on Orbstack

func MassageWindowsHostMountpoint added in v1.4.0 

func MassageWindowsHostMountpoint(mountPoint string) string

MassageWindowsHostMountpoint changes C:/path/to/something to //c/path/to/something This is required for Docker bind mounts on Docker toolbox. Sadly, if we have a Windows drive name, it has to be converted from C:/ to //c for Win10Home/Docker toolbox

func MassageWindowsNFSMount added in v1.21.5 

func MassageWindowsNFSMount(mountPoint string) string

MassageWindowsNFSMount changes C:\Path\to\something to /c/Path/to/something

func NetExists 

func NetExists(ctx context.Context, client *dockerClient.Client, name string) bool

NetExists checks to see if the Docker network for DDEV exists.

func NetworkExists added in v1.21.5 

func NetworkExists(netName string) bool

NetworkExists returns true if the named network exists Mostly intended for tests

func Pull added in v1.21.5 

func Pull(imageName string) error

Pull pulls image if it doesn't exist locally.

func RemoveContainer added in v1.4.0 

func RemoveContainer(id string) error

RemoveContainer stops and removes a container

func RemoveContainersByLabels added in v1.21.5 

func RemoveContainersByLabels(labels map[string]string) error

RemoveContainersByLabels removes all containers that match a set of labels

func RemoveImage added in v1.21.5 

func RemoveImage(tag string) error

RemoveImage removes an image with force

func RemoveNetwork added in v1.21.5 

func RemoveNetwork(netName string) error

RemoveNetwork removes the named Docker network netName can also be network's ID

func RemoveNetworkDuplicates added in v1.22.5 

func RemoveNetworkDuplicates(ctx context.Context, client *dockerClient.Client, netName string)

RemoveNetworkDuplicates removes the duplicates for the named Docker network This means that if there is only one network with this name - no action, and if there are several such networks, then we leave the first one, and delete the others

func RemoveNetworkWithWarningOnError added in v1.22.4 

func RemoveNetworkWithWarningOnError(netName string)

RemoveNetworkWithWarningOnError removes the named Docker network

func RemoveVolume added in v1.21.5 

func RemoveVolume(volumeName string) error

RemoveVolume removes named volume. Does not throw error if the volume did not exist.

func RestartContainer added in v1.21.5 

func RestartContainer(id string, timeout *int) error

RestartContainer stops and removes a container

func RunSimpleContainer added in v1.1.0 

func RunSimpleContainer(image string, name string, cmd []string, entrypoint []string, env []string, binds []string, uid string, removeContainerAfterRun bool, detach bool, labels map[string]string, portBindings nat.PortMap, healthConfig *dockerContainer.HealthConfig) (containerID string, output string, returnErr error)

RunSimpleContainer runs a container (non-daemonized) and captures the stdout/stderr. It will block, so not to be run on a container whose entrypoint or cmd might hang or run too long. This should be the equivalent of something like docker run -t -u '%s:%s' -e SNAPSHOT_NAME='%s' -v '%s:/mnt/ddev_config' -v '%s:/var/lib/mysql' --no-healthcheck --rm --entrypoint=/migrate_file_to_volume.sh %s:%s" Example code from https://gist.github.com/fsouza/b0bf3043827f8e39c4589e88cec067d8 Default behavior is to use the image's healthcheck (healthConfig == nil) When passed a pointer to HealthConfig (often &dockerutils.NoHealthCheck) it can turn off healthcheck or it can replace it or have other behaviors, see https://pkg.go.dev/github.com/moby/docker-image-spec/specs-go/v1#HealthcheckConfig Returns containerID, output, error

func VolumeExists added in v1.21.5 

func VolumeExists(volumeName string) bool

VolumeExists checks to see if the named volume exists.

func VolumeLabels added in v1.21.5 

func VolumeLabels(volumeName string) (map[string]string, error)

VolumeLabels returns map of labels found on volume.

Types

type ComposeCmdOpts added in v1.22.4 

type ComposeCmdOpts struct {
	ComposeFiles []string
	Action       []string
	Progress     bool // Add dots every second while the compose command is running
}

Source Files

View all Source files

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.