docs: fixing one example module and generating feature and quickstart docs

Author: terry-docker

docs/features/authentication.md

@@ -0,0 +1,109 @@
+# Docker Authentication
+
+Testcontainers-Python supports various methods of authenticating with Docker registries. This is essential when working with private registries or when you need to pull images that require authentication.
+
+## Basic Authentication
+
+The simplest way to authenticate is using Docker's built-in credential store. Testcontainers-Python will automatically use credentials stored by Docker:
+
+```python
+from testcontainers.generic import GenericContainer
+
+# Docker will automatically use stored credentials
+container = GenericContainer("private.registry.com/myimage:latest")
+```
+
+## Environment Variables
+
+You can provide registry credentials using environment variables:
+
+```bash
+# Set registry credentials
+export DOCKER_USERNAME=myuser
+export DOCKER_PASSWORD=mypassword
+export DOCKER_REGISTRY=private.registry.com
+```
+
+## Configuration File
+
+You can also configure authentication in the `.testcontainers.properties` file:
+
+```properties
+registry.username=myuser
+registry.password=mypassword
+registry.url=private.registry.com
+```
+
+## Programmatic Authentication
+
+For more control, you can provide credentials programmatically:
+
+```python
+from testcontainers.core.config import TestcontainersConfiguration
+
+# Configure registry credentials
+config = TestcontainersConfiguration()
+config.registry_username = "myuser"
+config.registry_password = "mypassword"
+config.registry_url = "private.registry.com"
+
+# Use the configuration
+container = GenericContainer("private.registry.com/myimage:latest")
+```
+
+## AWS ECR Authentication
+
+For Amazon Elastic Container Registry (ECR), Testcontainers-Python supports automatic authentication:
+
+```python
+from testcontainers.generic import GenericContainer
+
+# ECR authentication is handled automatically
+container = GenericContainer("123456789012.dkr.ecr.region.amazonaws.com/myimage:latest")
+```
+
+## Google Container Registry (GCR)
+
+For Google Container Registry, you can use Google Cloud credentials:
+
+```python
+from testcontainers.generic import GenericContainer
+
+# GCR authentication using Google Cloud credentials
+container = GenericContainer("gcr.io/myproject/myimage:latest")
+```
+
+## Azure Container Registry (ACR)
+
+For Azure Container Registry, you can use Azure credentials:
+
+```python
+from testcontainers.generic import GenericContainer
+
+# ACR authentication using Azure credentials
+container = GenericContainer("myregistry.azurecr.io/myimage:latest")
+```
+
+## Best Practices
+
+1. Never commit credentials to version control
+2. Use environment variables or secure credential stores
+3. Rotate credentials regularly
+4. Use the least privileged credentials necessary
+5. Consider using Docker credential helpers
+6. Use registry-specific authentication when available
+7. Keep credentials secure and encrypted
+8. Use separate credentials for different environments
+
+## Troubleshooting
+
+If you encounter authentication issues:
+
+1. Verify your credentials are correct
+2. Check if the registry is accessible
+3. Ensure your Docker daemon is running
+4. Check Docker's credential store
+5. Verify network connectivity
+6. Check for any proxy settings
+7. Look for any rate limiting
+8. Check registry-specific requirements

docs/features/building_images.md

@@ -0,0 +1,190 @@
+# 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:
+
+```python
+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:
+
+```python
+# 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:
+
+```python
+# 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:
+
+```python
+# 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:
+
+```python
+# 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:
+
+```python
+# Build with labels
+image = build_image(
+    path="path/to/dockerfile/directory",
+    labels={
+        "test": "true",
+        "environment": "test"
+    },
+    tag="myapp:test"
+)
+```
+
+## Best Practices
+
+1. Use appropriate tags
+2. Clean up built images
+3. Use build arguments for configuration
+4. Consider build context size
+5. Use appropriate build caching
+6. Handle build failures
+7. Use appropriate platforms
+8. Add meaningful labels
+
+## Common Use Cases
+
+### Building Test Images
+
+```python
+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
+
+```python
+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
+
+```python
+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:
+
+1. Check Dockerfile syntax
+2. Verify build context
+3. Check for missing files
+4. Verify build arguments
+5. Check for platform compatibility
+6. Verify cache settings
+7. Check for resource limits
+8. Verify Docker daemon state