core

Documentation

Index

• Constants
• Variables
• func DefaultGatewayIP() (string, error)
• func DefaultLabels(sessionID string) map[string]string
• func ExtractDockerHost(ctx context.Context) string
• func ExtractDockerSocket(ctx context.Context) string
• func ExtractImagesFromDockerfile(dockerfile string, buildArgs map[string]*string) ([]string, error)
• func ExtractImagesFromReader(r io.Reader, buildArgs map[string]*string) ([]string, error)
• func ExtractRegistry(image string, fallback string) string
• func InAContainer() bool
• func IsURL(str string) bool
• func IsWindows() bool
• func NewClient(ctx context.Context, ops ...client.Opt) (*client.Client, error)
• func ProcessID() string
• func ProjectPath() string
• func SessionID() string

Constants

const (
	IndexDockerIO = "https://index.docker.io/v1/"

	URLSchema    = `((ftp|tcp|udp|wss?|https?):\/\/)`
	URLUsername  = `(\S+(:\S*)?@)`
	URLIP        = `([1-9]\d?|1\d\d|2[01]\d|22[0-3]|24\d|25[0-5])(\.(\d{1,2}|1\d\d|2[0-4]\d|25[0-5])){2}(?:\.([0-9]\d?|1\d\d|2[0-4]\d|25[0-5]))`
	IP           = `` /* 659-byte string literal not displayed */
	URLSubdomain = `((www\.)|([a-zA-Z0-9]+([-_\.]?[a-zA-Z0-9])*[a-zA-Z0-9]\.[a-zA-Z0-9]+))`
	URLPath      = `((\/|\?|#)[^\s]*)`
	URLPort      = `(:(\d{1,5}))`
	URL          = `^` + URLSchema + `?` + URLUsername + `?` + `((` + URLIP + `|(\[` + IP + `\])|(([a-zA-Z0-9]([a-zA-Z0-9-_]+)?[a-zA-Z0-9]([-\.][a-zA-Z0-9]+)*)|(` + URLSubdomain + `?))?(([a-zA-Z\x{00a1}-\x{ffff}0-9]+-?-?)*[a-zA-Z\x{00a1}-\x{ffff}0-9]+)(?:\.([a-zA-Z\x{00a1}-\x{ffff}]{1,}))?))\.?` + URLPort + `?` + URLPath + `?$`
)

const (
	LabelBase      = "org.testcontainers"
	LabelLang      = LabelBase + ".lang"
	LabelReaper    = LabelBase + ".reaper"
	LabelRyuk      = LabelBase + ".ryuk"
	LabelSessionID = LabelBase + ".sessionId"
	LabelVersion   = LabelBase + ".version"
)

Variables

var (
	ErrDockerHostNotSet               = errors.New("DOCKER_HOST is not set")
	ErrDockerSocketOverrideNotSet     = errors.New("TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE is not set")
	ErrDockerSocketNotSetInContext    = errors.New("socket not set in context")
	ErrDockerSocketNotSetInProperties = errors.New("socket not set in ~/.testcontainers.properties")
	ErrNoUnixSchema                   = errors.New("URL schema is not unix")
	ErrSocketNotFound                 = errors.New("socket not found")
	ErrSocketNotFoundInPath           = errors.New("docker socket not found in " + DockerSocketPath)
	// ErrTestcontainersHostNotSetInProperties this error is specific to Testcontainers
	ErrTestcontainersHostNotSetInProperties = errors.New("tc.host not set in ~/.testcontainers.properties")
)

var (
	ErrRootlessDockerNotFound               = errors.New("rootless Docker not found")
	ErrRootlessDockerNotFoundHomeDesktopDir = errors.New("checked path: ~/.docker/desktop/docker.sock")
	ErrRootlessDockerNotFoundHomeRunDir     = errors.New("checked path: ~/.docker/run/docker.sock")
	ErrRootlessDockerNotFoundRunDir         = errors.New("checked path: /run/user/${uid}/docker.sock")
	ErrRootlessDockerNotFoundXDGRuntimeDir  = errors.New("checked path: $XDG_RUNTIME_DIR")
	ErrRootlessDockerNotSupportedWindows    = errors.New("rootless Docker is not supported on Windows")
	ErrXDGRuntimeDirNotSet                  = errors.New("XDG_RUNTIME_DIR is not set")
)

var DockerHostContextKey = dockerHostContext("docker_host")

