What is a per-project Docker Compose setup for Nx e2e tests?
In this pattern, every e2e project owns a docker-compose.e2e.yml that sits next to its project.json. That file declares only the backend services the project's tests talk to, such as a Postgres instance for api-e2e or a Redis queue for worker-e2e. Nx then exposes the file as ordinary targets, deps-up and deps-down, and the e2e target declares deps-up in its dependsOn. The database stops being something a developer has to remember to start. It becomes an edge in the project graph that Nx resolves before any test runs.
A single repo-wide Compose file is simpler to set up, but it starts every service for every test run. It also gives no hint about which project depends on what. When the files are scoped per project, nx affected -t e2e brings up only the containers for the projects that actually changed. A change to the worker does not start the API's database.
api-e2e worker-e2e
e2e ──dependsOn──▶ deps-up e2e ──dependsOn──▶ deps-up
│ │
Compose project: api-e2e Compose project: worker-e2e
network: api-e2e_default network: worker-e2e_default
postgres host:55432 redis host:56379
The pattern suits backend and platform engineers who run integration tests in Nx monorepos against real databases and queues rather than mocks. It removes three common problems:
- Hidden dependencies. Tests pass only because something happened to be running locally.
- Shared state. Two suites write to the same database and interfere with each other.
- Manual startup steps. Setup instructions live in a README instead of in the graph, so they drift out of date.
nx affected -t e2e
│
┌──────────────────┴──────────────────┐
▼ ▼
┌──────────────────────────────────┐ ┌──────────────────────────────────┐
│ api-e2e/project.json │ │ worker-e2e/project.json │
│ │ │ │
│ ┌─────┐ dependsOn ┌─────────┐ │ │ ┌─────┐ dependsOn ┌─────────┐ │
│ │ e2e │──────────▶│ deps-up │ │ │ │ e2e │──────────▶│ deps-up │ │
│ └─────┘ └────┬────┘ │ │ └─────┘ └────┬────┘ │
│ │ │ │ │ │
│ docker-compose.e2e.yml ▼ │ │ docker-compose.e2e.yml ▼ │
│ ┌────────────────────────────┐ │ │ ┌────────────────────────────┐ │
│ │ Compose project: api-e2e │ │ │ │ Compose project: worker-e2e│ │
│ │ network: api-e2e_default │ │ │ │ network: worker-e2e_default│ │
│ │ ┌────────────────────────┐ │ │ │ │ ┌────────────────────────┐ │ │
│ │ │ postgres │ │ │ │ │ │ redis │ │ │
│ │ │ host:55432 │ │ │ │ │ │ host:56379 │ │ │
│ │ └────────────────────────┘ │ │ │ │ └────────────────────────┘ │ │
│ └────────────────────────────┘ │ │ └────────────────────────────┘ │
└──────────────────────────────────┘ └──────────────────────────────────┘
Each e2e project owns a docker-compose.e2e.yml and its e2e target depends on deps-up, so each project gets its own Compose project, network and host port, and nx affected starts only the dependencies of the projects that changed.
How does Nx drive Docker Compose with deps-up and deps-down targets?
Moving those steps into the graph starts with two targets on the e2e project, both using the nx:run-commands executor. deps-up runs docker compose -f docker-compose.e2e.yml -p <name> up -d --wait, and deps-down runs the same file and project name with down -v. The -p flag sets the Compose project name, which scopes container, network, and volume names. Hardcode it per Nx project for now; section 4 makes it unique per run. The -v flag on down removes the named volumes declared in the file, so the next run starts from an empty database instead of inheriting the last suite's rows.
On the e2e target, add deps-up to dependsOn. Running nx e2e orders-api-e2e now brings the stack up first, and nobody has to remember a manual step.
The --wait flag is what makes this ordering useful. Without it, up -d returns as soon as containers are created, and the test runner races the database's startup. With --wait, Compose blocks until each service reports healthy and exits non-zero if one becomes unhealthy, which also fails the Nx target. There is a catch: a service with no healthcheck counts as ready once its container is running. That is the same race as before. --wait is only as good as the healthchecks behind it.
Teardown is harder. Nx has no "always run afterwards" hook. If you chain deps-down after e2e, either through dependsOn or by listing both targets in one invocation, a failing e2e stops execution and deps-down never runs. The containers keep running, ports stay bound, and the next run collides with them. You can't rely on a separate target for cleanup, so teardown has to happen in the same process that runs the tests. The wrapper script in section 4 does this.
{
"name": "orders-api-e2e",
"$schema": "../../node_modules/nx/schemas/project-schema.json",
"projectType": "application",
"targets": {
"deps-up": {
"executor": "nx:run-commands",
"cache": false,
"options": {
"cwd": "apps/orders-api-e2e",
"command": "docker compose -f docker-compose.e2e.yml -p orders-api-e2e up -d --wait"
}
},
"deps-down": {
"executor": "nx:run-commands",
"cache": false,
"options": {
"cwd": "apps/orders-api-e2e",
"command": "docker compose -f docker-compose.e2e.yml -p orders-api-e2e down -v"
}
},
"e2e": {
"executor": "@nx/jest:jest",
"dependsOn": ["deps-up"],
"options": {
"jestConfig": "apps/orders-api-e2e/jest.config.ts",
"passWithNoTests": false
}
}
}
}
A project.json where e2e depends on a deps-up target that starts the Compose stack and waits for healthy services. The matching deps-down target removes containers and volumes, but nothing calls it automatically, so it does not run after a failed e2e.
How do you write healthchecks that mean ready, not just running?
Each service needs a healthcheck that probes the process itself. For Postgres, run pg_isready -h 127.0.0.1 -U app -d app with an interval of 2s, a timeout of 3s and retries of 15. Pass -h explicitly. The official image runs a temporary server during initialization that listens only on the Unix socket, so a socket-based probe can report ready before init scripts finish. For Redis, redis-cli ping with similar settings is usually enough. Add start_period if cold starts are slow, so early failures don't count against retries.
A plain depends_on list only controls start order. Compose launches the dependent container as soon as the dependency's container exists, whether or not anything is listening. To make Compose wait for the probe to pass, use the long form with condition: service_healthy.
Even a passing probe only tells you the server accepts connections. It says nothing about whether the schema, extensions such as pgcrypto or postgis, or roles your tests expect actually exist. Readiness has to cover every step the tests depend on. So the wrapper should bring containers up, wait for healthy, run migrations as an explicit step that fails loudly, and only then start the test runner.
Seed data should be deterministic: fixed IDs, fixed timestamps, no random fixtures. That way a failure reproduces exactly. Between test files, reset state in one of two ways:
- Truncation:
TRUNCATE ... RESTART IDENTITY CASCADEon the mutable tables, then reseed. - Transactions: wrap each file in a transaction that rolls back. This is faster, but it only works when the code under test shares that connection.
services:
postgres:
image: postgres:16
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: app-e2e-only # throwaway test credential
POSTGRES_DB: app
healthcheck:
# -h forces TCP, so the socket-only init server does not count as ready
test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "app", "-d", "app"]
interval: 2s
timeout: 3s
retries: 15
start_period: 10s # failures during cold start don't use up retries
redis:
image: redis:7
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 2s
timeout: 3s
retries: 15
# One-shot job: schema, extensions and seed data are part of readiness
migrate:
image: example/api:e2e
command: ["npm", "run", "db:migrate-and-seed"]
environment:
DATABASE_URL: postgres://app:app-e2e-only@postgres:5432/app
depends_on:
postgres:
condition: service_healthy # wait for the probe, not just container start
api:
image: example/api:e2e
depends_on:
migrate:
condition: service_completed_successfully # a failed migration blocks startup
redis:
condition: service_healthy
A Compose file where TCP-based healthchecks gate a one-shot migration job, and the API starts only after that job exits successfully. Container start alone does not count as ready.
How do you isolate parallel Nx e2e runs and guarantee teardown?
Under nx run-many -t e2e --parallel, two stacks that share a project name or a host port will collide. Compose uses its project name as a prefix for containers, networks and volumes, so two runs with the same name end up sharing one stack. Derive the name from the Nx project and the CI job, for example api-e2e-${CI_JOB_ID:-local}. Pass it with -p or export COMPOSE_PROJECT_NAME. Concurrent pipelines on a shared runner then stay separate too.
Ports work the same way. A fixed 5432:5432 mapping lets only one stack bind the port. Publish only the container port, written as "5432", and Docker assigns a free host port. After up --wait, ask Compose which port it chose with docker compose port postgres 5432. Export the result as DATABASE_URL or REDIS_URL, and have the tests read those variables instead of assuming localhost:5432.
In the worked example, api-e2e starts Postgres as api-e2e-123. At the same time, worker-e2e starts Redis and its own Postgres as worker-e2e-123. Each stack gets its own network, volumes and random ports, so the two never meet.
Wrap the steps in a script that runs up --wait, then migrations, then tests. Register trap 'docker compose -p "$NAME" down -v' EXIT before up, so teardown runs on a failure or a normal exit. A trap cannot catch SIGKILL. If a CI job is cancelled or the runner dies, containers and volumes stay behind. Add a label such as e2e=true to each service and volume. Then run a scheduled docker container prune and docker volume prune with --filter label=e2e=true to remove the leftovers.
#!/usr/bin/env bash
# Usage: e2e-stack.sh <nx-project> <compose-file> <test command...>
# e.g. e2e-stack.sh api-e2e apps/api-e2e/compose.yaml npx jest
# Compose files publish container ports only ("5432", "6379") and label
# every service and volume with e2e=true so scheduled prunes can find leftovers.
set -euo pipefail
PROJECT="$1"; COMPOSE_FILE="$2"; shift 2
# One Compose project per Nx project per CI job, e.g. api-e2e-123 and worker-e2e-123,
# so parallel stacks never share containers, networks or volumes.
NAME="${PROJECT}-${CI_JOB_ID:-local}"
dc() { docker compose -p "$NAME" -f "$COMPOSE_FILE" "$@"; }
# Register teardown BEFORE up, so a failed up, migration or test still cleans up.
# Turning INT/TERM into a normal exit makes the EXIT trap fire on cancellation too.
# SIGKILL cannot be trapped; label-based pruning covers that case.
trap 'dc down -v --remove-orphans' EXIT
trap 'exit 143' INT TERM
# Start detached and block until healthchecks pass.
dc up -d --wait
# Docker picked a free host port; `port` prints e.g. 0.0.0.0:49153, keep the port part.
host_port() { local addr; addr="$(dc port "$1" "$2" | head -n1)"; echo "${addr##*:}"; }
PG_PORT="$(host_port postgres 5432)"
export DATABASE_URL="postgres://e2e:e2e_password@127.0.0.1:${PG_PORT}/app_test"
# worker-e2e also runs Redis; api-e2e does not.
if dc config --services | grep -qx redis; then
REDIS_PORT="$(host_port redis 6379)"
export REDIS_URL="redis://127.0.0.1:${REDIS_PORT}"
fi
npm run migrate # placeholder: your migration command, reads DATABASE_URL
"$@" # tests read DATABASE_URL / REDIS_URL, never localhost:5432
# Scheduled cleanup job for stacks orphaned by SIGKILL or a dead runner:
# docker container prune -f --filter label=e2e=true
# docker volume prune -f --filter label=e2e=true
A wrapper script that gives each Nx e2e project a unique Compose project name and ephemeral host ports, exports connection URLs for tests, and always tears the stack down via trap, with label-filtered pruning for runs that were killed outright.
Should Nx cache e2e targets that use live containers?
Caching an e2e target fails in two directions. If the inputs are under-declared, Nx sees an unchanged hash and replays a green result from the cache. Nobody started the containers or ran the tests. Suppose someone edits a migration that lives outside the project root, or bumps the image tag in the Compose file. If neither file is in the hash, the next run reports success without checking anything. The opposite failure is over-declaring inputs. If you hash the entire workspace or every environment variable, the hash changes on almost every commit. You then pay for cache bookkeeping and never get a hit.
For most teams, the right default is cache: false on the e2e target. You can also leave it out of cacheableOperations or targetDefaults, depending on how your workspace is configured. Tests against live dependencies are only worth running if they actually execute. Losing a few minutes to a rerun costs less than a false pass.
Caching is defensible only when every input that affects the outcome is hashed. Define a named input, for example e2eDeps, that includes:
- the project's
docker-compose.e2e.yml - the migrations directory
- the seed data files
{ "env": "..." }entries for each variable that changes behaviour, such as feature flags or the database URL scheme
Then add ^production so that changes to upstream libraries also change the hash. Pin images by digest rather than by a floating tag. A floating tag can point to a new image without any file in the repo changing, and Nx cannot detect that.
What changes in CI, and how does it affect cost and engineering time?
CI runners need a working Docker daemon before any deps-up target can run. There are two common ways to provide one, and each has trade-offs.
| Docker-in-Docker | Mounted host socket | |
|---|---|---|
| Security | Requires a privileged container | Job gets root-equivalent control of the host daemon |
| Reaching services | Ports are on the DinD service hostname, not localhost |
localhost works only if the job runs directly on the host |
| Hosted runners | Privileged mode is often disallowed | Socket is often not exposed to containerized jobs |
Pull images ahead of time, or restore them from a cache keyed on the pinned digests. That way registry latency doesn't count against test timeouts.
Cap Nx's --parallel so that the number of concurrent stacks fits within runner CPU and memory. Contention from too many stacks slows healthchecks and queries, and the resulting timeouts look like flaky tests.
On failure, upload docker compose logs as an artifact. Without the logs, a failed run tells you nothing about what the containers were doing.
Illustrative estimate (assumed numbers, not a benchmark). Assume 10 affected projects, 40 s stack startup, 60 s of tests per project, and parallelism of 3.
- Per-project stacks:
ceil(N/P) × (startup + test)= 4 × 100 = 400 s - Shared stack:
startup + ceil(N/P) × test= 40 + 240 = 280 s
The per-project setup costs more CI minutes. Engineering time recovers some of that cost in three ways:
- Affected-only runs: only projects touched by a change start their stacks.
- Reproducible local runs: developers use the same Compose file, so a CI failure can be reproduced locally with one command.
- Fewer shared-state failures: engineers no longer spend hours tracing failures caused by another project's leftover rows.
When should you avoid this pattern, and what are the alternatives such as Testcontainers?
Per-project Compose is not always the right fit. Avoid it in three cases:
- Many tiny e2e projects. If twenty projects each need the same Postgres, starting twenty stacks costs more startup time and runner memory than one shared stack.
- Runners without Docker access. Some locked-down or rootless CI environments cannot reach a Docker daemon, so Compose cannot run there at all.
- Tests that control containers mid-test. If a test needs to kill a broker, restart a database or change its config to check failure handling, Compose's up-before, down-after model gets in the way.
The main alternative is Testcontainers. The test process starts its own containers, gets random host ports, and the library removes the containers automatically, even when a run crashes. Tests can stop, restart or reconfigure a container directly. The cost is that the stack is defined in a language-specific library inside test code. A Go service and a Node service cannot share it, and a developer cannot easily bring it up for manual testing.
| Option | Language-agnostic | Reusable for local dev | Mid-test lifecycle control | Shared across suite |
|---|---|---|---|---|
| Per-project Compose | Yes | Yes | Limited | Per project |
| Testcontainers | No | Poor | Yes | Per test process |
| Single global Compose stack | Yes | Yes | Limited | Yes, but shared state |
| Externally managed environment | Yes | Sometimes | No | Yes |
None of these options guarantees production parity. A Compose file or Testcontainers definition can drift from production manifests unless you review it whenever infrastructure changes.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to nx e2e docker compose, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.