werkator/docs/prs/2026-09-11-PR#53-testcontainers-smoke-test-on-the-webspace.md

> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

> Written after the fact: commit `bbb892f` reached main without any pull request, and this file supplies the missing documentation.
> The number 53 belongs to this documentation PR itself (`07785a6`), not to the change it describes.
> The change described here is exactly the one in commit `bbb892f`; nothing was added or reinterpreted.

## The Problem

`TestcontainersSmokeTest` asks whether Testcontainers can start a container on this host.
It skips rather than fails when no engine answers — that is deliberate, and it is what lets Werkator build itself on a Docker-less host.

The trouble is where that skip applied: everywhere that mattered.
Werkator's own build runs on a Hostsharing Managed Webspace, inside a werkdock sandbox, which had no engine to talk to.
So the one test that exists to prove Testcontainers works ran only on machines where nobody doubted it, and stayed silent on the machine where the answer was genuinely unknown.

A test that never runs where the risk is proves nothing.
Since werkdock 0.6.0 serves the Docker Engine API subset Testcontainers uses (RFC 0005 milestone 3), the answer on that host can be a real one.

## Non-Goals

- No change to the skip itself: on a host with no engine at all the test still skips, which is what keeps a Docker-less build green.
- No new sandbox capability. The socket is bound where the werkdock runner already binds this repository's build-environment home; nothing in `WerkdockBuildRunner` changed.
- Not a claim about Testcontainers in general — one container, started and stopped. It is a smoke test, not a conformance suite.

## The Scenarios

### Feature: the smoke test runs where the risk is

#### Background

- `builds.default.werkdock.env` is a build setting a branch may carry; `werkdock.enabled`, `werkdock.rootfs` and `werkdock.binary` are pinned and stripped from a branch layer, so they stay with the host.
- The werkdock runner binds this repository's build-environment home into every sandbox as `/root`.
- The host side is the systemd user unit `werkdock-api-werkator.service` and `alpine:3` in the werkdock image store.

#### Scenario#53.01: On the webspace the test starts a real container

So that a regression in werkdock's Engine API subset is noticed by Werkator's own build, not by a user.

- **Given** Werkator's build running in a werkdock sandbox on the webspace
- **and** a werkdock API socket in this repository's build-environment home
- **When** the build runs its tests
- **Then** `DOCKER_HOST` reaches that socket as `unix:///root/werkdock.sock`
  - **and** the smoke test starts `alpine:3`, asserts it runs, and stops it
  - **and** it is no longer counted as ignored

##### Verified by

- [TestcontainersSmokeTest "Testcontainers starts a container"](../../src/test/kotlin/de/hoennig/werkator/framework/TestcontainersSmokeTest.kt)
- The first build on main after the change: 1 test, 0 ignored, 12.3 s, passed.

#### Scenario#53.02: A host with no engine still skips

So that a Docker-less machine can still build Werkator.

- **Given** a host where `DockerClientFactory.isDockerAvailable()` answers no
- **When** the build runs its tests
- **Then** the smoke test is skipped, not failed

##### Verified by

- [TestcontainersSmokeTest](../../src/test/kotlin/de/hoennig/werkator/framework/TestcontainersSmokeTest.kt) — the `enabledIf` guard is unchanged.

#### Scenario#53.03: Only the build setting is committed

So that a branch cannot reach the host's sandbox policy.

- **Given** the repository's committed `.werkator.yml`
- **When** it is read as a branch layer
- **Then** it carries `werkdock.env` alone
  - **and** `werkdock.enabled`, `werkdock.rootfs` and `werkdock.binary` come from the host, as the pinned set requires

##### Verified by

- [ConfigLoaderTest](../../src/test/kotlin/de/hoennig/werkator/config/ConfigLoaderTest.kt) — the pinning rules this relies on.

## The Solution

Two lines of configuration and a corrected comment.

`.werkator.yml` gives `builds.default` a `werkdock.env` block with `DOCKER_HOST: unix:///root/werkdock.sock` and `TESTCONTAINERS_RYUK_DISABLED: "true"`.
The socket needs no extra mount: the werkdock runner already binds this repository's build-environment home into every sandbox as `/root`.
Ryuk is off because it wants an API socket inside a container of its own, which werkdock does not offer.

The test's own KDoc was the other half of the problem — it claimed the skip existed for the webspace, which is no longer true and would have sent the next reader looking in the wrong place.

`DockerBuildRunnerTest` is unaffected: it mocks the socket locator, and this variable reaches the build sandbox, never the Werkator process.

## Open Questions

- The host side — the systemd user unit and `alpine:3` in the store — is not described by anything in this repository.
  A fresh instance would have a green build here and a skipped test there, with nothing saying why.
  Whether that belongs in `docs/deployment.md` or in `init` is open.

## Additional Changes

- The version goes to **1.8.1** with its release-notes entry, which PR#53 did not bring.
  The rule that every PR carries its own version landed in PR#52, one commit earlier, and `ReleaseVersionConsistencyTest` cannot catch the omission — it compares the version against the top release note, and both still said 1.8.0.
  That gap is PR#52's Open Question; this is it happening.

## Prerequisite PRs

- PR#50 — werkdock's `import` verb and the binary-freshness check, which is how werkdock 0.6.0 reached the host.