From 34babb06f59458dd68b88bdea39061b6c5b01847 Mon Sep 17 00:00:00 2001 From: Meyon Soo Kim <39788337+PreAgile@users.noreply.github.com> Date: Tue, 10 Mar 2026 16:39:35 +0900 Subject: [PATCH 1/4] add: contribution research notes for testcontainers-java --- docs/contributor-research/README.md | 252 ++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 docs/contributor-research/README.md diff --git a/docs/contributor-research/README.md b/docs/contributor-research/README.md new file mode 100644 index 00000000000..1c6cd1d6518 --- /dev/null +++ b/docs/contributor-research/README.md @@ -0,0 +1,252 @@ +# Testcontainers Java Contribution Research + +## Goal + +This note summarizes contribution candidates for a Spring / Java / Kotlin backend engineer targeting `testcontainers/testcontainers-java`. + +The focus is not only "what is easy", but "what will look strong to backend hiring teams while still having a realistic merge path". + +## Repository Health + +- Upstream repository: `testcontainers/testcontainers-java` +- Local fork remote: `PreAgile/testcontainers-java` +- Current local branch: `main` +- Working tree state at review time: clean + +Signals that the repository is actively maintained: + +- `good first issue` labels are still in use +- merged PRs exist in late 2025 and early 2026 +- recent human-merged PRs include: + - `#11498` merged on `2026-02-26` + - `#11223` merged on `2026-03-02` + +## Local Codebase Areas That Matter + +Relevant local paths: + +- `docs/contributing.md` +- `docs/contributing_docs.md` +- `docs/modules/k6.md` +- `modules/k6/src/test/java/org/testcontainers/k6/K6ContainerTests.java` +- `modules/r2dbc/src/main/java/org/testcontainers/r2dbc/R2DBCDatabaseContainer.java` +- `modules/postgresql/src/main/java/org/testcontainers/postgresql/PostgreSQLR2DBCDatabaseContainer.java` +- `modules/mysql/src/main/java/org/testcontainers/mysql/MySQLR2DBCDatabaseContainer.java` +- `modules/mongodb/src/main/java/org/testcontainers/mongodb/MongoDBContainer.java` +- `modules/jdbc/src/main/java/org/testcontainers/jdbc/ContainerDatabaseDriver.java` + +## Maintainer Preference Pattern + +Observed pattern from recent merged PRs: + +- small scope +- module-focused changes +- tests included for code changes +- low review burden + +Examples: + +- `#11498` changed 2 files and added a focused implementation plus test update +- `#11223` changed 3 files with a targeted compatibility fix + +This strongly suggests that a first PR should avoid broad cross-cutting core changes. + +## Candidate Ranking + +### 1. Best first PR: `#8780` + +Title: + +- `[Enhancement]: Add example test to the K6 module docs` + +Why this is the safest first merge: + +- issue scope is clear +- user pain is already documented in the issue body +- implementation is mostly docs/example work +- it does not require design negotiation across multiple modules + +Problem analysis: + +- `docs/modules/k6.md` currently includes a code snippet from `K6ContainerTests` +- the docs show the API, but do not clearly present the "typical test shape" that users expect +- the issue author explicitly compared it unfavorably to quickstart-style docs + +Root cause: + +- documentation exposes a snippet, but not an opinionated onboarding flow +- discoverability is weaker than in other Testcontainers modules + +Why this helps a Spring/backend profile: + +- not as strong as a code PR, but excellent as a first merged foothold +- shows you can read the repo conventions and contribute cleanly + +Recommended PR shape: + +- keep it to docs and possibly example snippet framing +- do not over-design a new example project unless maintainers ask for it +- align the K6 docs with the style of existing quickstart/test integration pages + +Merge probability: + +- high + +### 2. Best second PR: `#8797` + +Title: + +- `Add getR2dbcUrl helper method to JdbcDatabaseContainer` + +Why this is the best backend-signaling PR: + +- directly relevant to Spring, reactive stacks, database integration, and developer ergonomics +- stronger hiring signal than a docs PR +- maintainers already discussed acceptable design direction + +Problem analysis: + +- current R2DBC support exposes `getOptions(container)` methods +- users who want a concrete R2DBC URL string must construct it manually +- that hurts discoverability and ease of use + +Important maintainer guidance already found in the issue: + +- do not force this into a generic `JdbcDatabaseContainer` API immediately +- preferred direction is static `getR2dbcUrl(container)` helpers on each `R2DBCDatabaseContainer` implementation +- this was discussed explicitly by maintainers in the issue thread + +Existing failed attempt: + +- PR `#9569` attempted the feature +- maintainer immediately asked for tests +- contributor then got stuck on MSSQL-specific test issues +- PR was eventually closed + +What that means: + +- the feature itself is not rejected +- the implementation failed because the scope was too broad and the testing path got messy + +Best way to revive it: + +- comment on the issue first +- confirm that the agreed static-method design is still welcome +- explicitly propose a narrow first step +- avoid broad "support everything at once" unless maintainers request it + +Safer implementation plan: + +1. Start with the stable implementations that are easiest to test cleanly +2. Add tests alongside each helper +3. Leave tricky drivers such as MSSQL for follow-up if needed + +Why this helps a Spring/backend profile: + +- strongest fit for Spring / Java backend positioning +- good talking point for R2DBC, developer experience, and integration testing + +Merge probability: + +- medium to high if kept narrow +- medium or lower if implemented across too many drivers at once + +### 3. High-value but risky: `#3066` + +Title: + +- `Support init scripts for MongoDBContainer without manually customizing the WaitStrategy` + +Why it is attractive: + +- strong backend signal +- involves lifecycle, initialization order, replica set handling, and wait strategy design + +Problem analysis from issue and code: + +- placing scripts under `/docker-entrypoint-initdb.d` can trigger MongoDB restart behavior +- local `MongoDBContainer` currently relies on `Wait.forLogMessage("(?i).*waiting for connections.*", 1)` +- that does not robustly cover the init-script + replica-set startup sequence + +Root cause: + +- container readiness assumptions do not fully match Mongo init script behavior +- `MongoDBContainer` also performs replica set initialization after start, which increases timing sensitivity + +Why it is risky as a first PR: + +- more design ambiguity +- more regression risk +- higher chance of maintainers asking for a reproducer-heavy discussion or broader design changes + +Merge probability: + +- medium at best for a newcomer first PR + +### 4. Not recommended first: `#1537` + +Title: + +- `Support hikari data-source-properties in ContainerDatabaseDriver` + +Why it looks easy but is not: + +- the surface request is "just pass `Properties info` through" +- in practice it may affect: + - JDBC property propagation + - connection creation semantics + - cache key behavior in `ContainerDatabaseDriver` + +Root cause: + +- `ContainerDatabaseDriver.connect(String url, Properties info)` does not currently flow those properties in a newcomer-safe way +- any fix in this path touches JDBC core behavior, not just one module + +Why it is a poor first PR: + +- too core +- too broad +- too easy to create subtle regressions + +Merge probability: + +- low for a first contribution + +## Recommended Order + +1. `#8780` K6 docs/example PR +2. `#8797` R2DBC helper PR +3. `#3066` MongoDB wait-strategy/init-script PR + +## Suggested PR Positioning + +### For `#8780` + +PR message should emphasize: + +- clearer onboarding +- quickstart-style discoverability +- alignment with existing docs conventions + +### For `#8797` + +PR message should emphasize: + +- narrowed scope +- implementation following the already discussed issue design +- tests added for each touched helper +- no attempt to redesign the entire R2DBC abstraction + +Suggested issue comment before coding: + +> I would like to revive this using the static `getR2dbcUrl(container)` approach discussed above. +> To keep the scope reviewable, I plan to add the helper with tests for the stable implementations first and leave any problematic drivers for a follow-up PR if needed. +> Does that still match the expected direction? + +## Practical Notes + +- For docs contributions, follow `docs/contributing_docs.md` +- For code contributions, follow `docs/contributing.md` +- Run formatting and tests before opening a PR +- Keep each PR scoped to one issue and one clear problem +- For a newcomer, "small and mergeable" is more valuable than "ambitious but stalled" From b7758ca292fae070c56fbbe82281487988a38943 Mon Sep 17 00:00:00 2001 From: Meyon Soo Kim <39788337+PreAgile@users.noreply.github.com> Date: Tue, 10 Mar 2026 17:33:30 +0900 Subject: [PATCH 2/4] docs: expand contributor strategy notes --- docs/contributor-research/README.md | 135 ++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) diff --git a/docs/contributor-research/README.md b/docs/contributor-research/README.md index 1c6cd1d6518..95c0ea45a72 100644 --- a/docs/contributor-research/README.md +++ b/docs/contributor-research/README.md @@ -218,6 +218,141 @@ Merge probability: 2. `#8797` R2DBC helper PR 3. `#3066` MongoDB wait-strategy/init-script PR +## First PR Recommendation + +### Recommended first merged PR + +Issue: + +- `#8780` `[Enhancement]: Add example test to the K6 module docs` + +Link: + +- `https://github.com/testcontainers/testcontainers-java/issues/8780` + +Why this is the best first PR: + +- the issue scope is concrete +- the user pain is already written clearly in the issue +- it avoids deep design arguments +- it matches the small-PR preference observed in recent merged work + +Problem analysis: + +- `docs/modules/k6.md` already exposes API usage through codeinclude +- however, it still does not clearly show the "expected JUnit-style test shape" that users look for +- the issue reporter explicitly compared the docs to quickstart-style guidance and found the current page harder to follow + +Root cause: + +- the docs expose a runnable snippet +- but the onboarding flow is weaker than in more polished Testcontainers pages +- the page answers "what API exists" better than "how should I write my first test" + +Recommended solution shape: + +1. Update `docs/modules/k6.md` +2. Reuse the existing runnable snippet from `modules/k6/src/test/java/org/testcontainers/k6/K6ContainerTests.java` +3. Add a short JUnit-style explanation section +4. Keep the change limited to docs and snippet framing unless maintainers request more + +Why this should merge well: + +- it is easy to review +- it improves user onboarding directly +- it does not expand the public API +- it does not create cross-module risk + +Estimated merge probability: + +- high, assuming the PR stays small and aligned with existing docs conventions + +## Maintainer Interaction Strategy + +### Who is most likely to matter + +Based on issue and PR review activity observed during research: + +- `eddumelendez` +- `kiview` + +This does not mean directly targeting them personally. It means: + +- write the issue comment in a way that makes review easy for maintainers who already triage this area +- keep scope explicit +- make it obvious that the change is intentionally narrow + +### Best way to approach `#8780` + +Suggested issue comment: + +> I’d like to work on this. +> My plan is to improve the K6 docs by adding a clearer JUnit-style example section based on the existing module test, while keeping the change small and aligned with the current docs/codeinclude style. + +This is strong because: + +- it signals ownership +- it shows you read the existing docs structure +- it reduces reviewer uncertainty + +### Best PR description style for `#8780` + +Suggested PR structure: + +```md +## Summary +Improve the K6 module documentation with a clearer JUnit-style example test. + +## Problem +The current docs show the API usage, but it is still hard to understand the expected test structure quickly. + +## Changes +- add a clearer example section to the K6 docs +- reuse the existing runnable test snippet +- keep the documentation aligned with the current codeinclude style + +## Why +This makes the module easier to adopt for users looking for a quickstart-like testing example. +``` + +## Second PR Recommendation + +### Best first code PR after the docs PR + +Issue: + +- `#8797` `Add getR2dbcUrl helper method to JdbcDatabaseContainer` + +Link: + +- `https://github.com/testcontainers/testcontainers-java/issues/8797` + +Why this is the strongest backend-signaling follow-up: + +- aligns closely with Spring / reactive database usage +- gives a better hiring signal than docs-only work +- maintainers already discussed an acceptable design direction + +Important caution: + +- a previous attempt, PR `#9569`, was closed +- the feature was not rejected +- the attempt appears to have become too broad and got stuck in tests, especially around MSSQL + +Best way to revive it: + +Suggested issue comment: + +> I’d like to revive this using the static `getR2dbcUrl(container)` approach discussed above. +> To keep the scope reviewable, I plan to start with the stable implementations first and include tests for each one, leaving any problematic driver-specific follow-up for a separate PR if needed. +> Does that still match the expected direction? + +Why this approach should improve merge odds: + +- it respects prior maintainer discussion +- it shows you learned from the closed PR +- it reduces fear of a large cross-driver change + ## Suggested PR Positioning ### For `#8780` From 95a2ce76bd48a2bccf50d9f790051bb29dd149e8 Mon Sep 17 00:00:00 2001 From: meyonsoo Date: Tue, 10 Mar 2026 22:34:01 +0900 Subject: [PATCH 3/4] docs: add issue 8797 R2DBC contribution strategy --- .../issue-8797-r2dbc-url-strategy.md | 405 ++++++++++++++++++ 1 file changed, 405 insertions(+) create mode 100644 docs/contributor-research/issue-8797-r2dbc-url-strategy.md diff --git a/docs/contributor-research/issue-8797-r2dbc-url-strategy.md b/docs/contributor-research/issue-8797-r2dbc-url-strategy.md new file mode 100644 index 00000000000..e2ec394d0b2 --- /dev/null +++ b/docs/contributor-research/issue-8797-r2dbc-url-strategy.md @@ -0,0 +1,405 @@ +# Issue #8797 Research: `getR2dbcUrl` Contribution Strategy + +## Summary + +This document records the analysis for Testcontainers Java issue `#8797`: + +- issue: `Add getR2dbcUrl helper method to JdbcDatabaseContainer` +- target repository: `testcontainers/testcontainers-java` +- contribution goal: choose an implementation strategy with a high merge probability + +This note is not just about "can this be coded?". +It is about: + +- what the feature means +- why the issue exists +- what design direction maintainers already accepted +- what failed before +- how to narrow scope to maximize merge probability +- how this can be presented as a strong backend-oriented open source contribution + +## What the issue is really about + +Today, Testcontainers Java already supports R2DBC integration for several databases. +That support is mainly exposed through static methods like: + +- `PostgreSQLR2DBCDatabaseContainer.getOptions(container)` +- `MySQLR2DBCDatabaseContainer.getOptions(container)` +- `MariaDBR2DBCDatabaseContainer.getOptions(container)` +- `MSSQLR2DBCDatabaseContainer.getOptions(container)` + +Those methods return `ConnectionFactoryOptions`, which can then be used to build a connection factory. + +The problem is discoverability and developer ergonomics. + +For many users, especially Spring backend engineers working with reactive stacks, what they often want is not options composition but a concrete R2DBC connection URL string. +Something like: + +- `r2dbc:postgresql://...` +- `r2dbc:mysql://...` +- `r2dbc:mariadb://...` + +The issue exists because users can get a JDBC URL very easily through the container APIs, but there is no equally discoverable helper for the R2DBC URL. + +## Why this matters conceptually + +This is a small feature, but it sits at an important backend developer experience boundary. + +In practice, backend engineers often need: + +- the container lifecycle handled by Testcontainers +- a direct connection string for framework config +- a convenient bridge between container runtime values and application bootstrap + +This is especially relevant in: + +- Spring Boot reactive applications +- Micronaut test resources +- custom integration test setup for R2DBC-based services + +So the core value of the issue is not "adding a string helper". +It is improving the usability and discoverability of R2DBC support in a real backend workflow. + +## Current code structure + +Relevant current implementation paths: + +- `modules/r2dbc/src/main/java/org/testcontainers/r2dbc/R2DBCDatabaseContainer.java` +- `modules/postgresql/src/main/java/org/testcontainers/postgresql/PostgreSQLR2DBCDatabaseContainer.java` +- `modules/mysql/src/main/java/org/testcontainers/mysql/MySQLR2DBCDatabaseContainer.java` +- `modules/mariadb/src/main/java/org/testcontainers/mariadb/MariaDBR2DBCDatabaseContainer.java` +- `modules/mssqlserver/src/main/java/org/testcontainers/mssqlserver/MSSQLR2DBCDatabaseContainer.java` + +There are also legacy compatibility classes under `org.testcontainers.containers` for the same database families: + +- `modules/postgresql/src/main/java/org/testcontainers/containers/PostgreSQLR2DBCDatabaseContainer.java` +- `modules/mysql/src/main/java/org/testcontainers/containers/MySQLR2DBCDatabaseContainer.java` +- `modules/mariadb/src/main/java/org/testcontainers/containers/MariaDBR2DBCDatabaseContainer.java` +- `modules/mssqlserver/src/main/java/org/testcontainers/containers/MSSQLR2DBCDatabaseContainer.java` + +This matters because a contribution here is not only about the modern package paths. +It also needs awareness of compatibility surface and duplicate implementation classes. + +## Root cause of the issue + +The root cause is not that Testcontainers lacks R2DBC support. +It already has that. + +The real root cause is: + +- R2DBC support is exposed through low-level option objects +- URL generation is left to users +- that makes common usage less discoverable +- the API feels less ergonomic than `getJdbcUrl()` + +So the issue is about API discoverability and user ergonomics, not missing protocol support. + +## Maintainer discussion and agreed direction + +The issue discussion is highly valuable because it reduces design ambiguity. + +Important maintainers involved in the discussion include: + +- `eddumelendez` +- `kiview` + +The most important conclusion from the thread is this: + +- maintainers agreed that the safest current design is to add a new static `getR2dbcUrl(container)` method on each `R2DBCDatabaseContainer` implementation + +Example direction discussed by maintainers: + +```java +public static String getR2dbcUrl(MySQLContainer container) { + return ...; +} +``` + +Key point: + +- they did **not** settle on immediately adding a generic method to `JdbcDatabaseContainer` +- they did **not** reject the feature +- they did agree the feature is useful +- the remaining question became implementation scope and testing + +This is extremely important because it means the contribution is not fighting maintainers on product direction. +The contribution can follow a path they already explicitly accepted. + +## What failed before + +There was already a previous PR attempt: + +- PR `#9569` +- title: `Add getR2dbcUrl Method on MariaDB, MySQL, PostgreSQL, MsSQL` + +This is a key learning source. + +What happened: + +- the contributor implemented the feature for several databases +- maintainer requested tests +- contributor then hit MSSQL-specific testing issues +- the PR eventually closed without landing + +This is the main signal for how to approach the issue successfully. + +The feature itself was not rejected. +The previous attempt failed mainly because: + +- the scope was broad +- tests became messy +- MSSQL created friction + +So the lesson is clear: + +- keep the feature narrow +- keep the test matrix simple +- avoid dragging the first PR into MSSQL-specific instability unless really necessary + +## Recommended implementation strategy + +### Best strategy for merge probability + +Do **not** start with a generic `JdbcDatabaseContainer.getR2dbcUrl()`. + +Do: + +- add static `getR2dbcUrl(container)` methods to concrete `R2DBCDatabaseContainer` classes +- keep implementation explicit per database +- avoid trying to invent one universal builder abstraction in the first PR + +### Recommended first scope + +Best first scope: + +- PostgreSQL +- MySQL +- MariaDB + +Do not include MSSQL in the first PR unless there is a very strong reason. + +### Why MSSQL should be deferred + +There are multiple reasons to defer MSSQL: + +1. previous attempt already got stuck there +2. current MSSQL R2DBC implementation contains a database-name-related TODO +3. SQL Server startup and readiness behavior adds review and test complexity +4. a newcomer first PR should avoid known friction when the feature can be landed incrementally + +This does not mean MSSQL should never be supported. +It means MSSQL is a poor choice for the first narrow revival PR. + +## Recommended code shape + +For each selected implementation: + +- keep `getOptions(container)` unchanged +- add `getR2dbcUrl(container)` +- derive the URL using the same effective values already used by `configure(options)` + +The most important design principle is consistency with existing behavior: + +- same host source +- same mapped port source +- same database name source where supported +- same username/password source where appropriate + +The contribution should not try to redesign R2DBC integration. +It should only expose a simpler helper based on the already-existing configuration path. + +## Testing strategy + +Testing is the difference between a plausible PR and a mergeable PR here. + +### Weak testing approach + +Weak approach: + +- only assert that a string equals an expected literal format + +Why weak: + +- it proves only formatting +- it does not prove that the generated URL is actually consumable + +### Strong testing approach + +Preferred approach: + +- generate the URL through `getR2dbcUrl(container)` +- pass it into `ConnectionFactories.get(...)` +- run a real query through the resulting connection + +This aligns with the existing R2DBC test philosophy already present in the repository. + +Relevant test base: + +- `modules/r2dbc/src/testFixtures/java/org/testcontainers/r2dbc/AbstractR2DBCDatabaseContainerTest.java` + +That test fixture already covers: + +- creating a connection factory +- opening a connection +- executing a query +- asserting a successful result + +A strong contribution should reuse this testing style instead of inventing a detached unit-only test. + +## Why this scope should merge better + +The merge-friendly version of this feature has the following characteristics: + +- small scope +- aligned with maintainer comments +- tests included +- no broad API redesign +- no cross-cutting core changes +- no known MSSQL trap in the first pass + +This matches the general maintainer preference pattern seen in other merged contributions: + +- narrowly scoped +- module-focused +- low review burden +- easy to reason about + +## Risk analysis + +### Low-risk parts + +- PostgreSQL +- MySQL +- MariaDB + +These are relatively low risk because: + +- existing R2DBC support already works +- option extraction already exists +- implementation paths are straightforward +- test setup already exists + +### Medium-risk parts + +- adding support to both modern and compatibility package variants + +This is not conceptually hard, but it is easy to overlook. +A PR that updates only one package family may be seen as incomplete. + +### Higher-risk parts + +- MSSQL +- generic interface or abstract-base redesign +- adding behavior in `JdbcDatabaseContainer` + +These raise review load and increase the chance that a small feature turns into an API discussion. + +## Is this a good PR target? + +Yes, but only with the right scope. + +### Good target if: + +- implemented for PostgreSQL/MySQL/MariaDB first +- tests are included +- PR body explicitly references the issue discussion and accepted direction +- feature is framed as discoverability and developer ergonomics + +### Bad target if: + +- implemented across every database at once +- pushed as a generic framework redesign +- submitted without strong tests +- dragged into MSSQL complexity from day one + +So this is a good second PR candidate, but it should be treated as a precision strike, not a broad cleanup. + +## Suggested PR framing + +The PR should be framed around: + +- improving discoverability +- exposing a helper for an already-supported flow +- following the design discussed in `#8797` +- keeping the change intentionally narrow + +Good framing language: + +- users already rely on `getOptions(container)` today +- this adds a more discoverable helper for direct R2DBC URL usage +- the implementation follows the static-method approach discussed in the issue +- the initial scope is limited to the stable and straightforward implementations + +Avoid framing it as: + +- a new R2DBC architecture +- a universal abstraction improvement +- a broad parity project for all drivers in one PR + +## How this helps a backend career story + +This contribution can be presented as a strong backend-oriented OSS signal if the story is told correctly. + +### Why it is good for a backend portfolio + +It shows: + +- reading and respecting existing architecture +- understanding framework integration pain points +- improving developer experience without overengineering +- translating maintainer discussion into an implementation plan +- writing tests for infrastructure-level integration code + +This is more valuable than "I changed a string helper" if explained well. + +### Strong interview narrative + +A good narrative would be: + +- I analyzed an open source issue where reactive database support existed but was not ergonomic enough for real backend usage. +- I studied the maintainers' design discussion and identified why a previous PR attempt stalled. +- I narrowed the feature scope to the highest-confidence implementations to improve merge probability. +- I designed the change to match existing integration behavior rather than introducing a new abstraction. +- I validated the feature at the integration level instead of only asserting string formatting. + +This demonstrates backend maturity: + +- API judgment +- test judgment +- contribution strategy +- practical prioritization under maintainership constraints + +### What to emphasize publicly + +When using this in a resume, interview, or portfolio, the best emphasis is: + +- backend developer ergonomics +- R2DBC / reactive integration support +- open source collaboration through existing maintainer direction +- shipping a narrowly scoped, test-backed improvement + +Do not oversell it as a huge infrastructure rewrite. +Sell it as a thoughtful, well-scoped contribution that improved usability in a real Java backend ecosystem. + +## Recommended next step + +The highest-probability execution path is: + +1. comment on issue `#8797` with a narrow-scope proposal +2. implement `getR2dbcUrl(container)` for PostgreSQL, MySQL, and MariaDB +3. add integration-style tests that prove the generated URLs work +4. leave MSSQL for a follow-up PR if maintainers request it + +## Final recommendation + +Issue `#8797` is worth pursuing. + +But the success condition is not simply "implement the feature". +The success condition is: + +- choose the maintainer-approved shape +- avoid broad API changes +- avoid the MSSQL trap in the first pass +- prove the helper works with real connections + +If done that way, this is a strong and credible second contribution target for a Java / Spring / Kotlin backend engineer building an open source track record in the Testcontainers ecosystem. From 38d7f81b268595d4ad4cd8d003f3d5a1b044a529 Mon Sep 17 00:00:00 2001 From: meyonsoo Date: Wed, 18 Mar 2026 18:56:44 +0900 Subject: [PATCH 4/4] docs: add auth token guidance for LocalStack module Starting March 23, 2026, localstack/localstack:latest requires a LOCALSTACK_AUTH_TOKEN environment variable. Add a warning admonition and usage examples for both auth token and version pinning approaches. Closes #11568 Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/modules/localstack.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/modules/localstack.md b/docs/modules/localstack.md index 72d4fc843a7..f07d85569e5 100644 --- a/docs/modules/localstack.md +++ b/docs/modules/localstack.md @@ -2,6 +2,13 @@ Testcontainers module for [LocalStack](http://localstack.cloud/), 'a fully functional local AWS cloud stack', to develop and test your cloud and serverless apps without actually using the cloud. +!!! warning "Auth Token Required for `localstack/localstack:latest`" + Starting March 23, 2026, `localstack/localstack:latest` requires a + `LOCALSTACK_AUTH_TOKEN` environment variable. To continue without an + auth token, pin to a pre-change version such as `4.14.0`. + See the [LocalStack Auth Token documentation](https://docs.localstack.cloud/getting-started/auth-token/) + for details. + ## Usage example You can start a LocalStack container instance from any Java application by using: @@ -10,6 +17,26 @@ You can start a LocalStack container instance from any Java application by using [Container creation](../../modules/localstack/src/test/java/org/testcontainers/localstack/LocalStackContainerTest.java) inside_block:container +### Using an Auth Token + +For LocalStack versions that require authentication, set your auth token: + +```java +LocalStackContainer localstack = new LocalStackContainer( + DockerImageName.parse("localstack/localstack:latest") +).withEnv("LOCALSTACK_AUTH_TOKEN", System.getenv("LOCALSTACK_AUTH_TOKEN")); +``` + +### Pinning to a Pre-Change Version + +To continue without an auth token, pin to a pre-change version such as `4.14.0`: + +```java +LocalStackContainer localstack = new LocalStackContainer( + DockerImageName.parse("localstack/localstack:4.14.0") +); +``` + ## Creating a client using AWS SDK