core

Documentation

Index

• Constants
• Variables
• func AddDefaultLabels(sessionID string, target map[string]string)
• func DefaultGatewayIP() (string, error)
• func DefaultLabels(sessionID string) map[string]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 MergeCustomLabels(dst, src map[string]string) error
• func MustExtractDockerHost(ctx context.Context) string
• func MustExtractDockerSocket(ctx context.Context) string
• 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 is the base label for all testcontainers labels.
	LabelBase = "org.testcontainers"

	// LabelLang specifies the language which created the test container.
	LabelLang = LabelBase + ".lang"

	// LabelReaper identifies the container as a reaper.
	LabelReaper = LabelBase + ".reaper"

	// LabelRyuk identifies the container as a ryuk.
	LabelRyuk = LabelBase + ".ryuk"

	// LabelSessionID specifies the session ID of the container.
	LabelSessionID = LabelBase + ".sessionId"

	// LabelVersion specifies the version of testcontainers which created the container.
	LabelVersion = LabelBase + ".version"

	// LabelReap specifies the container should be reaped by the reaper.
	LabelReap = LabelBase + ".reap"
)

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 AddDefaultLabels

func AddDefaultLabels(sessionID string, target map[string]string)

AddDefaultLabels adds the default labels for sessionID to target.

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

DefaultLabels returns the standard set of labels which includes LabelSessionID if the reaper is enabled.

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 MergeCustomLabels

func MergeCustomLabels(dst, src map[string]string) error

MergeCustomLabels sets labels from src to dst. If a key in src has LabelBase prefix returns an error. If dst is nil returns an error.

func MustExtractDockerHost

func MustExtractDockerHost(ctx context.Context) string

MustExtractDockerHost 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, because the Docker host is not set, it panics.

func MustExtractDockerSocket

func MustExtractDockerSocket(ctx context.Context) string

MustExtractDockerSocket 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 MustExtractDockerHost.
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)

It panics if a Docker client cannot be created, or the Docker host cannot be discovered.

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