var DockerSocketPath = "/var/run/docker.sock"

DockerSocketPath is the path to the docker socket under unix systems.

var DockerSocketPathWithSchema = DockerSocketSchema + DockerSocketPath

DockerSocketPathWithSchema is the path to the docker socket under unix systems with the unix schema.

var DockerSocketSchema = "unix://"

DockerSocketSchema is the unix schema.

var TCPSchema = "tcp://"

TCPSchema is the tcp schema.

var WindowsDockerSocketPath = "//var/run/docker.sock"

WindowsDockerSocketPath is the path to the docker socket under windows systems.

Functions

func DefaultGatewayIP

func DefaultGatewayIP() (string, error)

deprecated see https://github.com/testcontainers/testcontainers-java/blob/main/core/src/main/java/org/testcontainers/dockerclient/DockerClientConfigUtils.java#L46

func DefaultLabels

func DefaultLabels(sessionID string) map[string]string

func ExtractDockerHost

func ExtractDockerHost(ctx context.Context) string

ExtractDockerHost Extracts the docker host from the different alternatives, caching the result to avoid unnecessary calculations. Use this function to get the actual Docker host. This function does not consider Windows containers at the moment. The possible alternatives are:

1. Docker host from the "tc.host" property in the ~/.testcontainers.properties file.
2. DOCKER_HOST environment variable.
3. Docker host from context.
4. Docker host from the default docker socket path, without the unix schema.
5. Docker host from the "docker.host" property in the ~/.testcontainers.properties file.
6. Rootless docker socket path.
7. Else, the default Docker socket including schema will be returned.

func ExtractDockerSocket

func ExtractDockerSocket(ctx context.Context) string

ExtractDockerSocket Extracts the docker socket from the different alternatives, removing the socket schema and caching the result to avoid unnecessary calculations. Use this function to get the docker socket path, not the host (e.g. mounting the socket in a container). This function does not consider Windows containers at the moment. The possible alternatives are:

1. Docker host from the "tc.host" property in the ~/.testcontainers.properties file.
2. The TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE environment variable.
3. Using a Docker client, check if the Info().OperativeSystem is "Docker Desktop" and return the default docker socket path for rootless docker.
4. Else, Get the current Docker Host from the existing strategies: see ExtractDockerHost.
5. If the socket contains the unix schema, the schema is removed (e.g. unix:///var/run/docker.sock -> /var/run/docker.sock)
6. Else, the default location of the docker socket is used (/var/run/docker.sock)

In any case, if the docker socket schema is "tcp://", the default docker socket path will be returned.

func ExtractImagesFromDockerfile

func ExtractImagesFromDockerfile(dockerfile string, buildArgs map[string]*string) ([]string, error)

ExtractImagesFromDockerfile extracts images from the Dockerfile sourced from dockerfile.

func ExtractImagesFromReader

func ExtractImagesFromReader(r io.Reader, buildArgs map[string]*string) ([]string, error)

ExtractImagesFromReader extracts images from the Dockerfile sourced from r.

func ExtractRegistry

func ExtractRegistry(image string, fallback string) string

ExtractRegistry extracts the registry from the image name, using a regular expression to extract the registry from the image name. regular expression to extract the registry from the image name the regular expression is based on the grammar defined in - image:tag - image - repository/image:tag - repository/image - registry/image:tag - registry/image - registry/repository/image:tag - registry/repository/image - registry:port/repository/image:tag - registry:port/repository/image - registry:port/image:tag - registry:port/image Once extracted the registry, it is validated to check if it is a valid URL or an IP address.

func InAContainer

func InAContainer() bool

InAContainer returns true if the code is running inside a container See https://github.com/docker/docker/blob/a9fa38b1edf30b23cae3eade0be48b3d4b1de14b/daemon/initlayer/setup_unix.go#L25

func IsURL

func IsURL(str string) bool

IsURL checks if the string is an URL. Extracted from https://github.com/asaskevich/govalidator/blob/f21760c49a8d/validator.go#L104

func IsWindows

func IsWindows() bool

IsWindows returns if the current OS is Windows. For that it checks the GOOS environment variable or the runtime.GOOS constant.

func NewClient

func NewClient(ctx context.Context, ops ...client.Opt) (*client.Client, error)

NewClient returns a new docker client extracting the docker host from the different alternatives

func ProcessID

func ProcessID() string

func ProjectPath

func ProjectPath() string

func SessionID

func SessionID() string