Merge branch 'main' into ubuntu-24.04

Author: cristianrgreco

.devcontainer/devcontainer.json

@@ -7,7 +7,7 @@
 
   // Features to add to the dev container. More info: https://containers.dev/features.
   "features": {
-    "ghcr.io/devcontainers/features/node:1": {
+    "ghcr.io/devcontainers/features/node:2": {
       "version": "24"
     },
     "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}

.github/workflows/checks.yml

@@ -107,7 +107,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
     runs-on: ubuntu-24.04
     steps:
       - name: Code checkout
@@ -143,7 +143,7 @@ jobs:
       fail-fast: false
       matrix:
         module: ${{ fromJSON(needs.detect-modules.outputs.modules) }}
-        node-version: [20.x, 22.x, 24.x]
+        node-version: [22.x, 24.x]
         container-runtime: [docker, podman]
     uses: ./.github/workflows/test-template.yml
     with:

.github/workflows/close-inactive-issues.yml

@@ -16,6 +16,7 @@ jobs:
           days-before-issue-stale: 90
           days-before-issue-close: 30
           stale-issue-label: "stale"
+          exempt-issue-labels: "never-stale"
           stale-issue-message: "This issue is stale because it has been open for 90 days with no activity."
           close-issue-message: "This issue was closed because it has been inactive for 30 days since being marked as stale."
           days-before-pr-stale: -1

.github/workflows/test-template.yml

@@ -54,6 +54,6 @@ jobs:
           workspace: "${{ inputs.workspace }}"
 
       - name: Run tests
-        run: npm run test:ci -- --coverage.include=${{ steps.npm-install.outputs.workspace_path }} ${{ steps.npm-install.outputs.workspace_path }}
+        run: npm run test:ci -- --coverage.include="${{ steps.npm-install.outputs.workspace_path }}/**/*.ts" ${{ steps.npm-install.outputs.workspace_path }}
         env:
           CI: true

AGENTS.md

@@ -5,11 +5,27 @@
 This is a working guide for contributors and coding agents in this repository.
 It captures practical rules that prevent avoidable CI and PR churn.
 
+## Instruction precedence
+
+- Repository-specific instructions in this file override generic coding-agent defaults, skills, and templates.
+- If a generic workflow conflicts with this file, follow this file.
+
+## Repository Layout
+
+- This repository is an npm workspaces monorepo.
+  - root package: `testcontainers-monorepo`
+  - workspaces: `packages/testcontainers` and `packages/modules/*`
+  - shared lockfile: root `package-lock.json` (workspace installs update this single file)
+- For workspace-scoped dependency changes, prefer targeted commands to reduce lockfile churn:
+  - `npm install -w @testcontainers/<module>`
+  - `npm uninstall -w @testcontainers/<module> <package>`
+
 ## Development Expectations
 
 - If a public API changes, update the relevant docs in the same PR.
 - If new types are made part of the public API, export them from the package's `index.ts` in the same PR.
 - If new learnings or misunderstandings are discovered, propose an `AGENTS.md` update in the same PR.
+- In docs Markdown, keep `<!--codeinclude-->` blocks tight with no blank lines between the markers and the include line, or the rendered snippet will contain blank lines between code lines.
 - Tests should verify observable behavior changes, not only internal/config state.
   - Example: for a security option, assert a real secure/insecure behavior difference.
 - Test-only helper files under `src` (for example `*-test-utils.ts`) must be explicitly excluded from package `tsconfig.build.json` so they are not emitted into `build` and accidentally published.
@@ -21,7 +37,7 @@ It captures practical rules that prevent avoidable CI and PR churn.
 ## Permission and Escalation
 
 - `npm install` requires escalated permissions for outbound network access to npm registries.
-- `npm test` commands should b`e run with escalation so tests can access the Docker socket.
+- `npm test` commands should be run with escalation so tests can access the Docker socket.
 
 ### Escalation hygiene
 
@@ -40,7 +56,9 @@ It captures practical rules that prevent avoidable CI and PR churn.
    - Never bypass signing (for example, do not use `--no-gpg-sign`).
    - If signing fails (for example, passphrase/key issues), stop and ask the user to resolve signing, then retry.
 8. Push branch. Ask for explicit user permission before any force push.
-9. Open PR against `main` using a human-readable title (no `feat(...)` / `fix(...)` prefixes).
+9. Open PR against `main` using a human-readable title (no `feat(...)` / `fix(...)` prefixes, and no agent-identifying prefixes or suffixes).
+   - Default to a ready-for-review PR. Only open or keep a PR in draft when the user explicitly asks for a draft.
+   - When using `gh` to create/edit PR descriptions, prefer `--body-file <path>` over inline `--body`; this avoids shell command substitution issues when the body contains backticks.
 10. Add labels for both change type and semantic version impact.
 11. Ensure PR body includes:
     - summary of changes
@@ -73,6 +91,6 @@ It captures practical rules that prevent avoidable CI and PR churn.
 - docs-only change: `documentation` + usually `patch`
 - dependency update: `dependencies` + impact label based on user-facing effect
 
-## Practical Note
+## Lockfile Hygiene
 
 - Recheck `package-lock.json` after `npm install` for unrelated drift and revert unrelated changes.

CONTRIBUTING.md

@@ -31,7 +31,7 @@ Then access the docs at [http://localhost:8000](http://localhost:8000).
 
 #### Using Python
 
-* Ensure that you have Python 3.8.0 or higher.
+* Ensure that you have Python 3.11.0 or higher.
 * Set up a virtualenv and run `pip install -r requirements.txt` in the `testcontainers-node` root directory.
 * Once Python dependencies have been installed, run `mkdocs serve` to start a local auto-updating MkDocs server.
 

docs/features/compose.md

@@ -144,6 +144,19 @@ const environment = await new DockerComposeEnvironment(composeFilePath, composeF
   .up();
 ```
 
+### With auto cleanup disabled
+
+By default Testcontainers registers the compose project with Ryuk so the stack is torn down automatically when the process exits. You can disable that registration for a specific compose stack:
+
+```js
+const environment = await new DockerComposeEnvironment(composeFilePath, composeFile)
+  .withProjectName("test")
+  .withAutoCleanup(false)
+  .up();
+```
+
+This only disables automatic cleanup. Explicit calls to `.down()`, `.stop()`, or `await using` disposal still tear the stack down as usual.
+
 ### With custom client options
 
 See [docker-compose](https://github.com/PDMLab/docker-compose/) library.

docs/features/containers.md

@@ -400,6 +400,16 @@ const container = await new GenericContainer("alpine")
 await container.stop({ remove: true }); // The container is stopped *AND* removed
 ```
 
+You can also disable automatic Ryuk cleanup for a specific container while leaving it enabled for the rest of the test session:
+
+```js
+const container = await new GenericContainer("alpine")
+  .withAutoCleanup(false)
+  .start();
+```
+
+This only affects automatic cleanup when the process exits unexpectedly or the container is otherwise left running. Explicit calls to `.stop()` still use the normal stop and removal behavior, so combine this with `.withAutoRemove(false)` or `.stop({ remove: false })` if you also want explicit stops to keep the container.
+
 Keep in mind that disabling ryuk (set `TESTCONTAINERS_RYUK_DISABLED` to `true`) **and** disabling automatic removal of containers will make containers persist after you're done working with them.
 
 

docs/modules/localstack.md

@@ -16,9 +16,27 @@ These examples use the following libraries:
 
 Choose an image from the [container registry](https://hub.docker.com/r/localstack/localstack) and substitute `IMAGE`.
 
+!!! note "Authentication requirements"
+    Starting on March 23, 2026, LocalStack moved to authenticated image releases. Older pinned tags may continue to work without `LOCALSTACK_AUTH_TOKEN`, but newer releases require it.
+
+    Prefer pinning a specific image tag instead of using `latest`. If the image tag you use requires authentication, pass `LOCALSTACK_AUTH_TOKEN` when starting the container:
+
+    ```typescript
+    const token = process.env.LOCALSTACK_AUTH_TOKEN;
+
+    if (!token) {
+      throw new Error("LOCALSTACK_AUTH_TOKEN must be set for authenticated LocalStack images");
+    }
+
+    const container = await new LocalstackContainer("localstack/localstack:IMAGE")
+      .withEnvironment({ LOCALSTACK_AUTH_TOKEN: token })
+      .start();
+    ```
+
+    Refer to the [LocalStack announcement](https://blog.localstack.cloud/localstack-single-image-next-steps/) for the current rollout details.
+
 ### Create a S3 bucket
 
 <!--codeinclude-->
 [](../../packages/modules/localstack/src/localstack-container.test.ts) inside_block:localstackCreateS3Bucket
 <!--/codeinclude-->
- 

docs/modules/oraclefree.md

@@ -0,0 +1,23 @@
+# Oracle Free
+
+## Install
+
+```bash
+npm install @testcontainers/oraclefree --save-dev
+```
+
+## Examples
+
+These examples use the following libraries:
+
+- [oracledb](https://www.npmjs.com/package/oracledb)
+
+        npm install oracledb
+
+Recommended to use an image from [this registry](https://hub.docker.com/r/gvenzl/oracle-free) and substitute for `IMAGE`
+
+### Start a database and execute queries
+
+<!--codeinclude-->
+[](../../packages/modules/oraclefree/src/oraclefree-container.test.ts) inside_block:customDatabase
+<!--/codeinclude-->