Skip to content

DockerUbuntu plugin

Use DockerUbuntu when the application command needs an Ubuntu environment in Docker. It runs against a container you already started. Use LocalBash when the command belongs on your host machine.

Select your application collection during onboarding. Use its ID in the target command below.

Install the bundled plugin with reflow init --collection <collection-id>. Docker must be available and running, and the selected container must already be running Ubuntu with Bash, timeout, setsid, ps, sleep, realpath, head, mkdir and rm installed and a writable /tmp. Your application and its dependencies must be available in that container.

The plugin does not create containers, pull images, change mounts or networks, or stop the selected container. It keeps its own working directories under /tmp in the container. This is local Docker execution, separate from hosted container infrastructure.

Save a private bindings.json, replacing the container name and working directory:

{
"worker": {
"provider": "DockerUbuntu",
"configuration": {"container": "my-test-container", "cwd": "/workspace/app"}
}
}

Both container and the absolute container cwd are required. The plugin talks to Docker Engine directly, without the Docker CLI. Optional endpoint selects the Engine’s Unix socket or HTTPS origin; it defaults to unix:///var/run/docker.sock. Keep the bindings file out of Git.

Terminal window
chmod 600 /absolute/path/to/bindings.json
reflow target --group container-tests --collection <collection-id> --bindings /absolute/path/to/bindings.json

Copy this into /tmp/container-output.md, outside your checkout:

---
name: Capture container output
providers:
worker: DockerUbuntu
---
### Capture container output
```rfl
worker.bash command="printf 'container ready\n'" checkpoint="container-output"
```

Create the test in the team’s chosen location, then run it:

Terminal window
reflow flows create --name container-output --file /tmp/container-output.md
reflow plan container-output
reflow apply container-output
reflow dashboard

Replace the example command with your application’s test or worker command. The alias worker selects the private connection with the same name. Its working directory is inside the container; the host checkout is separate.

worker.bash takes a required command string and optional files string containing a JSON array of relative paths. These are the same arguments as LocalBash. checkpoint names the retained result.

worker.bash command="./bin/check-orders --report report.txt" files="[\"report.txt\"]" checkpoint="order-report"

This example assumes your container contains the application’s ./bin/check-orders, which writes its report to the path given with --report. Keep logic out of the command string: run the application’s executable or a script, and pass paths as arguments. Files are read from the container after the command. They must remain inside the configured directory, and each is limited to 4 MiB.

requires: in the frontmatter lists, per alias, the programs the commands run; for a DockerUbuntu alias they are looked up inside the container, on the container’s PATH as its commands would find them, when the first step that acts starts. Build them into the image or install them before the flow starts; a step’s install cannot satisfy the check:

requires:
worker: [python3, jq>=1.6]

A missing or older tool fails the flow before anything runs, naming every one ([tool_unavailable]). Reflow never installs anything in the container. See the language guide.

A flow’s carried files (file="…" blocks) reach the container too. Before its first command, the plugin copies exactly the files the flow declares into a private directory under /tmp in the container, and every command finds it under REFLOW_FLOW_FILES, as in LocalBash, so the same step runs in either:

---
name: Container health
providers:
worker: DockerUbuntu
---
```bash file="health.sh"
# Prints the worker's health as one JSON object.
set -euo pipefail
./bin/worker health --json
```
### Check the worker's health
```rfl
worker.bash (
command="bash \"$REFLOW_FLOW_FILES/health.sh\""
expect=json(
{"json": [{"pointer": "/status", "equals": "ok"}]}
)
checkpoint="worker-health"
)
```
  • Run a carried script with bash "$REFLOW_FLOW_FILES/<path>": this also works when /tmp is mounted noexec.
  • The files are read-only. Commands still run in the binding’s cwd.
  • A flow that declares no files copies nothing. If the files cannot be copied, for example into a read-only container, a command that mentions REFLOW_FLOW_FILES tries again and fails before it runs if the copy still fails; any other command runs with the variable unset, never with a value the container defines.
  • Retained output and failure messages show the container directory as $REFLOW_FLOW_FILES, so results stay comparable between runs. Checks and returned values use the command’s own output.

REFLOW_STEP_FILES names a new, empty private directory in the container for each command, for files the command writes and its own stepFiles checks read. Unlike LocalBash’s, it does not keep files for a later command of the same step: keep that work inside one script. In a container whose /tmp is read-only, a command that mentions REFLOW_STEP_FILES or checks stepFiles fails before it runs, with “no writable scratch in this container”; other commands run as usual.

The plugin removes its directories when the run ends, on a best-effort basis; a run that is stopped abruptly can leave them in the container’s /tmp.

worker.bash accepts the same expect as LocalBash: exit status, text in stdout or stderr, JSON Pointer checks with exact numeric comparisons, and files in $REFLOW_STEP_FILES. An unmet expectation fails the step with what was expected and what was received. Exit statuses 124, 125 and 137 are the plugin’s own deadline and supervision, so like 126 and 127 they mean the command could not run, unless exit names them. worker.bash_value returns one value from the command’s JSON stdout for -> name, as in LocalBash, and pass it on as an argument of a carried script:

worker.bash_value command="./bin/worker enqueue --json" select="/jobId" -> job_id
worker.bash (
command="bash \"$REFLOW_FLOW_FILES/wait-job.sh\" ${job_id}"
expect=json(
{"exit": 0, "stdoutIncludes": "done"}
)
)

As in LocalBash, a bash call with expect can decide an if or unless, and cannot wait with within=; see branch on a command. LocalBash’s file is not available in containers yet.

Write $${ for a literal ${ in the quoted command string: author $${VAR:-default}, $${PIPESTATUS[0]} or $${#arr[@]}, and Bash in the container receives ${VAR:-default}, ${PIPESTATUS[0]} or ${#arr[@]} respectively. RFL references such as ${inputs.name} still resolve normally. This is the same interpolation escape as LocalBash; JSON string escaping and shell quoting still apply.

Each invocation retains stdout, stderr, exit code and selected files. A nonzero exit, unless expect names it, fails the command and keeps its output. Compare retained results across runs; there is no extra terminal screenshot command.

Shared shell evidence redacts known private values from text and withholds affected binary files. Files in the container remain unchanged.

An unavailable Docker daemon, stopped container, missing working directory or missing required executable prevents execution. Reflow manages the command’s process group while leaving the selected container running. If completion is unknown, reconcile it before retrying; see repair and rerun.

Flows using this plugin can be saved in Reflow or in your repository. Read test storage for the team preference, private bindings and the shared plan/apply workflow.