Why does LocalStackContainer need to override the entry point?

[aelfric]

In the LocalStackContainer the library creates a new entry point script by constructing a file here.

I haven't traced through the code in detail, but it seems like all this custom command does is set some environment variables. Why is that necessary rather than setting the environment variables using addEnv?

The reason I ask is at my company we are not allowed to download images directly from dockerhub so someone had contributed our own image that behaves like the one on dockerhub except that the entry point script was written to /bin/docker-entrypoint.sh instead of /usr/local/bin/docker-entrypoint.sh. We can and are fixing our container to use the same path as upstream, but I was wondering why wouldn't the container needs to override the entry point at all.

[MILLERMARRU]

The entry point override exists because LocalStack's startup sequence requires more than just setting environment variables — it needs to bootstrap internal services, configure port routing, and set up the LocalStack daemon in a specific order that a plain shell entrypoint controls. Simply using addEnv() would set the variables too late in the lifecycle (after the entrypoint has already run) for some settings to take effect.

Why addEnv() alone isn't enough

LocalStack's original entrypoint script:

1. Sets up internal directories and permissions
2. Configures the EDGE_PORT routing table before the main process starts
3. Bootstraps service-specific processes in order

If you only set env vars with addEnv(), those variables exist in the container environment but the entrypoint logic that reads them to configure routing has already completed. The script path override ensures Testcontainers injects the configuration before that bootstrap phase.

Fix for a custom image with a different entrypoint path

If your organization's custom image has the entrypoint at /bin/docker-entrypoint.sh instead of the default /usr/local/bin/docker-entrypoint.sh, override it with withCreateContainerCmdModifier:

LocalStackContainer localstack = new LocalStackContainer(
        DockerImageName.parse("your-org/localstack:latest")
            .asCompatibleSubstituteFor("localstack/localstack"))
    .withServices(LocalStackContainer.Service.S3, LocalStackContainer.Service.SQS)
    .withCreateContainerCmdModifier(cmd ->
        cmd.withEntrypoint("/bin/docker-entrypoint.sh")
    );

Alternative: subclass LocalStackContainer

For a reusable solution across your test suite:

public class CustomLocalStackContainer extends LocalStackContainer {

    private static final String CUSTOM_ENTRYPOINT = "/bin/docker-entrypoint.sh";

    public CustomLocalStackContainer(DockerImageName image) {
        super(image);
        withCreateContainerCmdModifier(cmd -> cmd.withEntrypoint(CUSTOM_ENTRYPOINT));
    }
}

Verify it's working

After startup, confirm LocalStack bootstrapped correctly:

@BeforeAll
static void setup() {
    localstack.start();
    // LocalStack exposes a health endpoint
    String health = localstack.execInContainer("curl", "-s",
        "http://localhost:4566/_localstack/health").getStdout();
    System.out.println("LocalStack health: " + health);
}