dirigent-examples 0.15.0__py3-none-any.whl

dirigent_examples/shelves/docker/docker-compose-database.yaml

@@ -0,0 +1,124 @@
+# A database stack brought up, driven with real SQL, and torn down whatever happened.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev). docs/docker.md is the family's home.
+#
+# Every block here declares local_execution, so the engine refuses them unless the instance
+# allowlists their ids:
+#   dg run --local examples/docker/docker-compose-database.yaml \
+#     --enable-unsafe docker.compose.up,docker.compose.down,docker.run
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up","docker.compose.down","docker.run"]'
+#
+# Three hops, and what each one hands on:
+#   stack     one postgres service, brought up detached and left running for the rest of the
+#             run. Output: every service's container with its state and health, the networks
+#             they sit on, and default_network.
+#   query     a psql container joined to that network, which creates a table, inserts two
+#             rows and selects them back. Output: the exit code and the stdout those selects
+#             printed, which is the step's result a downstream step would read.
+#   teardown  the same project down again, volumes included.
+#
+# WAIT IS WHAT TURNS A HEALTHCHECK INTO A GATE. Postgres accepts connections some seconds
+# after its container starts, and a compose file's healthcheck is only an opinion the daemon
+# records unless something waits on it. wait: true holds the up step open until every service
+# is running and healthy, so the query step meets a database that is ready rather than
+# racing it and failing on connection refused. Without it the stack step returns the moment
+# compose has started the containers.
+#
+# THE NETWORK NAME COMES FROM THE UP STEP. Compose puts the project on a network of its own
+# and the up step reports it as default_network; the query step names that as its network
+# mode, which is what lets it resolve the service by the name the compose file gave it -- db.
+#
+# THE TEARDOWN RUNS ON ANY OUTCOME. rule: all_done means the down step runs whether the query
+# passed or failed, so a database is never left running past the run that started it. Both
+# compose steps default their project name from the run id, so the down addresses exactly the
+# project the up created with nothing wired between them.
+#
+# TO MAKE IT YOURS: put your own schema and queries in the psql argv, or swap postgres for
+# whatever your pipeline actually talks to; the shape -- up with wait, drive, down with
+# all_done -- does not change.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-compose-database
+name: A database stack, queried and torn down
+description: Bring PostgreSQL up behind its healthcheck, run SQL against it, and remove it with its volumes.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.compose.up
+    - docker.compose.down
+    - docker.run
+
+steps:
+  stack:
+    block: docker.compose.up
+    deadline: 10m
+    config:
+      # Hold the step open until pg_isready succeeds, and give up after two minutes rather
+      # than sitting on the step's whole deadline if the image never comes up at all.
+      wait: true
+      wait_timeout: 2m
+      pull: always
+      content: |
+        services:
+          db:
+            image: postgres:17-alpine
+            environment:
+              POSTGRES_USER: dirigent
+              POSTGRES_PASSWORD: dirigent
+              POSTGRES_DB: dirigent
+            healthcheck:
+              test: ["CMD-SHELL", "pg_isready -U dirigent -d dirigent"]
+              interval: 2s
+              timeout: 2s
+              retries: 15
+
+  query:
+    block: docker.run
+    depends_on: [stack]
+    deadline: 5m
+    config:
+      # The postgres image ships psql, so the client needs no image of its own; its
+      # entrypoint execs any command that is not the server itself.
+      image: postgres:17-alpine
+      pull: true
+      # Joining the project's network is what makes "db" a hostname here.
+      network: "${steps.stack.output.default_network}"
+      env:
+        PGPASSWORD: dirigent
+      # argv, not command: no shell is involved, so each statement is one argument however it
+      # is quoted. -A -t strips psql's alignment and headers, leaving rows a later step can
+      # read; ON_ERROR_STOP makes the first failing statement the container's exit code.
+      argv:
+        - psql
+        - -h
+        - db
+        - -U
+        - dirigent
+        - -d
+        - dirigent
+        - -v
+        - ON_ERROR_STOP=1
+        - -A
+        - -t
+        - -c
+        - "create table reading (station text primary key, celsius numeric)"
+        - -c
+        - "insert into reading values ('bergen', 7.1), ('oslo', 4.5)"
+        - -c
+        - "select station, celsius from reading order by station"
+      memory: 256mb
+      pids_limit: 128
+
+  teardown:
+    block: docker.compose.down
+    depends_on: [query]
+    # all_done runs the teardown on success or failure, so the stack outlives neither.
+    rule: all_done
+    deadline: 5m
+    config:
+      # The database's data volume goes with it: a run's stack leaves nothing on the worker.
+      down_volumes: true

