dockerutil

package
v1.24.8 Latest Latest
Warning

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

 Go to latest Published: Sep 17, 2025 License: Apache-2.0 Imports: 49 Imported by: 0

Documentation

Index

Constants

View Source 
const NetName = "ddev_default"

NetName provides the default network name for ddev.

Variables

View Source 
var DockerRequirements = DockerVersionMatrix{
	APIVersion:               "1.44",
	Version:                  "25.0",
	ComposeVersionConstraint: ">= 2.24.3",
}

DockerRequirements defines the minimum Docker version required by DDEV. We compare using the APIVersion because it's a consistent and reliable value. The Version is displayed to users as it's more readable and user-friendly. The values correspond to the API version matrix found here: https://docs.docker.com/reference/api/engine/#api-version-matrix List of supported Docker versions: https://endoflife.date/docker-engine

ComposeVersionConstraint is in sync with https://docs.docker.com/desktop/release-notes/ 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 = container.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 CanRunWithoutDocker added in v1.23.5 

func CanRunWithoutDocker() bool

CanRunWithoutDocker returns true if the command or flag can run without Docker.

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(dockerVersionMatrix DockerVersionMatrix) error

CheckDockerVersion determines if the Docker version of the host system meets the provided minimum for the Docker API Version.

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(cmd *ComposeCmdOpts, stdin io.Reader, stdout io.Writer, stderr io.Writer) error

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

func ContainerName 

func ContainerName(container *container.Summary) 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 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 specified targetSubdir is removed and recreated

func CreateComposeProject added in v1.24.8 

func CreateComposeProject(yamlStr string) (*types.Project, error)

CreateComposeProject creates a compose project from a string

func CreateVolume added in v1.21.5 

func CreateVolume(volumeName string, driver string, driverOpts map[string]string, labels map[string]string) (volume.Volume, 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(name string, netOptions network.CreateOptions) 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) (*container.Summary, 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) (*container.Summary, 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) ([]container.Summary, 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) ([]container.Summary, error)

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

func FindImagesByLabels added in v1.23.5 

func FindImagesByLabels(labels map[string]string, danglingOnly bool) ([]image.Summary, error)

FindImagesByLabels takes a map of label names and values and returns any Docker images which match all labels. danglingOnly is used to return only dangling images, otherwise return all of them, including dangling.

func FindNetworksWithLabel added in v1.22.4 

func FindNetworksWithLabel(label string) ([]network.Inspect, 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) ([]container.Summary, error)

GetAppContainers retrieves docker containers for a given sitename.

func GetBoundHostPorts added in v1.24.3 

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

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

func GetContainerEnv 

func GetContainerEnv(key string, container container.Summary) string

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

func GetContainerHealth 

func GetContainerHealth(container *container.Summary) (string, string)

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

func GetContainerNames added in v1.23.4 

func GetContainerNames(containers []container.Summary, excludeContainerNames []string, removePrefix string) []string

GetContainerNames takes an array of Container and returns an array of strings with container names. Use removePrefix to get short container names.

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 API version of Docker provider engine See https://docs.docker.com/engine/api/#api-version-matrix

func GetDockerClient 

func GetDockerClient() (context.Context, client.APIClient, error)

GetDockerClient returns the Go context and the Docker API client

func GetDockerClientInfo added in v1.24.8 

func GetDockerClientInfo() (system.Info, error)

GetDockerClientInfo returns the Docker system information from the daemon

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) ([]container.Summary, error)

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

func GetDockerContextNameAndHost added in v1.24.8 

func GetDockerContextNameAndHost() (string, string, error)

GetDockerContextNameAndHost returns the Docker context name and host

func GetDockerHostSanitized added in v1.24.8 

func GetDockerHostSanitized() (string, error)

GetDockerHostSanitized returns Docker host but with all special characters removed It stands in for Docker context name, 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 it is a tcp:// URL)

func GetDockerVersion added in v1.21.5 

func GetDockerVersion() (string, error)

GetDockerVersion gets the cached version of Docker provider engine

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 address 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 container.Summary) 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) (container.InspectResponse, 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 cerrdefs.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.24.8 

func IsOrbStack() bool

IsOrbStack detects if running on OrbStack

func IsRancherDesktop added in v1.23.5 

func IsRancherDesktop() bool

IsRancherDesktop detects if running on Rancher Desktop

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(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(image string) error

Pull pulls image if it doesn't exist locally

func PullImages added in v1.24.8 

func PullImages(images []string, pullAlways bool) error

PullImages pulls images in parallel if they don't exist locally If pullAlways is true, it will always pull Otherwise, it will only pull if the image doesn't exist

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(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 ResetDockerHost added in v1.24.8 

func ResetDockerHost(host string) error

ResetDockerHost resets cached Docker host data in singleton (it's not thread-safe). Used for testing only.

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 *container.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 RunSimpleContainerExtended added in v1.24.8 

func RunSimpleContainerExtended(name string, config *container.Config, hostConfig *container.HostConfig, removeContainerAfterRun bool, detach bool) (containerID string, output string, returnErr error)

RunSimpleContainerExtended runs a container (non-daemonized) and captures the stdout/stderr. Accepts any config and hostConfig. If stdin is provided, enables interactive mode with stdin forwarding.

func TruncateID added in v1.24.7 

func TruncateID(id string) string

TruncateID returns a shorthand version of a string identifier for convenience. This is a copy from https://github.com/moby/moby/blob/master/client/pkg/stringid/stringid.go

func ValidatePort added in v1.24.0 

func ValidatePort(port interface{}) error

ValidatePort checks that the given port is valid (in range 1-65535)

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
	ComposeYaml  *types.Project
	Profiles     []string
	Action       []string
	Progress     bool // Add dots every second while the compose command is running
	Timeout      time.Duration
	ProjectName  string // Optional project name to set via -p flag
}

type DockerVersionMatrix added in v1.24.3 

type DockerVersionMatrix struct {
	APIVersion               string
	Version                  string
	ComposeVersionConstraint string
}

type HostDockerInternal added in v1.24.8 

type HostDockerInternal struct {
	IPAddress string // IP address that containers should use to reach the host
	ExtraHost string // Value to use in docker-compose extra_hosts for host.docker.internal
	Message   string // Debug message explaining the configuration choice
}

HostDockerInternal contains host.docker.internal configuration

func GetHostDockerInternal added in v1.24.8 

func GetHostDockerInternal() *HostDockerInternal

GetHostDockerInternal determines the correct host.docker.internal configuration for containers. Returns HostDockerInternal containing IP, extra_hosts value, and debug message.

The function handles platform-specific cases: - Docker Desktop: Uses built-in host.docker.internal - Linux: Uses host-gateway - WSL2 scenarios: Detects Windows host IP via routing table - Colima: Uses fixed IP 192.168.5.2 - IDE location overrides: Respects global xdebug_ide_location settings

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.