docker.compose

Docker Compose orchestration: bring stacks up/down, register containers as live hosts in the active Lab, and idempotently re-enter when the same stack is already running.

The public surface (re-exported from otto.docker) is:

otto.docker.compose.get_user_compose_project(repo_name, suffix=None)

Return a compose project name unique enough to coexist with other runs.

Format: otto-<repo>-<suffix>. suffix defaults to the OS username, or OTTO_COMPOSE_SUFFIX if set in the environment. Lowercase only — compose project names must be lowercase.

Return type:

str

async otto.docker.compose.compose_up(repo, lab, *, on=None, project_name=None, build=True)

Bring up repo’s compose stack on a parent host.

Idempotent at the project-name level: if a stack with the same project_name is already running on parent, this becomes a lookup instead of a fresh up. Either way, returns a dict mapping each declared service to its DockerContainerHost, with the hosts also registered in lab.hosts so --list-hosts and otto host <id> see them.

Parameters:

build – When True (the default) and the repo declares [[docker.images]], run build_images() first so locally- built images exist on the parent before compose tries to pull them. The build is idempotent via the context-hash skip, so this is cheap when nothing changed. Pass build=False if the compose file references only published images (or if you already built explicitly).

Return type:

dict[str, DockerContainerHost]

async otto.docker.compose.compose_down(repo, lab, *, on=None, project_name=None, stop_timeout=1)

Tear down repo’s compose stack and unregister its container hosts.

stop_timeout is the per-container graceful-shutdown grace period in seconds passed to docker compose down --timeout. Defaults to 1s rather than docker’s default of 10s — otto’s typical workload is integration tests with disposable stacks where waiting 10s on every teardown adds up fast (4 tests × 10s = 40s of wall time on the serialized docker_e2e group). Pass a larger value for stacks where graceful shutdown matters.

Return type:

Status

otto.docker.compose.composed(repo, lab, *, on=None, project_name=None, own=False, build=True)

Context manager wrapping compose_up / compose_down.

By default the stack is not torn down on exit if it was already running on entry — this lets a suite-level fixture hold the stack while inner instructions also call composed without yanking it from each other. Pass own=True to force teardown.

build is forwarded to compose_up().

Return type:

AsyncIterator[dict[str, DockerContainerHost]]

async otto.docker.compose.compose_ps(parent)

Return a list of dicts describing running containers on parent.

Uses docker ps --format '{{json .}}' so the output is structured.

Return type:

list[dict[str, Any]]

otto.docker.compose.register_declared_container_hosts(lab, repos)

Pre-register placeholder container hosts in lab for every declared <parent>.<project>.<service>.

The placeholders carry an empty container_id so that any operation against a not-yet-up container fails with a clear “run otto docker up” message rather than a confusing not-found error. Once compose_up() runs, it overwrites the placeholder with a real entry containing the resolved container id.

Returns the number of placeholders registered.

Return type:

int

otto.docker.compose.get_container_host(host_id)

Look up a registered container host by id. Raises if not present.

Return type:

DockerContainerHost