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.
Connect
Section titled “Connect”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.
chmod 600 /absolute/path/to/bindings.jsonreflow target --group container-tests --collection <collection-id> --bindings /absolute/path/to/bindings.jsonWrite a flow
Section titled “Write a flow”Copy this into /tmp/container-output.md, outside your checkout:
---name: Capture container outputproviders: worker: DockerUbuntu---
### Capture container output
```rflworker.bash command="printf 'container ready\n'" checkpoint="container-output"```Create the test in the team’s chosen location, then run it:
reflow flows create --name container-output --file /tmp/container-output.mdreflow plan container-outputreflow apply container-outputreflow dashboardReplace 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.
Commands and captured files
Section titled “Commands and captured files”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.
Declare the tools the commands need
Section titled “Declare the tools the commands need”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.
Carry helper scripts into the container
Section titled “Carry helper scripts into the container”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 healthproviders: 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
```rflworker.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/tmpis mountednoexec. - 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_FILEStries 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.
Check results and return values
Section titled “Check results and return values”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_idworker.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.
Shell parameter expansion
Section titled “Shell parameter expansion”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.
Evidence and failures
Section titled “Evidence and failures”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.