Deploy a Docker Compose application

ReaperCI treats the Compose project on the VPS as an operator-owned deployment definition. It builds and pushes application images, then performs a typed docker compose pull and up -d in an allowlisted absolute directory. The hub does not mount the VPS Docker socket.

Prepare the VPS

Create a dedicated directory such as /srv/acme-app and place the reviewed compose.yaml there. For an outbound connector, include /srv in --deploy-roots. For direct SSH, use a dedicated Unix account with permission only for the required Compose project.

Reference the externally reachable ReaperCI registry and a stable deployment tag in the server-side Compose file:

services:
  app:
    image: ci.example.com/acme-app:staging
    restart: unless-stopped
    ports:
      - "8080:8080"

Configure the target Docker daemon to trust and reach the registry, and set REAPERCI_REGISTRY_PULL_HOST=ci.example.com on the hub. ReaperCI logs in with its robot credential before pull and removes the temporary Docker client config.

Pipeline

on:
  push: [main]
  manual: true

steps:
  - name: test
    image: golang:1.26.5-bookworm
    run: go test ./...
    timeout: 15m

  - name: image
    dockerfile: Dockerfile
    tags:
      - acme-app:staging
    dependsOn: [test]

deploy:
  environment: staging
  compose: /srv/acme-app
  approve: manual
  # Fail before mutation unless the current runtime can be snapshotted safely.
  autoRollback: true
  healthCheck:
    url: https://staging.example.com/healthz
    interval: 5s
    timeout: 10s
    failureThreshold: 3

Use an environment-scoped secret when Compose needs a runtime value. ReaperCI writes a short-lived mode-0600 environment file for the operation and does not return its contents in the deployment record.

Verify and promote

Approve staging, confirm every service is healthy, and inspect the recorded Compose service summary. Promotion copies immutable release inputs to the next environment; it does not bypass that environment's policy. For production, prefer an immutable image tag in the production Compose definition and update that reviewed definition as part of the release process rather than relying on an ambiguous mutable tag.

Before enabling autoRollback, establish and inspect one healthy deployment on the target. ReaperCI records the actual sha256: image ID for every Compose service. If the next health check fails, it queues a typed rollback that overlays those exact IDs on the reviewed base Compose file and runs up -d --no-build --pull never. Registry availability and tag movement therefore cannot change the rollback target. The target must retain the previous images locally; include that assumption in disk cleanup and rollback drills.