werkdock/docs/testcontainers.md

Testcontainers against Werkdock

Werkdock serves the Docker Engine API subset Testcontainers uses, so a test that asks for a real PostgreSQL gets one — without docker, without podman, without root. Validated with Testcontainers 1.19.3 and 1.21.4 and postgres:16-alpine, on a developer machine and on a Hostsharing managed webspace (RFC 0005 milestones 3 and 4), both programmatically and through jdbc:tc URLs.

Setting it up

werkdock pull postgres:16-alpine     # once; needs the crane binary
werkdock system service &            # listens on $XDG_RUNTIME_DIR/werkdock.sock
export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/werkdock.sock
export TESTCONTAINERS_RYUK_DISABLED=true

That is the whole adaptation: one socket and one environment variable. Ryuk, Testcontainers' cleanup container, wants the API socket bind-mounted into a container of its own and is therefore not supported; --rm, werkdock rm, and Testcontainers' own session cleanup cover the same ground.

A test then reads as it always does:

try (PostgreSQLContainer<?> pg = new PostgreSQLContainer<>("postgres:16-alpine")) {
    pg.start();
    try (Connection c = DriverManager.getConnection(pg.getJdbcUrl(), pg.getUsername(), pg.getPassword())) {
        // pg.getMappedPort(5432) is where the server really listens
    }
}

Or no container code at all: jdbc:tc URLs

Testcontainers can be the JDBC driver itself, which is how most projects use it — the database is then a line of configuration:

spring:
  datasource:
    driver-class-name: org.testcontainers.jdbc.ContainerDatabaseDriver
    url: jdbc:tc:postgresql:16-alpine:///mydb?TC_DAEMON=true&TC_INITSCRIPT=init.sql

This works against werkdock with the same two environment variables and asks for no endpoint the programmatic form does not. Two flags are worth knowing:

• TC_DAEMON=true keeps the container while the JVM lives. Without it Testcontainers stops the database when the last connection closes, and a connection pool closes connections whenever it likes.
• TC_INITSCRIPT names a script on the classpath, which Testcontainers runs over JDBC. No file is copied into the container, so it needs nothing werkdock lacks.

Werkprobe exercises both forms against werkdock in its test suite.

To keep the socket available without starting it by hand, a systemd user unit does it (the managed webspaces have a user manager and lingering enabled):

[Service]
ExecStart=%h/opt/werkdock/bin/werkdock system service
Environment=WERKDOCK_HOME=%h/.werkdock

werkdock system service --time 30m exits when nothing has used it for that long, podman's manner; without --time it runs until stopped.

What is different from docker, and why

Ports are moved, not mapped. The sandbox shares the host's network (RFC 0002), so there is nothing to map a port with. When a client asks for a published port, werkdock picks a free one and tells the service to bind it, through the environment variable the image honours, then reports that port to the client. getMappedPort(5432) therefore returns a real, free port and the JDBC URL works — but the server inside is genuinely listening on that port, not on 5432.

The images werkdock knows how to move, each verified against the real image by starting it and connecting to the port werkdock reported:

Image	How
postgres	PGPORT	environment
mariadb	--port=	flag, on mariadbd
mysql	--port=, --mysqlx-port=	flag, on mysqld
redis	--port	flag, on redis-server
nats	--port	flag, on nats-server
rabbitmq	RABBITMQ_NODE_PORT	environment, capped at 45535
eclipse-mosquitto	—	cannot be moved; keeps 1883

Only postgres reads an environment variable. The other three were listed as doing so until 0.8.0 and did not: the server stayed on its own port while werkdock reported a free one, which is the one failure this whole mechanism exists to prevent. A flag is appended only while the container still runs the image's own program — werkdock does not add arguments to a command a client chose — and where it cannot, the port is reported unmoved.

Any other image keeps its own port, which is correct as long as one instance of it runs at a time. Asking to publish such a port somewhere else fails with the reason rather than reporting a port nothing listens on. Adding an image is one line in quirks (package api) — and, as 0.8.0 showed, an hour with the image itself, because the documentation of what moves a server's port is unreliable.

