Ephemeral Docker Compose Test Environment

Validate that your full application stack actually starts and serves before you merge a pull request. This blueprint orchestrates Docker Compose with Kestra to bring up an ephemeral test environment, run an HTTP smoke test against it, and guarantee teardown afterward, so short-lived CI environments never leak containers or volumes. It solves the classic problem of broken integration environments: instead of trusting that a stack "should" boot, you prove it boots and answers on every PR, with cleanup that runs even when the test fails.

How it works

1. A io.kestra.plugin.core.trigger.Webhook trigger named on_pull_request receives CI calls when a pull request opens, guarded by a secret webhook key.
2. The compose_up task (io.kestra.plugin.docker.Compose) starts the stack in the background with composeArgs set to up -d --wait, so the run blocks until services report healthy.
3. The smoke_test task (io.kestra.plugin.core.http.Request) issues a GET against the smoke_test_url input to confirm the stack serves traffic.
4. The compose_down task tears the stack down with down -v on the happy path, removing containers and named volumes.
5. An errors handler, teardown_on_failure, runs the same down -v when the smoke test or startup fails, so nothing is left running.

Each Compose task uses the io.kestra.plugin.scripts.runner.docker.Docker task runner and mounts /var/run/docker.sock to reach the host engine.

What you get

• A repeatable, ephemeral test environment defined entirely in YAML.
• Health-gated startup via up -d --wait instead of fragile sleeps.
• Guaranteed cleanup (down -v) on both success and failure paths.
• A clear pass or fail signal driven by an HTTP status code.

Who it's for

• Platform and DevOps engineers who run integration checks in CI.
• Backend teams that want stack-level smoke tests on every pull request.
• Anyone replacing brittle bash-in-CI scripts with a declarative flow.

Why orchestrate this with Kestra

Docker Compose can start and stop a stack, but it cannot react to a pull-request event, retry a flaky probe, enforce cleanup when a step fails, or give you execution history and lineage across runs. Kestra adds the event trigger, the error handler that guarantees teardown, declarative YAML you can version, and full observability of every attempt. The webhook trigger and the errors block fill the exact gap Compose's own CLI leaves open: orchestration around the stack, not just the stack itself.

Prerequisites

• A Kestra worker that can reach a Docker daemon (the Compose tasks mount the host socket).
• CI configured to POST to the webhook trigger on pull requests.

Secrets

• COMPOSE_TEST_WEBHOOK_KEY: key that guards the on_pull_request webhook trigger.

Quick start

1. Add the COMPOSE_TEST_WEBHOOK_KEY secret to your Kestra namespace.
2. Replace the inline composeFile with your application's real stack.
3. Point the smoke_test_url input at a health endpoint your stack exposes.
4. Wire your CI to call the webhook URL on pull requests.

How to extend

• Probe multiple endpoints by adding more io.kestra.plugin.core.http.Request tasks.
• Replace the HTTP probe with a containerized integration test suite.
• Post the pass or fail result back to GitHub or Slack via a notification task.
• Add retries to the smoke test to absorb slow cold starts.

Links

• plugin-docker documentation
• Docker orchestration with Kestra