dirigent_examples/shelves/docker/docker-compose-failing-up.yaml

@@ -0,0 +1,83 @@
+# A bring-up that fails, and the containers it does not leave behind.
+#
+# THIS PIPELINE FAILS ON PURPOSE. It is here to show what a broken stack looks like from the
+# outside, so the expected outcome is a failed run and an empty daemon.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev). docs/docker.md is the family's home.
+#
+# docker.compose.up declares local_execution, so the engine refuses it unless the instance
+# allowlists its id:
+#   dg run --local examples/docker/docker-compose-failing-up.yaml --enable-unsafe docker.compose.up
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up"]'
+#
+# One hop. The stack has two services: "healthy" comes up and passes its check, and "broken"
+# comes up and never will -- its healthcheck is a command that exits non-zero, so after two
+# retries two seconds apart the daemon marks the container unhealthy. wait: true is waiting on
+# exactly that, so compose gives up and exits non-zero, and the step fails with what compose
+# said on stderr. wait_timeout: 30s is the backstop for a check that hangs rather than fails.
+#
+# WHAT A FAILED BRING-UP LEAVES BEHIND: nothing. This is the one case a block cleans up after
+# itself, because compose has already started containers by the time it decides the stack did
+# not come up. On a non-zero exit -- and equally on a timeout or a cancelled step -- the block
+# runs a down of the same project before it raises, so the half-built project goes with the
+# failure. cleanup: true is the default; it is written out below because it is the point of
+# the example. It never touches a bring-up that SUCCEEDED: that one persists for the run, and
+# a docker.compose.down step is what ends it.
+#
+# HOW TO READ THE FAILURE. The step's error is compose's own last words -- typically
+# "container <project>-broken-1 is unhealthy" -- and the run's step list shows the one step
+# failed with nothing after it. The whole of the CLI's two streams are artifacts of the
+# attempt, and the block logs whether the cleanup worked, so a stack that could not be torn
+# down says so rather than disappearing quietly. Afterwards:
+#   docker ps -a --filter label=com.docker.compose.project
+# lists nothing from this run.
+#
+# TO MAKE IT YOURS: this is the failure mode to reach for when a service of yours is slow
+# rather than broken. Raise retries and interval, or give the service a start_period, before
+# concluding that a stack cannot come up.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-compose-failing-up
+name: A stack that will not come up
+description: A service whose healthcheck never passes, so the bring-up fails and cleans up after itself.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.compose.up
+
+steps:
+  stack:
+    block: docker.compose.up
+    deadline: 5m
+    config:
+      wait: true
+      # Short on purpose: the example should fail in seconds, not sit out a default that was
+      # chosen for stacks meant to work.
+      wait_timeout: 30s
+      timeout: 2m
+      pull: always
+      # Tear the half-built project down before failing the step. This is the default, and
+      # it is what keeps a failed run from orphaning containers.
+      cleanup: true
+      content: |
+        services:
+          healthy:
+            image: alpine:3
+            command: ["sleep", "600"]
+            healthcheck:
+              test: ["CMD-SHELL", "exit 0"]
+              interval: 2s
+              timeout: 2s
+              retries: 2
+          broken:
+            image: alpine:3
+            command: ["sleep", "600"]
+            healthcheck:
+              test: ["CMD-SHELL", "exit 1"]
+              interval: 2s
+              timeout: 2s
+              retries: 2

dirigent_examples/shelves/docker/docker-compose-file.yaml

