Docker Compose

​

When to use this mode

• Your app needs a database, cache, queue, or object store before it can start.
• You have two or more services that talk to each other.
• Your repository already ships a compose.yaml or docker-compose.yml.

​

The one requirement that matters most

# ✗ The pull request is not in this image
services:
  app:
    image: ghcr.io/acme/checkout:latest

# ✓ The pull request's code is what runs
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile

​

Step 1: Choose or write the compose file

1. Does it contain a service that builds your app from source? If not, keep looking.
2. Does that service publish a port (ports: - "3000:3000")? Something must be reachable from outside the stack.
3. Does it start on a plain docker compose up, or is the app behind a profiles: gate? Either works — you select profiles on the environment — but you need to know which.

​

Option A: add a testing overlay

# Testing-only overlay. Changes nothing you ship.
include:
  - path: docker-compose.yml # your existing file, used as-is

services:
  app: # must match the service name in the included file
    image: myapp-pr:test # a name that exists in no registry
    pull_policy: build # without this, the included file's image is still pulled
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000" # re-declare the published port here

• pull_policy: build is not optional. include: merges rather than replaces, so the base file’s image: survives alongside your build:, and a plain docker compose up -d pulls the published image and never builds. The overlay passes every check and still tests the release. The unregistrable image: name is a second guard: if anything ever pulls anyway, it fails loudly instead of serving the wrong code, and it is what lets you verify the overlay locally. Nothing is wasted by either: a pull-request sandbox starts with no images of its own, and where build caching is on, the build still reuses unchanged steps.
• Name it compose.qlane.yaml. That name is recognised and listed first when you pick a compose file. compose.qlane.yml, docker-compose.qlane.yaml and docker-compose.qlane.yml work too, at any depth in the repository. qlane must be the whole variant: compose.qlane-staging.yaml is still listed, but not first, so you have to select it yourself.
• Re-declare the published port on the overridden service — the same mapping the base file uses. The file you select is read as written, and include: targets aren’t followed when you pick the primary service, so a port declared only in the base file is invisible there, and the environment is refused. Repeat it exactly: an identical mapping collapses into one, but a different one is added, and the service then publishes both. The same goes for any service you want to expose and any profile you want offered.
• Keep the include inside the repository. A relative path is the normal case. Absolute paths, https:// or oci:// URLs, and ../ paths that climb above the overlay’s own directory are flagged: the sandbox only has your repository’s clone.
• Override, don’t rename. The service key must match the base file, or you add a second service instead of replacing the first.
• Settings merge into the base service; most lists don’t replace. Writing only healthcheck: { start_period: 120s } keeps the base file’s test, interval and retries and adds a grace window — worth doing whenever the first boot runs migrations before the app listens, or the service is reported unhealthy for that whole first start. command and entrypoint replace the base value. ports and env_file are combined with the base file’s, which is why the port above must match.

​