MySQL keeps one more port than it publishes: the X protocol on 33060. It moves only when a client asks for it, so two instances at once share it and the second one's X plugin fails while its SQL port works.

Two entries are shaped differently from the rest. RabbitMQ derives its Erlang distribution port from the one it is given, by adding 20000, so a node port above 45535 makes it refuse to boot; its quirk caps werkdock's choice, and a requested port above the cap is refused with the reason. Mosquitto cannot be moved at all — its shipped config declares its listeners, and an explicit listener switches off the default one -p would set — so its entry names only the user it needs to start, and its port is reported unmoved. An entry that moves nothing is still worth having: without it mosquitto does not run, and with it werkdock tells the truth about the port.

An image's /run is copied, not shown through. /run is the instance's own directory so that sockets and pid files survive a stop, which means the image's own /run does not show through it as it would on docker. What the image puts there — mariadb's /run/mysqld, say — is therefore copied in when the instance is created.

One user. An unprivileged user namespace maps the caller to exactly one uid, so an entrypoint that starts as root to drop privileges later (the official postgres image and its gosu dance) is started as its target user right away; those entrypoints detect a non-root uid and skip the dance. The same table holds that knowledge.

Refused rather than ignored. A parameter that would change the answer is not quietly dropped: logs?tail=10, timestamps=true, and a since/until other than zero all answer 501 with the reason, because werkdock streams the recorded output whole and records no timestamps beside it.

Everything else answers 501 with the reason. Werkdock implements the traffic a real session sends (docs/testcontainers-api.md), not the whole Engine API. A client that needs more gets a plain explanation, never a 404, and the service log names the endpoint. Known gaps, none of which PostgreSQLContainer needs: networks and docker build.

Copying a file in

withCopyFileToContainer works (0.7.0), so an image's own init mechanism does too:

new PostgreSQLContainer<>("postgres:16-alpine")
    .withCopyFileToContainer(MountableFile.forClasspathResource("init.sql"),
                             "/docker-entrypoint-initdb.d/init.sql")

Underneath it is not docker's copy, because it cannot be: the rootfs in the store is shared by every instance of that image and bound read-only. The tar is unpacked into the instance directory and bound into the sandbox, as high as a bind can sit without hiding anything the image put there: bound whole where the image has nothing, descended into where it has a directory, and the file bound where it has a file. The two trees therefore meet at whatever depth they first differ — MariaDBContainer copies its configuration to /etc/mysql/conf.d and gets one file bound four levels down, with /etc untouched.

One consequence is answered with 501 and the reason rather than done quietly: a copy into a running instance is refused, because a sandbox's mounts are fixed when it starts and there is no writable container layer to put the file in. Copy before start, as withCopyFileToContainer does, or write through a volume.

Inside a build sandbox

The intended use is an integration test inside a werkdock build, which reaches the service by having the socket bound in:

werkdock run --rm -v /repo:/repo -w /repo \
    -v $XDG_RUNTIME_DIR/werkdock.sock:/run/werkdock.sock \
    -e DOCKER_HOST=unix:///run/werkdock.sock \
    -e TESTCONTAINERS_RYUK_DISABLED=true \
    buildenv sh -c './gradlew test'

The database then runs as a sibling of the build sandbox, not inside it, which is exactly how docker-in-docker is done with a mounted socket.

Under Werkator this needs no mount at all. Its werkdock runner already binds a repository's build-environment home into every sandbox as /root, so a socket placed there is reachable as unix:///root/werkdock.sock, and .werkator.yml only has to say so:

builds:
  default:
    werkdock:
      env:
        DOCKER_HOST: "unix:///root/werkdock.sock"
        TESTCONTAINERS_RYUK_DISABLED: "true"

A systemd user unit keeps that socket alive, one per repository whose builds need it. Werkprobe and Werkator itself both run this way.