Migrate a Testcontainers Guide

You are migrating guides from https://testcontainers.com/guides/ into the Docker docs Hugo site. Each guide lives in its own GitHub repo under testcontainers/tc-guide-*, written in AsciiDoc. The source repos are listed in the testcontainers-site build.sh: https://github.com/testcontainers/testcontainers-site/blob/main/build.sh#L23-L45

Inputs

The user provides one or more guides to migrate. Resolve these from the inventory below:

• REPO_NAME: GitHub repo (e.g. tc-guide-getting-started-with-testcontainers-for-java)
• SLUG: guide slug inside guide/ dir (e.g. getting-started-with-testcontainers-for-java)
• LANG: language identifier (go, java, dotnet, nodejs, python)
• GUIDE_ID: short kebab-case name (e.g. getting-started)

Guide inventory

These are the 21 guides from testcontainers.com/guides/ and their source repos:

Already migrated: #2 (Java getting-started), #13 (Go getting-started), #20 (Python getting-started)

Step 0: Pre-flight

1. Confirm testing-with-docker tag exists in data/tags.yaml. If not, add:

   testing-with-docker:
     title: Testing with Docker

2. Check if new terms need adding to _vale/config/vocabularies/Docker/accept.txt.
3. Read STYLE.md and COMPONENTS.md to refresh on Docker docs conventions.

Step 1: Clone the guide repo

Clone the guide repo to a temporary directory. This gives you all source files locally — no HTTP calls needed.

git clone --depth 1 https://github.com/testcontainers/{REPO_NAME}.git <tmpdir>/{REPO_NAME}

Where <tmpdir> is a temporary directory on your system (e.g. the output of mktemp -d).

The repo structure is:

• <tmpdir>/{REPO_NAME}/guide/{SLUG}/index.adoc — the AsciiDoc guide source
• <tmpdir>/{REPO_NAME}/src/ — application source code (referenced by include:: directives)
• <tmpdir>/{REPO_NAME}/testdata/ — test data files (SQL scripts, configs, etc.)
• <tmpdir>/{REPO_NAME}/pom.xml or go.mod — build config

1. Read guide/{SLUG}/index.adoc to get the guide content.
2. Find all include::{codebase}/path/to/file[] directives. The {codebase} attribute points to a remote URL, but since you have the repo cloned, read the files directly from disk instead (e.g. include::{codebase}/src/main/java/Foo.java[] → read <tmpdir>/{REPO_NAME}/src/main/java/Foo.java).
3. If includes have [lines="X..Y"], extract only those lines from the local file.
4. Note the [source,lang] block preceding each include — that determines the code fence language.

This cloned repo also serves as the base for Step 6 (code verification) — you can run the tests directly in it to confirm they pass before updating the code to the latest API.

Step 2: Convert AsciiDoc to Markdown

Step 3: Apply Docker docs style rules

These are mandatory (from STYLE.md and AGENTS.md):

• No "we": "We are going to create" → "Create" or "Start by creating"
• No "let us" / "let's": → imperative voice or "You can..."
• No hedge words: remove "simply", "easily", "just", "seamlessly"
• No meta-commentary: remove "it's worth noting", "it's important to understand"
• No "allows you to" / "enables you to": → "lets you" or rephrase
• No "click": → "select"
• No bold for emphasis or product names: only bold UI elements
• No time-relative language: remove "currently", "new", "recently", "now"
• No exclamations: remove "Voila!!!" etc.
• Use console language hint for interactive shell blocks with $ prompts
• Use contractions: "it's", "you're", "don't"

Step 4: Update code to latest Testcontainers API

Research the latest API version for the target language before writing code.

Best practices reference: The Testcontainers team maintains Claude skills with up-to-date API patterns and best practices for each language at https://github.com/testcontainers/claude-skills/ — check the relevant language skill (testcontainers-go, testcontainers-node, testcontainers-dotnet) for current API signatures, cleanup patterns, wait strategies, and anti-patterns to avoid.

For each language, check the cloned repo's existing code, then update to the latest API. Key patterns per language:

Go (testcontainers-go v0.41.0):

• postgres.RunContainer(ctx, opts...) → postgres.Run(ctx, "image", opts...)
• testcontainers.WithImage(...) → image is now the 2nd positional param to Run()
• Manual WithWaitStrategy(wait.ForLog(...)) → postgres.BasicWaitStrategies()
• t.Cleanup(func() { ctr.Terminate(ctx) }) → testcontainers.CleanupContainer(t, ctr)
• if err != nil { log.Fatal(err) } → require.NoError(t, err) (use testify require/assert)
• Helper functions should accept t *testing.T as first param, call t.Helper()
• No TearDownSuite() needed if CleanupContainer is registered in the helper
• Go version prerequisite: 1.25+

Java (testcontainers-java 2.0.4):

