Pull request previews for Docker Compose apps

Give each pull request of a Docker Compose app its own private, running copy in your cloud account. Add one .stagely.yml file next to your Compose files.

Your app already runs with Docker Compose. Stagely uses the same Compose files to give each GitHub pull request a stagelet: a private, running copy of the app on its own machine in your cloud account. You add one file to the repository. Then each pull request deploys when someone opens it or pushes to it, as long as the project deploys on push, the default. A pull request from a fork deploys only when someone with write access asks.

Add one file

Commit .stagely.yml to the root of the repository. This one comes from the app that Stagely’s own end-to-end test deploys:

version: 1
compose:
  - compose.yml
public:
  service: web
  port: 8080
health:
  path: /healthz
migration:
  command: /app/migrate

It names the Compose files, the service and the port that people open, the path that answers when the app is healthy, and a migration command. The Compose file stays an ordinary Compose file:

services:
  web:
    build: ./web
    environment:
      GREETING: ${GREETING:-hello}
      PROBE_URL: ${PROBE_URL:-}
    env_file:
      - web.env
    depends_on:
      - cache
  cache:
    image: redis:7-alpine

Stagely reads both files from the head commit of each pull request. .stagely.yml lists every field.

What a deploy does

A build worker in your cloud builds each service that has a build section, and pushes the images to your registry. At the same time, the customer agent creates the stagelet’s own machine, if it does not exist yet. Then the agent runs docker compose up --wait on that machine, with each built image pinned by digest. It runs the migration command, if .stagely.yml has one, and waits until the health path answers with a 2xx status. Last, the stagelet gateway serves the stagelet’s private URL.

The console shows these steps live, with their logs: Lease, Secrets, Build images, Provision machine, Start services, Migrate, Health check and Route. On GitHub, the pull request gets a stagely/<account> commit status. Its Details link opens the stagelet’s page in the console. Deploys from pull requests explains each step and what starts a deploy.

Which Compose settings work

Stagely runs the Compose subset, a safe part of Docker Compose. The subset is a security control: it refuses settings that give a container access to its machine, such as privileged: true, host namespaces, devices, bind mounts and the Docker socket. It also limits build, because the pull requests of all projects in an environment share its build workers.

Most apps need no change:

• Public images, such as redis:7-alpine, and services built from the repository work.
• Named volumes work. They live on the stagelet’s machine and survive deploys and resets of the same stagelet.
• include, extends and env_file work.

If your development Compose file bind-mounts the source code, keep that file for development. Add a second Compose file that builds the image, and name it in .stagely.yml. Compose rules lists every setting that Stagely refuses.

Config and secrets

• Every service gets each config entry as an environment variable. These values override the values in your Compose files.
• Compose variables, such as ${GREETING:-hello}, get their values from the plain config values and from the .env file next to the first Compose file.
• Stagely never sees secret values. It stores only each secret’s name and key. The agent in your cloud holds the values, and a secret reaches the containers only as an environment variable.

Config values and secrets shows how to add them.

When the stagelet ends

Closing the pull request deletes its stagelet. Stagely removes access first, then the agent deletes the machine. A stagelet that nobody deploys again ends after its TTL, 72 hours by default.

Start

1. Set up Stagely once with the Quickstart.
2. Check your Compose files against the Compose rules.
3. Add .stagely.yml, and open a pull request.