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"
• 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 — 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 — 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.