• Artifacts renamed in 2.x: org.testcontainers:postgresql → org.testcontainers:testcontainers-postgresql
• Check the latest version at https://java.testcontainers.org/
• Use @Testcontainers and @Container annotations for JUnit 5 lifecycle
• Prefer module-specific containers (e.g. PostgreSQLContainer) over GenericContainer
• Use @DynamicPropertySource for Spring Boot integration

.NET (testcontainers-dotnet):

• Check the latest NuGet package version
• Use IAsyncLifetime for container lifecycle in xUnit
• Use builder pattern: new PostgreSqlBuilder().Build()

Node.js (testcontainers-node):

• Check the latest npm version
• Use module-specific packages (e.g. @testcontainers/postgresql)
• Use GenericContainer for services without a dedicated module

Python (testcontainers-python):

• Check the latest PyPI version
• Use context managers (with PostgresContainer() as postgres:)
• Use module-specific containers when available

For all languages: consult the corresponding Testcontainers skill at https://github.com/testcontainers/claude-skills/ for current best practices and anti-patterns.

Step 5: Create guide directory structure

Directory: content/guides/testcontainers-{LANG}-{GUIDE_ID}/

Each guide is its own top-level entry under /guides/. Do NOT nest guides inside a shared parent section — otherwise they won't appear individually in the tag/language filters on the guides listing page.

_index.md (landing page)

---
title: {Full guide title}
linkTitle: {Short title for guides listing}
description: {One-line description}
keywords: testcontainers, {lang}, testing, {technologies used}
summary: |
  {2-3 line summary for the guides listing card}
toc_min: 1
toc_max: 2
tags: [testing-with-docker]
languages: [{lang}]
params:
  time: {estimated} minutes
---

<!-- Source: https://github.com/testcontainers/{REPO_NAME} -->

Content: what you'll learn (bulleted list), prerequisites, and a NOTE linking to https://testcontainers.com/getting-started/ for newcomers.

Sub-pages (chapters)

Split the guide into logical chapters. Each sub-page:

---
title: {Chapter title}
linkTitle: {Short title for stepper}
description: {One-line description}
weight: {10, 20, 30, ...}
---

No tags, languages, or params on sub-pages — only on _index.md.

Typical chapter breakdown:

Adapt the split to the guide's content — some guides may need fewer or more chapters.

Step 6: Verify code compiles and tests pass

This is CRITICAL. The code in the guide MUST compile and all tests MUST pass. Do not skip this step.

6a: Use the cloned repo as the verification project

The repo you cloned in Step 1 (<tmpdir>/{REPO_NAME}) already contains a working project with all source files, build config, and tests. Use it as the starting point:

cd <tmpdir>/{REPO_NAME}

First, verify the original code compiles and tests pass before you change anything. This confirms a good baseline.

6b: Update the code in the cloned repo

After confirming the original works, apply the API updates (from Step 4) directly in the cloned repo's source files. This is the same code you're putting in the guide — keep them in sync.

6c: Update dependencies and compile

Run compilation inside a container for reproducibility — no need to install the language toolchain on the host. Use the appropriate language Docker image, mounting the cloned repo:

docker run --rm -v "<tmpdir>/{REPO_NAME}":/app -w /app <language-image> sh -c "<compile command>"

Pick the right image for the language (e.g. golang:1.25-alpine, maven:3-eclipse-temurin-21, gradle:jdk21, mcr.microsoft.com/dotnet/sdk:9.0, node:22-alpine, python:3.13-alpine). Update dependencies to the latest Testcontainers version and compile.

If compilation fails, fix the code and update the guide markdown to match.

6d: Run tests in a container with Docker socket mounted

Run tests in the same kind of container, but mount the Docker socket so Testcontainers can create sibling containers.

macOS Docker Desktop workarounds

When running on macOS with Docker Desktop, these environment variables and flags are required:

• TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal — On macOS, containers can't reach sibling containers via the Docker bridge IP (172.17.0.x). This tells Testcontainers (including Ryuk) to connect via host.docker.internal instead. Do NOT disable Ryuk — it is a core Testcontainers feature and the guides must demonstrate proper usage.
• docker-java.properties with api.version=1.47 — Docker Desktop's minimum API version is 1.44, but docker-java defaults to 1.24. Create this file in the project root and mount it to /root/.docker-java.properties inside Java containers.
• -Dspotless.check.skip=true — The Spotless Maven plugin in the source repos is incompatible with JDK 21. Skip it since it's a code formatter, not part of the test.
• -Dmicronaut.test.resources.enabled=false — Micronaut's Test Resources service starts a separate process that can't connect to Docker from inside a container. The guide tests use Testcontainers directly, not Test Resources. Only needed for Micronaut guides.

Java guide test command

# Create docker-java.properties in the project root
echo "api.version=1.47" > <tmpdir>/{REPO_NAME}/docker-java.properties