@@ -0,0 +1,117 @@
+# A compose stack brought up from a FILE on the worker, not from content in the document.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev). docs/docker.md is the family's home.
+#
+# Every block here declares local_execution, so the engine refuses them unless the instance
+# allowlists their ids:
+#   dg run --local examples/docker/docker-compose-file.yaml \
+#     --enable-unsafe docker.compose.up,docker.compose.down,docker.run
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up","docker.compose.down","docker.run"]'
+#
+# Four hops, and what each one hands on:
+#   write     a container writes a compose file into stack/ in the run's work directory.
+#             Output: where each declared file landed.
+#   stack     compose brought up from that path. Output: the services, the networks, and
+#             compose_file -- the path the CLI was actually given.
+#   probe     a container on the stack's network, fetching the service by name.
+#   teardown  the same project down again, on any outcome.
+#
+# WHERE FILES LIVE DURING A RUN. A run has two places. Scratch -- ${run.scratch}, a prefix
+# under the instance's artifact root -- is storage, and is where a result that outlives the
+# run goes. The work directory is this worker's own filesystem, and is where a tool that opens
+# a file reads it from. Compose runs a CLI, so it names a file in the work directory and
+# nowhere else: the path is always relative to it, never absolute, and never climbs out.
+# "stack/docker-compose.yaml" below is the same file the write step wrote there.
+#
+# THE TWO FORMS. docker.compose.up takes exactly one of content or file. Inline content keeps
+# a small stack in the document, and the block writes it into the work directory for the CLI
+# anyway; file is the form for a document an earlier step produced -- generated here, but just
+# as often a storage.copy out of an object store, or a repository checkout. Either way the up
+# step reports compose_file, the path it used, so a later step needing the same document -- a
+# down that has to resolve the project by file rather than by label -- can name it without
+# knowing which form was used.
+#
+# TO MAKE IT YOURS: replace the write step with whatever actually produces your compose file,
+# and leave the rest alone. Note that a compose file with build: stanzas needs its build
+# contexts in the work directory too; v1 targets stacks of pre-built images.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-compose-file
+name: A stack from a compose file on the worker
+description: Write a compose file into the run's work directory, bring the stack up from that path, and tear it down.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.run
+    - docker.compose.up
+    - docker.compose.down
+
+steps:
+  write:
+    block: docker.run
+    deadline: 5m
+    config:
+      image: alpine:3
+      pull: true
+      network: none
+      # Whatever the container leaves in its output mount is copied where the target names
+      # once it exits. A target with no URI scheme is a path in the run's work directory on
+      # this worker, which is where the compose CLI opens its file from; a URI would send the
+      # file to storage instead, for a result that outlives the run.
+      outputs:
+        docker-compose.yaml: "stack/docker-compose.yaml"
+      command: |
+        cat > /dirigent/outputs/docker-compose.yaml <<'COMPOSE'
+        services:
+          web:
+            image: nginx:alpine
+            healthcheck:
+              test: ["CMD-SHELL", "wget -qO- http://localhost/ >/dev/null 2>&1 || exit 1"]
+              interval: 2s
+              timeout: 2s
+              retries: 5
+        COMPOSE
+      memory: 64mb
+      pids_limit: 64
+
+  stack:
+    block: docker.compose.up
+    depends_on: [write]
+    deadline: 10m
+    config:
+      # Relative to the run's work directory, matching what the write step produced. The CLI
+      # is always run with --project-directory set to that directory, so relative paths inside
+      # the compose file resolve against it rather than against this file's directory.
+      file: stack/docker-compose.yaml
+      wait: true
+      wait_timeout: 2m
+      pull: always
+
+  probe:
+    block: docker.run
+    depends_on: [stack]
+    deadline: 5m
+    config:
+      image: alpine:3
+      pull: true
+      # The network the up step reported: joining it resolves "web" to the service.
+      network: "${steps.stack.output.default_network}"
+      argv: [wget, -qO-, "http://web/"]
+      memory: 64mb
+      pids_limit: 64
+
+  teardown:
+    block: docker.compose.down
+    depends_on: [probe]
+    rule: all_done
+    deadline: 5m
+    config:
+      # A project tears down by its label alone, so the file is optional here; passing back
+      # the path the up step reported is how a teardown that does need -f gets it, whichever
+      # form the up step was given.
+      file: "${steps.stack.output.compose_file}"
+      down_volumes: true

dirigent_examples/shelves/docker/docker-compose-profiles-env.yaml

