Skip to content

Registry

Since v0.30.0

Introduction

The Testcontainers module for Registry.

Adding this module to your project dependencies

Please run the following command to add the Registry module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/registry

Usage example

registryContainer, err := registry.Run(context.Background(), "registry:2.8.3")
defer func() {
    if err := testcontainers.TerminateContainer(registryContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

Module Reference

Run function

Info

The RunContainer(ctx, opts...) function is deprecated and will be removed in the next major release of Testcontainers for Go.

The Registry module exposes one entrypoint function to create the Registry container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*RegistryContainer, error)
  • context.Context, the Go context.
  • string, the Docker image to use.
  • testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "registry:2.8.3").

Docker Auth Config

The module exposes a way to set the Docker Auth Config for the Registry container, thanks to the SetDockerAuthConfig function. This is useful when you need to pull images from a private registry. It basically sets the DOCKER_AUTH_CONFIG environment variable with authentication for the given host, username and password sets. It returns a function to reset the environment back to the previous state, which is helpful when you need to reset the environment after a test.

On the same hand, the module also exposes a way to build a Docker Auth Config for the Registry container, thanks to the DockerAuthConfig helper function. This function returns a map of AuthConfigs including base64 encoded Auth field for the provided details. It also accepts additional host, username and password triples to add more auth configurations.

Container Options

When starting the Registry container, you can pass options in a variadic way to configure it.

With Authentication

It's possible to enable authentication for the Registry container. By default, it is disabled, but you can enable it in two ways:

  • You can use WithHtpasswd to enable authentication with a string representing the contents of a htpasswd file. A temporary file will be created with the contents of the string and copied to the container.
  • You can use WithHtpasswdFile to copy a htpasswd file from your local filesystem to the container.

In both cases, the htpasswd file will be copied into the /auth directory inside the container.

registryContainer, err := registry.Run(
    ctx,
    registry.DefaultImage,
    registry.WithHtpasswd("testuser:$2y$05$tTymaYlWwJOqie.bcSUUN.I.kxmo1m5TLzYQ4/ejJ46UMXGtq78EO"),
)

ctx := context.Background()
registryContainer, err := registry.Run(
    ctx,
    "registry:2.8.3",
    registry.WithHtpasswdFile(filepath.Join("testdata", "auth", "htpasswd")),
    registry.WithData(filepath.Join("testdata", "data")),
)

WithData

In the case you want to initialise the Registry with your own images, you can use WithData to copy a directory from your local filesystem to the container. The directory will be copied into the /data directory inside the container. The format of the directory should be the same as the one used by the Registry to store images. Otherwise, the Registry will start but you won't be able to read any images from it.

ctx := context.Background()
registryContainer, err := registry.Run(
    ctx,
    "registry:2.8.3",
    registry.WithHtpasswdFile(filepath.Join("testdata", "auth", "htpasswd")),
    registry.WithData(filepath.Join("testdata", "data")),
)

The following options are exposed by the testcontainers package.

Basic Options

Lifecycle Options

Files & Mounts Options

Build Options

Logging Options

Image Options

Networking Options

Advanced Options

Experimental Options

Container Methods

The Registry container exposes the following methods:

HostAddress

This method returns the host address including port of the Distribution Registry. E.g. localhost:32878.

Address

This method returns the HTTP address string to connect to the Distribution Registry, so that you can use to connect to the Registry. E.g. http://localhost:32878.

httpAddress, err := registryContainer.Address(ctx)

ImageExists

The ImageExists method allows to check if an image exists in the Registry. It receives the Go context and the image reference as parameters.

Info

The image reference should be in the format my-registry:port/image:tag in order to be pushed to the Registry.

PushImage

The PushImage method allows to push an image to the Registry. It receives the Go context and the image reference as parameters.

Info

The image reference should be in the format my-registry:port/image:tag in order to be pushed to the Registry.

// repo is localhost:32878/customredis
// tag is v1.2.3
newImage := fmt.Sprintf("%s:%s", repo, tag)
err = registryContainer.PushImage(context.Background(), fmt.Sprintf("%s:%s", repo, tag))
if err != nil {
    log.Printf("failed to push image: %s", err)
    return
}

If the push operation is successful, the method will internally wait for the image to be available in the Registry, querying the Registry API, returning an error in case of any failure (e.g. pushing or waiting for the image).

PullImage

  • Not available until the next release main

The PullImage method allows to pull an image to local Docker daemon. This method downloads (copies) the specified image reference so it becomes available locally for further operations such as tagging or pushing. It receives the Go context and the image reference as parameters, pulling the image with the same platform as the registry container's image.

Info

The image reference should be in the format my-registry:port/image:tag in order to be pulled from the Registry.

// defaultRegistryURI is localhost:32878
// defaultImage is customredis
// defaultTag is v1.2.3
imageRef := fmt.Sprintf("%s/%s:%s", defaultRegistryURI, defaultImage, defaultTag)
err = registryContainer.PullImage(ctx, imageRef)
if err != nil {
    log.Printf("failed to pull image: %s", err)
    return
}

TagImage

  • Not available until the next release main

The TagImage method allows to tag an image from the local Registry. It receives the Go context, the image reference and the name of the new tag as parameters.

Info

The image reference should be in the format my-registry:port/image:tag in order to be tagged properly.

// defaultRegistryURI is localhost:32878
// defaultImage is customredis
// defaultTag is v1.2.3
taggedImage := fmt.Sprintf("%s/%s:%s", registryContainer.RegistryName, defaultImage, defaultTag)
err = registryContainer.TagImage(ctx, imageRef, taggedImage)
if err != nil {
    log.Printf("failed to tag image: %s", err)
    return
}

DeleteImage

The DeleteImage method allows to delete an image from the Registry. It receives the Go context and the image reference as parameters.

Info

The image reference should be in the format image:tag in order to be deleted from the Registry.

// newImage is customredis:v1.2.3
err = registryContainer.DeleteImage(context.Background(), newImage)
if err != nil {
    log.Printf("failed to delete image: %s", err)
    return
}