Building Images from Dockerfiles¶

Testcontainers-Python allows you to build Docker images from Dockerfiles during test execution. This is useful when you need to test custom images or when you want to ensure your Dockerfile builds correctly.

Basic Image Building¶

The simplest way to build an image is using the build_image function:

from testcontainers.core.container import build_image

# Build an image from a Dockerfile
image = build_image(
    path="path/to/dockerfile/directory",
    tag="myapp:test"
)

# Use the built image
with GenericContainer(image) as container:
    # Your test code here
    pass

Building with Options¶

You can customize the build process with various options:

# Build with specific Dockerfile
image = build_image(
    path="path/to/dockerfile/directory",
    dockerfile="Dockerfile.test",
    tag="myapp:test"
)

# Build with build arguments
image = build_image(
    path="path/to/dockerfile/directory",
    buildargs={
        "VERSION": "1.0.0",
        "ENVIRONMENT": "test"
    },
    tag="myapp:test"
)

# Build with target stage
image = build_image(
    path="path/to/dockerfile/directory",
    target="test",
    tag="myapp:test"
)

Building with Context¶

You can specify a build context:

# Build with specific context
image = build_image(
    path="path/to/dockerfile/directory",
    context="path/to/build/context",
    tag="myapp:test"
)

Building with Cache¶

You can control build caching:

# Build without cache
image = build_image(
    path="path/to/dockerfile/directory",
    nocache=True,
    tag="myapp:test"
)

# Build with specific cache from
image = build_image(
    path="path/to/dockerfile/directory",
    cache_from=["myapp:latest"],
    tag="myapp:test"
)

Building with Platform¶

You can specify the target platform:

# Build for specific platform
image = build_image(
    path="path/to/dockerfile/directory",
    platform="linux/amd64",
    tag="myapp:test"
)

Building with Labels¶

You can add labels to the built image:

# Build with labels
image = build_image(
    path="path/to/dockerfile/directory",
    labels={
        "test": "true",
        "environment": "test"
    },
    tag="myapp:test"
)

Best Practices¶

Use appropriate tags
Clean up built images
Use build arguments for configuration
Consider build context size
Use appropriate build caching
Handle build failures
Use appropriate platforms
Add meaningful labels

Common Use Cases¶

Building Test Images¶

def test_custom_image():
    # Build test image
    image = build_image(
        path="path/to/dockerfile/directory",
        buildargs={"TEST_MODE": "true"},
        tag="myapp:test"
    )

    # Use the test image
    with GenericContainer(image) as container:
        # Your test code here
        pass

Building with Dependencies¶

def test_with_dependencies():
    # Build base image
    base_image = build_image(
        path="path/to/base/dockerfile/directory",
        tag="myapp:base"
    )

    # Build test image using base
    test_image = build_image(
        path="path/to/test/dockerfile/directory",
        cache_from=[base_image],
        tag="myapp:test"
    )

Building for Different Environments¶

def test_different_environments():
    # Build for different environments
    environments = ["dev", "test", "staging"]

    for env in environments:
        image = build_image(
            path="path/to/dockerfile/directory",
            buildargs={"ENVIRONMENT": env},
            tag=f"myapp:{env}"
        )

Troubleshooting¶

If you encounter issues with image building:

Check Dockerfile syntax
Verify build context
Check for missing files
Verify build arguments
Check for platform compatibility
Verify cache settings
Check for resource limits
Verify Docker daemon state