@@ -0,0 +1,133 @@
+# Pipeline parameters reaching into a compose stack: an interpolated variable, and a profile.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev). docs/docker.md is the family's home.
+#
+# Every block here declares local_execution, so the engine refuses them unless the instance
+# allowlists their ids:
+#   dg run --local examples/docker/docker-compose-profiles-env.yaml \
+#     --enable-unsafe docker.compose.up,docker.compose.down,docker.run
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up","docker.compose.down","docker.run"]'
+#
+# Three hops, and what each one hands on:
+#   stack     a two-service stack where one service is optional. Output: the containers the
+#             project actually has, so the profile's effect is visible in the record.
+#   present   a container on the stack's network, fetching the greeting the first service is
+#             serving and asking whether the optional one is there at all. Output: its stdout,
+#             which is the parameter's value followed by a verdict on the profile.
+#   teardown  the same project down again, on any outcome.
+#
+# TWO WAYS A PARAMETER REACHES COMPOSE, and they are not the same mechanism:
+#   env       variables set for the compose CLI process itself, which compose interpolates
+#             into the file it reads. ${params.greeting} is resolved by the engine before the
+#             block sees the config, so the value is a plain string by the time compose runs.
+#   profiles  the --profile flags the CLI is given. A service that declares profiles is left
+#             out of every command that does not activate one of them, so this is how a
+#             pipeline turns an optional service on and off without two compose files.
+#
+# WRITE $${GREETING} FOR COMPOSE, ${...} FOR THE ENGINE. Every ${...} in a document is a
+# reference the engine resolves, and it fails the attempt on a name it does not know, so a
+# variable compose is meant to interpolate is written with the escape: $${GREETING} reaches
+# compose as the literal ${GREETING}, and the engine never looks the name up.
+#
+# project_name is set explicitly here to show the field. It defaults to a name derived from
+# the run id -- shared by the up, the steps that drive it and the down, and unique between
+# runs -- so an explicit one has to keep both those promises itself, which is what ${run.id}
+# does. A fixed string would collide with the next run of the same pipeline.
+#
+# TO MAKE IT YOURS: the parameter names are the only thing specific to this file. Pass
+# -p profile=none to see the same stack come up without its optional service.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-compose-profiles-env
+name: Parameters into a compose stack
+description: A compose stack whose greeting comes from a parameter and whose optional service comes from a profile.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.compose.up
+    - docker.compose.down
+    - docker.run
+
+params:
+  type: object
+  additionalProperties: false
+  properties:
+    greeting:
+      type: string
+      default: hello from a parameter
+      description: Interpolated into the compose file as $${GREETING} and served by the greeter.
+    profile:
+      type: string
+      default: extras
+      description: The compose profile to activate; anything but "extras" leaves the reporter out.
+
+steps:
+  stack:
+    block: docker.compose.up
+    deadline: 10m
+    config:
+      wait: true
+      wait_timeout: 2m
+      pull: always
+      project_name: "dirigent-profiles-${run.id}"
+      # A whole reference resolves to the value itself, so this is a one-element list of the
+      # parameter's string rather than a list containing a template.
+      profiles: ["${params.profile}"]
+      # Set for the CLI process, which is where compose reads interpolation from.
+      env:
+        GREETING: "${params.greeting}"
+      content: |
+        services:
+          greeter:
+            image: nginx:alpine
+            # Compose substitutes GREETING out of the env above before docker sees this, so
+            # the file the daemon runs carries the parameter's value, not the variable. The
+            # greeting is written where nginx serves from, which is how a later step reads it.
+            command:
+              - sh
+              - -c
+              - echo $${GREETING} > /usr/share/nginx/html/index.html && exec nginx -g 'daemon off;'
+            healthcheck:
+              test: ["CMD-SHELL", "wget -qO- http://127.0.0.1/ >/dev/null 2>&1 || exit 1"]
+              interval: 2s
+              timeout: 2s
+              retries: 5
+          reporter:
+            # Declared under a profile, so this service exists only when that profile is
+            # activated. The greeter, declaring none, is always part of the project.
+            profiles: [extras]
+            image: alpine:3
+            command: ["sleep", "600"]
+
+  present:
+    block: docker.run
+    depends_on: [stack]
+    deadline: 5m
+    config:
+      image: alpine:3
+      pull: true
+      network: "${steps.stack.output.default_network}"
+      # The first line proves what compose interpolated; the second proves what the profile
+      # selected, because a name that does not resolve on the project's network is a service
+      # the profile left out.
+      argv:
+        - sh
+        - -c
+        - 'wget -qO- http://greeter/; nslookup reporter >/dev/null 2>&1 && echo "reporter is up" || echo "reporter was left out"'
+      memory: 64mb
+      pids_limit: 64
+
+  teardown:
+    block: docker.compose.down
+    depends_on: [present]
+    rule: all_done
+    deadline: 5m
+    config:
+      # The project name is not defaulted here, so the teardown has to name the same one the
+      # up step built.
+      project_name: "dirigent-profiles-${run.id}"
+      down_volumes: true

