Skip to main content
Real apps aren’t one process. They’re a web tier, an API, a worker, a database, a queue, maybe a search index. Single-repo sandboxes can’t test what happens between services — and the bugs that hide between services are the ones that hurt in production. QLane’s Compose mode runs your entire stack for every test session. If you have a compose.yaml (or docker-compose.yml), point QLane at it and we’ll bring the whole thing up. If you don’t have one, the agent can write it for you from your repos.

​
Why Compose mode

  • Catch integration bugs early. API ↔ database, worker ↔ queue, frontend ↔ API — these only break when they actually run together. Compose mode tests them together.
  • Realistic data. Your seed scripts, fixtures, and DB snapshots run inside the stack the same way they do locally. No more “works on my machine.”
  • One file, every environment. The same compose.yaml you use for docker compose up locally works in QLane. No QLane-specific YAML, no parallel test build.
  • No extra infra. QLane runs the Compose stack in an isolated sandbox per session. Teardown happens automatically when the run ends.

​
When to use this mode

Use Compose mode when any of these is true:
  • Your app needs a database, cache, or queue to even start.
  • You have two or more services that talk to each other.
  • You have a compose.yaml you already run locally — using the same file for QA is the smallest possible workflow change.
If your app is a single Node.js service that just needs a few env vars, stick with Single repo — Compose mode pays for itself only when there’s a stack to bring up.

​
Set it up

From the project page, open Environments → New environment and choose Docker Compose.
  1. Compose file path — where the file lives in your repo. The default is compose.yaml at the repo root.
  2. Primary service — the service the agent should drive (usually your web frontend). QLane uses the URL of this service as the test target.
  3. Port — the port that the primary service exposes (3000, 8080, whatever your app uses).
  4. Environment variables — anything your stack expects via shell env. QLane interpolates ${VAR} references in your compose file with the values you set here.
  5. Profiles (optional) — pass Docker Compose profiles to activate, for example a seed profile that runs a one-shot seeding service.
Save.

​
A compose file that works well with QLane

QLane runs your file as-is. A few patterns make it boot reliably:
  • Healthchecks on every service. depends_on: { service: { condition: service_healthy } } makes the start order predictable.
  • Use ${VAR} interpolation, not committed secrets. Pass real values via the environment’s variables panel.
  • Gate test-only services with profiles. A seed service under profiles: [seed] runs only when QLane activates the profile — your local docker compose up stays clean.
Example skeleton: 
name: my-app

services:
  postgres:
    image: pgvector/pgvector:pg16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

  web:
    build:
      context: .
      dockerfile: apps/web/Dockerfile
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgresql://postgres@postgres:5432/app
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  seed:
    profiles: ["seed"]
    image: node:24-alpine
    command: node /work/scripts/seed.mjs
    depends_on:
      web:
        condition: service_healthy
In QLane, set Primary service to web, Port to 3000, and add seed to Profiles if you want the seed step to run on every session.

​
No compose file yet?

You don’t need to write one to start. From the New environment screen, choose Docker Compose and then Generate from my repos. The agent reads your repos, infers the services and how they talk, and proposes a compose.yaml. You review the diff, tweak anything, and commit it — exactly like any other PR. The generated file is yours. It works locally with docker compose up, works in QLane, and isn’t tied to QLane in any way.

​
What you get in this mode

Compose mode unlocks every agent capability:
  • Real browser against your primary service.
  • Shell inside the sandbox to inspect logs, files, and processes across services.
  • Database queries (when the agent has a connection string) — useful for verifying state after a UI action.
  • Code awareness of every repo bound to the environment.

​
Cold-boot expectations

Compose stacks take longer to come up than single-repo sandboxes because Docker has more to do — build images, start services, run healthchecks. A typical stack is ready in two to five minutes the first time, faster on subsequent runs thanks to layer caching. QLane queues sessions if you exceed the concurrency available on your plan. If you regularly hit the limit, upgrade the plan or talk to us about dedicated capacity.

​
Common gotchas

  • Long healthchecks block everything. If a service’s healthcheck takes 90 seconds, the rest of the stack waits. Tune interval and start_period for fast startup.
  • Don’t expose host ports unnecessarily. Services on the internal Compose network talk to each other by service name (postgres:5432). Only the primary service needs a published port.
  • Heavy seed data. A 5 GB seed script will dominate cold-boot time. Use a smaller, representative dataset for QA — or gate the full seed behind a profile you only activate when needed.
  • Build context size. Add a .dockerignore for node_modules, .next, build outputs, and .git. A 200 MB context turns into 200 MB of build traffic on every session.

​
What happens behind the scenes

QLane provisions a fresh sandbox per session, copies your repo in, and runs docker compose up against your file. When the primary service reports healthy, the agent connects and starts running test cases. When the session ends — pass, fail, or cancelled — the sandbox is destroyed. No state survives between sessions.