Using Podman instead of Docker

Testcontainers for Go supports the use of Podman (rootless or rootful) instead of Docker.

In most scenarios no special setup is required in Testcontainers for Go. Testcontainers for Go will automatically discover the socket based on the DOCKER_HOST environment variables. Alternatively you can configure the host with a .testcontainers.properties file. The discovered Docker host is taken into account when starting a reaper container. The discovered socket is used to detect the use of Podman.

By default Testcontainers for Go takes advantage of the default network settings both Docker and Podman are applying to newly created containers. It only intervenes in scenarios where a ContainerRequest specifies networks and does not include the default network of the current container provider. Unfortunately the default network for Docker is called bridge where the default network in Podman is called podman.

In complex container network scenarios it may be required to explicitly make use of the ProviderPodman like so:

package some_test

import (
    "testing"
    tc "github.com/testcontainers/testcontainers-go"
)

func TestSomething(t *testing.T) {
    req := tc.GenericContainerRequest{
        ProviderType: tc.ProviderPodman,
        ContainerRequest: tc.ContainerRequest{
            Image: "nginx:alpine"
        },
    }

    // ...
}

The ProviderPodman configures the DockerProvider with the correct default network for Podman to ensure complex network scenarios are working as with Docker.

Podman socket activation

The reaper container needs to connect to the docker daemon to reap containers, so the podman socket service must be started:

> systemctl --user start podman.socket

MacOS

Currently, in MacOS the autodetection of podman does not work as intended, which leads to Ryuk failing at boot-up. In order to use Testcontainers then either 1. Disable Ryuk (not recommended): see here 2. If you want to use Ryuk then you need 1. Run podman in rootful mode by running the following commands

  podman machine stop
  podman machine set --rootful
  podman machine start

2. Add

ryuk.container.privileged=true

to ~/.testcontainers.properties 3. Use the WithProvider option when running your containers

package some_test

import (
    "testing"

    tc "github.com/testcontainers/testcontainers-go"
)

func TestSomething(t *testing.T) {
    ctx := t.Context()
    ctr, err := tc.Run(ctx,
        "docker.io/myservice:1.2.3",
        tc.WithProvider(tc.ProviderPodman),
    )

    // ...
}

As an alternative to declaring the provider in the tests themselves, set the TESTCONTAINERS_PROVIDER environment variable to podman to select Podman for tests that do not explicitly choose a provider. You can also set provider=podman in the .testcontainers.properties file in your home directory. An explicit provider in code takes precedence over the environment variable, which takes precedence over the properties file.

New integrations can register Podman through its Go module:

import _ "github.com/testcontainers/testcontainers-go/modules/podman"

Select it with TESTCONTAINERS_PROVIDER=podman or provider=podman. The import registers the provider; it does not start or connect to Podman. Adding the dependency to go.mod without importing it does not register it.

The built-in Podman path and ProviderPodman remain available during migration, so existing tests do not need to change immediately. Both paths retain the same Docker-compatible endpoint discovery and podman default bridge network.

Provider modules initialize before Docker host or socket discovery, including when the first operation is direct client construction. Select the runtime before any Testcontainers operation; a process cannot switch to a different managed runtime after initialization. Selecting an unregistered provider returns an error.

Fedora

DOCKER_HOST environment variable must be set

> export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock

SELinux may require a custom policy be applied to allow the reaper container to connect to and write to a socket. Once you experience the se-linux error, you can run the following commands to create and install a custom policy.

> sudo ausearch -c 'app' --raw | audit2allow -M my-podman
> sudo semodule -i my-podman.pp

The resulting my-podman.te file should look something like this:

module my-podman2 1.0;

require {
        type user_tmp_t;
        type container_runtime_t;
        type container_t;
        class sock_file write;
        class unix_stream_socket connectto;
}

#============= container_t ==============
allow container_t container_runtime_t:unix_stream_socket connectto;
allow container_t user_tmp_t:sock_file write;

NOTE: It will take two rounds of installing a policy, then experiencing the next se-linux issue, install new policy, etc...