dirigent_examples/shelves/docker/docker-compose-stack.yaml

@@ -0,0 +1,70 @@
+# Bringing a compose stack up, driving it, and tearing it down even on failure.
+#
+# REQUIRES A DOCKER DAEMON the worker can reach, named by DOCKER_HOST (a dind sidecar over
+# tcp+TLS, or the local socket in dev). docs/docker.md is the family's home; docs/operations.md
+# says what mounting the host socket grants.
+#
+# docker.compose.up and docker.compose.down declare local_execution, so the engine refuses
+# them unless the instance allowlists their ids:
+#   dg run --local examples/docker/docker-compose-stack.yaml \
+#     --enable-unsafe docker.compose.up,docker.compose.down,docker.run
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up","docker.compose.down","docker.run"]'
+#
+# The lifecycle is the point: up brings the stack up detached and it PERSISTS, so the drive
+# step reaches it; down runs with rule: all_done, so the stack is torn down whether the drive
+# step passed or failed. Both default their project name from the run id, so down finds the
+# stack up created with no wiring.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-compose-stack
+name: A compose stack, driven and torn down
+description: Bring a two-service stack up, reach it from a container, and tear it down on any outcome.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.compose.up
+    - docker.compose.down
+    - docker.run
+
+steps:
+  stack:
+    block: docker.compose.up
+    deadline: 5m
+    config:
+      # wait: true holds the step open until every service is healthy, so the drive step
+      # never races the stack coming up. pull: always fetches the images on a fresh worker.
+      wait: true
+      pull: always
+      content: |
+        services:
+          api:
+            image: nginx:alpine
+            healthcheck:
+              test: ["CMD-SHELL", "wget -qO- http://localhost/ >/dev/null 2>&1 || exit 1"]
+              interval: 2s
+              timeout: 2s
+              retries: 5
+
+  drive:
+    block: docker.run
+    depends_on: [stack]
+    deadline: 2m
+    config:
+      image: alpine:3
+      pull: true
+      # The network the up step reported: joining it is how this container resolves and
+      # reaches the "api" service by name.
+      network: "${steps.stack.output.default_network}"
+      command: wget -qO- http://api/
+
+  teardown:
+    block: docker.compose.down
+    depends_on: [drive]
+    # all_done runs the teardown on success or failure, so a stack is never left running.
+    rule: all_done
+    deadline: 2m
+    config:
+      down_volumes: true

dirigent_examples/shelves/docker/docker-hello.yaml

@@ -0,0 +1,53 @@
+# Running a container as a step, and what that costs in trust.
+#
+# REQUIRES A DOCKER SOCKET: a Docker daemon the worker can reach, at /var/run/docker.sock
+# or wherever DOCKER_HOST points. Without one the document still validates and applies; it
+# fails at the step, saying the daemon could not be reached.
+#
+# docker.run declares local_execution, so the engine refuses it unless the instance
+# allowlists the id. Reaching the Docker socket is reaching root on the host:
+#   dg run --local examples/docker/docker-hello.yaml --enable-unsafe docker.run
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.run"]'   # for the instance
+#
+# The block is asynchronous: execute creates the container and starts it detached, and the
+# engine probes it. A container that runs for an hour costs one parked row, not an hour of
+# a worker, and the deadline stays on the step.
+#
+# network: none is the default: an image a document named does not reach the worker's
+# network unless the step says so. pull: true fetches the image first, so this runs on a
+# machine that has never seen alpine.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-hello
+name: Hello from a container
+description: Run a command in a container, with no network and the image pulled first.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.run
+
+params:
+  type: object
+  additionalProperties: false
+  properties:
+    message:
+      type: string
+      default: hello from a container
+      description: What the container echoes.
+
+steps:
+  greet:
+    block: docker.run
+    deadline: 5m
+    config:
+      image: alpine:3
+      pull: true
+      # A container that needs nothing from the network is given none, and the memory and
+      # process caps bound what a runaway image can take from the worker it landed on.
+      network: none
+      argv: [echo, "${params.message}"]
+      memory: 64mb
+      pids_limit: 64