docker run --rm \
  -v "<tmpdir>/{REPO_NAME}":/app \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "<tmpdir>/{REPO_NAME}/docker-java.properties":/root/.docker-java.properties \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal \
  -w /app \
  maven:3.9-eclipse-temurin-21 \
  mvn -B test -Dspotless.check.skip=true -Dspotless.apply.skip=true

For Quarkus guides, use maven:3.9-eclipse-temurin-17 instead (Quarkus 3.22.3 compiles for Java 17).

Go guide test command

docker run --rm \
  -v "<tmpdir>/{REPO_NAME}":/app \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal \
  -w /app \
  golang:1.25-alpine \
  sh -c "apk add --no-cache gcc musl-dev && go test -v -count=1 ./..."

Python guide test command

docker run --rm \
  -v "<tmpdir>/{REPO_NAME}":/app \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal \
  -w /app \
  python:3.13-slim \
  sh -c "pip install -r requirements.txt && python -m pytest"

.NET guide test command

docker run --rm \
  -v "<tmpdir>/{REPO_NAME}":/app \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal \
  -w /app \
  mcr.microsoft.com/dotnet/sdk:9.0 \
  dotnet test

Node.js guide test command

docker run --rm \
  -v "<tmpdir>/{REPO_NAME}":/app \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.docker.internal \
  -w /app \
  node:22-alpine \
  sh -c "npm install && npm test"

Important: run tests sequentially

Run guide tests one at a time. Running multiple concurrent DinD or sibling-container tests can overwhelm Docker Desktop's containerd store and cause meta.db: input/output error corruption, requiring a Docker Desktop restart.

6e: Fix until green

If any test fails, debug and fix the code in both the temporary project AND the guide markdown. Re-run until all tests pass. Do not proceed until verified.

Step 7: Update cross-references

1. content/manuals/testcontainers.md: Add a bullet under the ## Guides section:

   - [Guide title](/guides/testcontainers-{LANG}-{GUIDE_ID}/)

2. Do NOT update content/guides/testcontainers-cloud/_index.md — keep its external links.
3. Link to https://testcontainers.com/getting-started/ for the Testcontainers overview.
4. Use internal paths for already-migrated guides; keep testcontainers.com links for unmigrated ones.

Step 8: Validate

IMPORTANT: Run ALL validation locally before committing. Vale checks run on CI and will block the PR if they fail — fixing after push wastes CI cycles and review time.

1. npx prettier --write content/guides/testcontainers-{LANG}-{GUIDE_ID}/

2. npx prettier --write content/manuals/testcontainers.md

3. docker buildx bake lint — must pass with no errors

4. docker buildx bake vale — then check for errors in the new files:

   grep -A2 "testcontainers-{LANG}-{GUIDE_ID}" tmp/vale.out

   Fix ALL errors before proceeding. Common issues:

   • Vale.Spelling: tech terms (library names, tools) not in the dictionary → add to _vale/config/vocabularies/Docker/accept.txt (alphabetical order)
   • Vale.Terms: wrong casing (e.g. "python" → "Python") → fix in the markdown. Watch for package names like testcontainers-python triggering false positives — rephrase to "Testcontainers for Python" in prose.
   • Docker.Avoid: hedge words like "very", "simply" → reword
   • Docker.We: first-person plural → rewrite to "you" or imperative
   • Info-level suggestions (e.g. "VS Code" → "versus") are not blocking but review them

   Re-run docker buildx bake vale after fixes until no errors remain in the new files.

5. Verify in local dev server (HUGO_PORT=1314 docker compose watch):

   • Guide appears when filtering by its language
   • Guide appears when filtering by Testing with Docker tag
   • Stepper navigation works across chapters
   • All links resolve (no 404s)

6. Verify all external URLs return 200:

   curl -s -o /dev/null -w "%{http_code}" -L "{url}"

Step 9: Commit

One commit per guide. Message format:

feat(guides): add testcontainers {lang} {guide-id} guide

Migrated from https://github.com/testcontainers/{REPO_NAME}
Updated to testcontainers-{lang} v{version} API.

Special cases

• introducing-testcontainers: Language-agnostic, conceptual. May overlap with content/manuals/testcontainers.md. Review for deduplication before migrating.
• local-dev-testcontainers-desktop: About Testcontainers Desktop (now part of Docker Desktop). May need significant rewriting rather than mechanical migration.
• Java guides: Many share the same language. Each still gets its own testcontainers-java-{GUIDE_ID} directory.

Reference: completed migration (Go getting-started)

Use content/guides/testcontainers-go-getting-started/ as the reference implementation:

• _index.md — landing page with frontmatter, prerequisites, learning objectives
• create-project.md (weight: 10) — project setup and business logic
• write-tests.md (weight: 20) — first test with testcontainers-go
• test-suites.md (weight: 30) — container reuse with testify suites
• run-tests.md (weight: 40) — running tests, summary, further reading