Option B: write a standalone test compose file

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile # builds the pull request's code
    ports:
      - "3000:3000" # something must be reachable
    environment:
      HOST: 0.0.0.0 # listen on every interface, not loopback
      DATABASE_URL: postgres://app:app@db:5432/app
      APP_URL: ${QLANE_SANDBOX_PUBLIC_URL:-http://localhost:3000}
      LOG_LEVEL: ${LOG_LEVEL:-info}
    depends_on:
      db:
        condition: service_healthy
    pre_start:
      - command: ["npm", "run", "db:migrate"] # runs before the app starts
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/health"]
      interval: 5s
      timeout: 3s
      retries: 20
      start_period: 60s # a slow first boot isn't counted as a failure

  db:
    image: postgres:17-alpine # a backing service — prebuilt is correct
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 3s
      timeout: 3s
      retries: 20

• No named volume on the database. The sandbox is discarded after every run, so a volume buys nothing, and it is what makes docker-entrypoint-initdb.d behave inconsistently.
• A healthcheck on every service. condition: service_healthy means nothing without one, and without one on the app, readiness falls back to “the container is running”, which is true well before it can serve. Common backing services have a one-line check:

  Service	healthcheck.test
  PostgreSQL	["CMD-SHELL", "pg_isready -U app -d app"]
  MongoDB	["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
  Redis	["CMD", "redis-cli", "ping"]
  MySQL / MariaDB	["CMD", "mysqladmin", "ping", "-h", "127.0.0.1"]

• Probe readiness, not liveness. The app’s healthcheck decides when the postdeploy hook runs and when tests start, so it must pass only once the app can serve a real request — after its migrations have finished. Many apps expose a liveness endpoint (often /healthz) that answers as soon as the server listens, before the schema exists; a seed that waits on it writes to tables that are not there yet. Probe a readiness endpoint if the app has one, or a page or API route that reads from the database.
• Probe 127.0.0.1, not localhost. In many images — Alpine-based ones especially — localhost can resolve to the IPv6 address ::1. A server listening on 0.0.0.0 accepts IPv4 only, so a localhost probe is refused and the service never reports healthy, even though the app is fine.
• Use a probe tool your image has. Alpine images have wget; slim Debian images often have neither wget nor curl. Then use your runtime, for example node -e "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))".
• Serve the production build. The Dockerfile’s final command should serve built output, not run a dev server — the reasons are the same as for a Simple sandbox.
• Throwaway credentials, committed. The stack is ephemeral and unreachable from outside, so these aren’t secrets. Never do this with real ones.

​

Step 2: Environment variables

​

.env is written for you — other env files must be committed

env_file: .env # ✓ provided for you

env_file: .env.docker # ✗ must be committed, or the run is refused

env_file:
  - path: .env.local
    required: false # skipped when absent instead of failing

​

${VAR} interpolation

environment:
  LOG_LEVEL: ${LOG_LEVEL:-info} # default when unset
  API_TOKEN: ${API_TOKEN:?set API_TOKEN on the environment} # refused when unset or empty
  REGION: ${REGION?set REGION on the environment} # refused when unset only — empty passes

​

Public address of your app

services:
  app:
    environment:
      APP_URL: ${QLANE_SANDBOX_PUBLIC_URL:-http://localhost:3000}
      OAUTH_REDIRECT_URI: ${QLANE_SANDBOX_PUBLIC_URL:-http://localhost:3000}/callback

• In a variable configured on the environment, write exactly ${QLANE_SANDBOX_PUBLIC_URL} — braces, no :- default. qlane expands it before anything starts, and the rules are stricter than Compose’s: the unbraced $QLANE_SANDBOX_PUBLIC_URL isn’t expanded, and a modifier such as :-fallback is refused as an unknown name, like a typo would be, so a misspelt reference never reaches your app as a literal string. To pass the text through unexpanded, write $${QLANE_SANDBOX_PUBLIC_URL}.
• Not inside a committed .env or .env.example. Compose expands an entry there using only the entries above it, and the variable is added at the end of that file, so it silently becomes empty or your localhost fallback. Reference it from the compose file or an environment variable instead.
• Build-time values need build args, declared late. Front-end frameworks that bake configuration into the bundle (VITE_*, NEXT_PUBLIC_*) read it while the image builds, before environment: applies. Pass it through build.args and declare the matching ARG in the stage that runs the build (no ENV needed — an ARG is already in the environment of every later RUN in its stage). The address differs in every sandbox, so every step from the first RUN after the ARG is rebuilt on every run, even with build caching. Declare it just before the build step, not at the top:
  services:
    app:
      build:
        context: .
        args:
          NEXT_PUBLIC_APP_URL: ${QLANE_SANDBOX_PUBLIC_URL:-http://localhost:3000}
  
  COPY package.json yarn.lock ./
  RUN yarn install --frozen-lockfile
  COPY . .
  ARG NEXT_PUBLIC_APP_URL                # here, after the install, not at the top
  RUN yarn build
  
• Names starting with QLANE_ are reserved. Saving a variable of your own with that prefix is refused. A line of that name in your committed .env.example is left alone as long as you don’t edit it; it never becomes one of your variables, and the value qlane sets replaces it.

​

A literal $ inside configs:

configs:
  proxy_conf:
    content: |
      proxy_set_header Host $$host; # ✓ nginx receives $host
      proxy_set_header Host $host; # ✗ Compose substitutes it; nginx receives an empty header

​

Private packages during the build

services:
  app:
    build:
      context: .
      secrets:
        - npm_token

secrets:
  npm_token:
    environment: NPM_TOKEN # configured on the environment, not committed

RUN --mount=type=secret,id=npm_token,env=NPM_TOKEN yarn install --frozen-lockfile

• Why not a build argument. A build argument is recorded in the image’s history, so anyone who can read the image can read the token. A secret mount is never written into a layer or the history, and it isn’t part of the step’s cache key, so rotating the token doesn’t force a rebuild.
• Never leave the credential in a file a build step writes. A step that writes an .npmrc holding the token, or a ~/.m2/settings.xml with a password, puts it in that step’s layer, and layers are what build caching saves — including the early stages of a multi-stage build. If a tool insists on a config file, have it read the token from the environment, or write and delete it within the same RUN.
• Use a read-only token scoped to package downloads, never a general-purpose or write-capable one.
• A credential committed in your repository works without any of this, because the checkout carries it. That isn’t a reason to do it: see never commit real secrets. A committed credential that a build copies is also in the cached layers.
• Fetching from your git host during the build (git fetch, git submodule update, a private git dependency) can’t rely on qlane’s access to your repositories. Give that step its own read-only credential as a build secret, and don’t put a token in a clone URL: git clone writes it into .git/config, and so into the layer. Pass it through a credential helper or an Authorization header instead.

​

Step 3: Get the app into a testable state

​

Migrations — pre_start

services:
  app:
    build: .
    depends_on:
      db:
        condition: service_healthy
    pre_start:
      - command: ["npm", "run", "db:migrate"]

• The service has a custom entrypoint. The step’s command is passed to it as arguments: with entrypoint: ["./start.sh"] the step runs ./start.sh npm run db:migrate, and if the script starts the server instead, the step never finishes. Give the step its own entrypoint: ["sh", "-c"] with command: ["npm run db:migrate"].
• The service runs as a non-root user or with read_only: true. The step does too, so a migration that writes inside the container fails. Give the step its own user: or read_only: false, or write to a volume.

​

Accounts and data

• Your app has no self sign-up: accounts are invite-only, created by an admin, or signed in through single sign-on.
• Signing up needs something an inbox can’t give, such as a phone number, a CAPTCHA or an address on your own company’s domain, or a confirmation email your app can’t send from the sandbox.
• Cases need a role or a plan that a new sign-up doesn’t get.

​

When you need a test account or seed data — the postdeploy hook

services:
  app:
    build: .
    labels:
      ai.qlane.postdeploy: "npm run db:seed"

• A failure fails the run and shows the hook’s output. Nothing is tested against a half-seeded stack.
• Several services may each declare one. They run one at a time, in no guaranteed order — if one must precede another, chain them in a single command.
• The command runs through sh -c, so the image needs a shell (not distroless or scratch), and the service must still be running — a hook on a one-shot that has exited fails with service "<name>" is not running.
• All hooks share one deadline of about two minutes, and there is no timeout label. The deadline grows with the provision timeout only up to that cap, which it reaches at about ten minutes. Keep seeds small, and move slow work that needs only your backing services into pre_start, which runs inside the build budget. A seed that calls the app’s own API can’t move there, because pre_start runs before the app starts.
• Declaring a hook takes about two minutes off the build budget (see Build time, caching and memory). Merely adding the label can push a build that used to fit over the limit.

• An app’s own ingest endpoint stamps rows with the server’s clock. For anything that shows a trend or “the last N days”, write those rows to the database directly, with the timestamps you want.
• Randomness that doesn’t reference the row can be evaluated once. random() in a sub-select that doesn’t reference the outer row can yield one value for the whole dataset. Derive the varying value from a hash of the row’s own key (md5(id::text || ':' || n::text)), and verify by counting distinct values, not rows.

​

Step 4: Create the environment

​

Step 5: Turn on pull-request testing

​

Profiles, exposed services and several repositories

​

Compose profiles

• It is pre-filled. Once you pick a primary service, the profiles it needs are ticked: its own, those gating anything it depends_on, and those gating what those bring in. Each row says which services it gates and why it was ticked. Reset to suggested brings the pre-fill back.
• You can change it. If your edit leaves nothing that starts the primary service, you’re told on the spot, and a run configured that way is refused before anything is provisioned.
• Only profiles declared in the file you select are offered; profiles in an include:d file get no row.
• Ticking nothing leaves COMPOSE_PROFILES alone. A value committed to your .env, or configured as a variable on the environment, then applies — and the environment’s variable wins over the committed one, as Compose ranks the process environment above .env. The selector lists each value and names the one that applies. With anything ticked, the selection wins.

​

Exposing more than one service

• Only a port published under ports: can be exposed. Declaring an exposed service whose port no compose file publishes is refused before anything is provisioned.
• The preview URL doesn’t move, and the port it points at isn’t offered again; the primary service can still be exposed on another port it publishes.
• One port per service. Ticking one of a service’s ports holds its other rows until you untick it.

​

A stack that spans several repositories

• Networking. Services reach each other across components over the project’s default network, by service name. A service joins it only when its networks: key is absent or empty; a non-empty networks: replaces the default. Same-named networks in two components’ files don’t merge, and external: true doesn’t connect them either. So leave networks: off services that talk across repositories — and watch for a file where most services name a network and one doesn’t, which silently splits the stack.
• Names and published ports are project-wide. Two components defining the same service name, or publishing the same host port, are refused. Publish only the ports something outside the stack needs; service-to-service traffic never needs one.
• Paths are per repository. Each component’s file is read from its own checkout, so build: { context: . } means that repository. Keep one file per repository, with the services built from it and the backing services only it uses, and never hard-code another component’s directory. depends_on, including service_healthy, works across components.
• Every component is a trigger. Where automatic runs are on, the check passes and the watch paths match, a pull request in any connected repository starts a run here. There is no “present but not tested” component: connect a repository only if you want its pull requests tested.
• Branches with the same name are tested together. A run also checks out the triggering pull request’s branch name in every other component that has it, so a change split across repositories is tested as one — and each matched repository must build from source too. This is off when the environment has one component, for pull requests from forks, and for main, master, dev, develop, staging and branches starting renovate/ or dependabot/. Every other component is cloned at its configured Default branch.
• The triggering repository reports the default branch name. Its tree holds the pull request’s commit, but git rev-parse --abbrev-ref HEAD returns the default branch, so don’t derive a version, tag or cache key from it there.
• Clones are shallow, so builds that run git describe or count commits see a truncated history. Pass such values in as variables instead.

​

Build time, caching and memory

• Install dependencies before copying the source. Copy package.json and the lockfile, install, then COPY . .. The reverse order re-installs everything on every commit, and it is also what stops the cache reusing the install between pull requests.
  COPY package.json yarn.lock ./
  RUN yarn install --frozen-lockfile     # unchanged by most pull requests
  COPY . .
  RUN yarn build
  
• Keep the build context small. A .dockerignore excluding node_modules, .git, build output and test fixtures pays off on every run.
• Pick a bigger Compose size if it’s still too slow. New environments already start at the 30-minute maximum provision timeout, so for them the remaining lever is more CPU, not more time. An environment created before that default may still be on a shorter timeout: raise it to 30 minutes on the environment page before paying for a bigger size. Prefer the first two either way: sandboxes are billed for the time they’re up.

​

Build caching

• On by default. Turn it off on the environment’s page or in the Infra step; turning it off deletes the environment’s cached layers.
• Kept for up to 15 days after the environment’s last build.
• A fresh start once a week, on a day that differs between environments, so an unpinned download (apt-get install, a curl of a “latest” URL) is at most seven days stale. That build reuses nothing.
• Pull requests from forks never use it: they reuse nothing and save nothing. A pull request from a branch of the repository itself does, so anyone who can push a branch can influence what later builds reuse — the same trust a sandbox already gives them.
• A layer holds whatever its step writes: copied source, downloaded dependencies, and any file a RUN writes, including a credential in a config file. Carry credentials as build secrets.
• A build argument whose value changes per sandbox stops reuse at the first RUN after its ARG — see build-time values.
• Your .dockerignore rules still apply. To keep the written .env files out, qlane writes a Dockerfile.dockerignore (named after your Dockerfile) for the length of each cacheable build, containing your own rules copied exactly plus one line per .env it wrote, then restores or removes it.
• Some services read the cache but never save to it. The build log names each one and why. That happens when a service uses dockerfile_inline; has a remote URL or git repository as its context, or additional_contexts pointing at a local directory or at another service that can’t save; shares its Dockerfile with a service using a different context; has its context or Dockerfile outside the checked-out repositories, or reached through a symbolic link; has an ignore file that isn’t UTF-8 text or is a symbolic link; has a .env in its context that qlane didn’t write (one your repository commits, at any depth); or when qlane can’t inspect the context or write the ignore file. A service with both image: and build: whose pull policy pulls isn’t built at all, so it saves nothing either.
• A cache problem falls back to a build without it. If the cache can’t be reached, the build runs without it; if a cached build fails, qlane retries once without the cache and the log says so. If that fails too, the error is your build’s own. A cache that is reachable but slow can still use up most of the budget before the retry.

​

Build memory

ARG BUILD_MAX_OLD_SPACE_MB=4096
ENV NODE_OPTIONS=--max-old-space-size=${BUILD_MAX_OLD_SPACE_MB}
RUN yarn build

​

Worked example: an app whose shipped compose file can’t be reused

# Testing-only stack for pull-request sandboxes. The shipped compose file
# still pulls the published image; this one builds the pull request.
services:
  web:
    image: myapp-pr:test # unregistrable: a pull can never pass for a build
    pull_policy: build
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
    environment:
      HOST: 0.0.0.0
      NODE_ENV: production
      DATABASE_URL: postgres://app:app@db:5432/app
      # The address the app builds links and redirects from.
      PUBLIC_URL: ${QLANE_SANDBOX_PUBLIC_URL:-http://localhost:3000}
      # Throwaway values for an ephemeral sandbox — not your production secrets.
      SESSION_SECRET: test-only-session-secret-0123456789abcdef
      # Let an automated tester sign in repeatedly without locking itself out.
      LOGIN_RATE_LIMIT: "1000"
      # A third-party key the main features need, configured on the environment.
      PAYMENTS_API_KEY: ${PAYMENTS_API_KEY:?set PAYMENTS_API_KEY on the environment}
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://127.0.0.1:3000/health"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 120s
    labels:
      # A known login for the agent, created once the stack is healthy.
      ai.qlane.postdeploy: "npm run users:create -- --email qa@example.com --password 'Qa-test-2026!'"

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 3s
      timeout: 3s
      retries: 20

​

What’s checked before a run

​

Troubleshooting a failed configuration check

​

The primary service publishes no port

​

The app listens on 127.0.0.1

​

The app listens on a different port than the mapping targets

​

The healthcheck never passes

• The app may still be starting — migrations, cache warm-up, a large bundle. Add a start_period long enough to cover it.
• The probe may target localhost, which can resolve to IPv6 ::1 while the app listens on IPv4 only. Probe 127.0.0.1.
• The probe tool may not exist in the image. Use wget on Alpine, or your runtime itself.

​

The build runs out of time or memory

​

Other common problems

​

Your compose file isn’t in the list

​

The run passes, but your change isn’t there

​

Compose stops before anything builds

• A bind mount of an uncommitted file or directory — ./.env, a local config file, a data directory. Pass the settings as environment variables, or commit a test version of the file and mount that.
• user: "${UID}:${GID}" — those variables aren’t set in the sandbox, so the value is empty. Drop the line in your test compose file.
• An env_file: naming an uncommitted file — see Step 2.

​

A backing service exits right after it starts

​

The app is up, but pages are blank or redirect to localhost

​

The agent can’t sign in, or is locked out partway through

• The agent signed itself up, but the confirmation email never arrived. If your app sends that email itself, it needs real outgoing mail settings in the sandbox: a mail catcher such as Mailpit in your compose file keeps the email inside the sandbox, where the agent’s inbox can’t receive it. Set your app’s mail settings in the Env step, or add a test account.
• The test account doesn’t exist. Check the Postdeploy hook step of the run for the hook’s output.
• The user-creation command asked a question. A hook has no one to answer it, so it fails or hangs until the deadline. Pass every value as an argument or flag, so the command never prompts.
• The app’s own brute-force or abuse protection kicked in. An agent signs in, retries and navigates fast, which can trip login limits and automatic bans. Relax them in your test compose file.

​

Features that need a third-party key ask for one

​

The build is killed even on the Large size

​

Before you push: self-check and checklist

F=compose.qlane.yaml

# 1. Does it parse, and what starts? Empty output = every service is profile-gated.
docker compose -f $F config --services

# 2. Does the app service build from source?
docker compose -f $F config | grep -A3 'build:'

# 3. Which env files does it expect? Anything other than .env must be committed.
grep -n 'env_file' $F

# 4. Which variables must be supplied?
docker compose -f $F config 2>&1 | grep 'variable is not set'

# 5. Is every one-shot gated? A migrate or seed service with neither fails silently.
#    `required: false` on a service_completed_successfully edge means it is NOT a gate.
grep -n 'service_completed_successfully\|pre_start\|required: false' $F

# 6. Anything that must already exist? Nothing creates these in the sandbox.
grep -n 'external: true' $F

# 7. Does the app need its own address? Check the compose file and the COMMITTED env
#    files beside it (run from its directory). A hit that is the app's own URL needs
#    ${QLANE_SANDBOX_PUBLIC_URL}; a hit inside a committed env file must move out of it.
grep -nE 'https?://(localhost|127\.0\.0\.1)' $F $(git ls-files .env .env.example)

# 8. Does it fit the budget with nothing reused, the way a first build runs?
docker compose -f $F down -v                  # discard volumes so init hooks re-run
time docker compose -f $F build --no-cache
time docker compose -f $F up -d               # no --build: see below
#    Together over ~24 minutes (~22 with a postdeploy hook) => see the build budget.

# 9. Does the app answer on its published port?
curl -fsS -o /dev/null -w '%{http_code}\n' http://localhost:3000

​

Verify an overlay builds rather than pulls

docker inspect <container> --format '{{.Config.Image}}'   # must be myapp-pr:test

• The app service builds from source, directly or through an overlay with pull_policy: build (why)
• Every repository under test builds its own code, not only the one the pull request was opened in (several repositories)
• It serves the production build, publishes a literal port, binds 0.0.0.0, and has a healthcheck that probes 127.0.0.1
• It starts without a profile, or the environment’s profile selection activates one (profiles)
• env_file: is .env, or the referenced file is committed (env files)
• Every required ${VAR} has a default or is configured on the environment, and no real secret is committed (interpolation)
• The app’s own URL comes from ${QLANE_SANDBOX_PUBLIC_URL} in the compose file or an environment variable, never a hard-coded localhost or a committed .env (public address)
• Build-time credentials are build secrets, not build arguments or files left in a layer (private packages)
• Migrations run before the app serves, and a failure stops the start-up (Step 3)
• A new sign-up can reach what your cases test, or a postdeploy hook creates the test account you added (accounts and data)
• A build that reuses nothing fits the budget on the Compose size you picked, and doesn’t exhaust the Node heap (budget)
• Nothing is declared external: true, and nothing bind-mounts an absolute or uncommitted path (what’s checked)
• With several components: service names unique, no host-port collisions (several repositories)

​

What happens behind the scenes