feat: add WithReadOnlyRootFilesystem option

[jespino]

Add WithReadOnlyRootFilesystem option

Description

This PR implements the WithReadOnlyRootFilesystem option to allow running containers with read-only root filesystem, addressing the enhancement request in issue #2803.

Changes

✅ Implementation

• Added WithReadOnlyRootFilesystem() function in options.go

• Sets Docker's ReadonlyRootfs field to true in HostConfig

• Properly handles existing HostConfigModifier functions by wrapping them

• Follows existing codebase patterns and conventions

✅ Testing

• Unit tests in options_test.go:

  • Tests function works with no existing HostConfigModifier

  • Tests preservation of existing HostConfigModifier settings

  • Verifies ReadonlyRootfs field is correctly set

• Integration tests in readonly_integration_test.go:

  • Verifies write operations fail on read-only root filesystem

  • Confirms tmpfs mounts work for writable areas

  • Validates container configuration is properly applied

✅ Documentation

• Updated common_functional_options_list.md with new option

• Added comprehensive documentation in common_functional_options.md

• Included usage examples and best practices

• Created complete example in examples/readonly/

Usage

Basic Usage

container, err := testcontainers.Run(ctx, "alpine:latest",

    testcontainers.WithReadOnlyRootFilesystem(),

)

Advanced Usage with Tmpfs

container, err := testcontainers.Run(ctx, "alpine:latest",

    testcontainers.WithReadOnlyRootFilesystem(),

    testcontainers.WithTmpfs(map[string]string{"/tmp": "rw,noexec,nosuid,size=100m"}),

)

Benefits

• Security Enhancement: Prevents unauthorized writes to the root filesystem

• Production Parity: Helps catch bugs that occur in production environments with read-only containers

• Testing Reliability: Ensures applications work correctly with security hardening measures

Equivalent Docker Command

This option is equivalent to using the --read-only flag with docker run:

docker run --read-only alpine:latest

Backward Compatibility

✅ Fully backward compatible - no breaking changes

✅ Works seamlessly with existing HostConfigModifier functions

✅ Follows established patterns in the codebase

Fixes #2803

Checklist

• [x] Implementation follows existing code patterns

• [x] Comprehensive unit tests added

• [x] Integration tests added

• [x] Documentation updated

• [x] Example code provided

• [x] Backward compatibility maintained

• [x] No breaking changes introduced

[netlify[bot]]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	ae5ec8a9a2359920e21c4352eac927de1a13e3ac
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/68d03e86cc5eb10008d1bd2b
😎 Deploy Preview	https://deploy-preview-3303--testcontainers-go.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.