dirigent_examples/shelves/docker/docker-remote-daemon.yaml

@@ -0,0 +1,92 @@
+# Naming the daemon: the same compose stack, run on a daemon a connection points at.
+#
+# The compose lifecycle example (docker-compose-stack.yaml) uses whatever daemon the worker's
+# own environment names. This one names it in the document instead, through a `docker`
+# connection the instance holds, and that connection carries the client TLS the daemon
+# demands.
+#
+# REQUIRES A DOCKER CONNECTION the instance already holds. Create it once, with the client
+# half of the daemon's certificates -- a dind sidecar writes them to DOCKER_TLS_CERTDIR/client:
+#   dg connection create docker build-daemon \
+#     --set host=tcp://docker:2376 \
+#     --set "tls_ca=$(cat /certs/client/ca.pem)" \
+#     --set "tls_cert=$(cat /certs/client/cert.pem)" \
+#     --set "tls_key=$(cat /certs/client/key.pem)"
+#
+# The three blocks declare local_execution, so the engine refuses them unless the instance
+# allowlists their ids:
+#   export DIRIGENT_ENABLED_UNSAFE_BLOCKS='["docker.compose.up","docker.compose.down","docker.run"]'
+#
+# EVERY STEP NAMES THE SAME CONNECTION, and that is the whole discipline here. A stack exists
+# only on the daemon that was told to create it, so an `up` on one daemon and a `down` on
+# another tear down nothing: the second daemon has no such project. The drive step is in it
+# too, because it joins a network the first daemon owns.
+#
+# tls_key is sealed: encrypted at rest, redacted in every API response, and reaching the CLI
+# only as a 0600 file under the run's work directory that goes when the step leaves. A client
+# key for a docker daemon is a credential for root on whatever that daemon runs on.
+#
+# TO MAKE IT YOURS: point host at your own daemon. A daemon that needs no TLS -- an ssh://
+# host, or a unix socket on another path -- takes host alone and none of the three PEMs.
+
+format: dirigent/v1
+kind: pipeline
+code: docker-remote-daemon
+name: A compose stack on a named daemon
+description: Bring a stack up, drive it and tear it down on the daemon a docker connection names.
+
+tags: [docker, execute]
+
+requires:
+  blocks:
+    - docker.compose.up
+    - docker.compose.down
+    - docker.run
+  workers:
+    # The compose file and its build contexts are on the worker's own filesystem, so all three
+    # steps have to meet one docker-capable worker even though the daemon is named here.
+    - docker
+  connections:
+    # Named, not carried: the instance holds the connection and its sealed TLS key, and this
+    # document refuses to apply where it is absent rather than failing the first time it runs.
+    - build-daemon
+
+steps:
+  stack:
+    block: docker.compose.up
+    deadline: 5m
+    config:
+      connection: build-daemon
+      wait: true
+      pull: always
+      content: |
+        services:
+          api:
+            image: nginx:alpine
+            healthcheck:
+              test: ["CMD-SHELL", "wget -qO- http://localhost/ >/dev/null 2>&1 || exit 1"]
+              interval: 2s
+              timeout: 2s
+              retries: 5
+
+  drive:
+    block: docker.run
+    depends_on: [stack]
+    deadline: 2m
+    config:
+      connection: build-daemon
+      image: alpine:3
+      pull: true
+      # The network the up step reported, which exists on that daemon and nowhere else.
+      network: "${steps.stack.output.default_network}"
+      command: wget -qO- http://api/
+
+  teardown:
+    block: docker.compose.down
+    depends_on: [drive]
+    # all_done runs the teardown on success or failure, so a stack is never left running.
+    rule: all_done
+    deadline: 2m
+    config:
+      connection: build-daemon
+      down_volumes: true