Skip to main content

Compose Stacks and Variables

Compose stacks let you define multi-container applications in a docker-compose style YAML within a Template. Stacks are deployed atomically per device and are the recommended way to model multi-service apps.

Defining a stack

  • Services: Each service defines the image, environment, ports, volumes, and depends_on.
  • Networks/Volumes: Optionally declare named networks and volumes used by services.
  • Healthchecks: Add health checks for robust rollouts and remediation.
  • Restart policies: Set restart: unless-stopped (typical for services) or always/on-failure as needed.
  • Pull policy: Prefer immutable digests (image@sha256:...) for production to avoid accidental drift.

Using variables

  • Reference variables with ${VAR} syntax anywhere in the YAML (e.g., image tags, env values, ports, paths).
  • Define variables in the Template’s Variables tab with defaults and mark secrets accordingly.
  • You can override variables at deploy time or per device.
  • Resolution order: Template defaults → Project/device overrides (labels or per‑device settings) → Deploy‑time inputs. The last provided value wins.
  • Pitfalls: If ${VAR} resolves to an empty value, the resulting YAML may be invalid (e.g., missing port). The deploy preview highlights missing variables before proceeding.

Auto-population during deploy

  • When you deploy a Template, Daployi automatically surfaces any missing variables, ports, and scripts referenced by the compose or template so you can fill them before confirming.
  • Validation: The compose content is linted server-side; schema errors (unknown keys) or collisions (duplicate ports) are shown in the preview.

History and revisions

  • Every save to the Template creates a new revision recorded in the History tab.
  • The History view shows who changed what, with a diff of the Compose YAML and related variables.
  • You can filter history to just Compose changes to quickly find image tag updates or service edits.
  • Triggers for new revisions: saving compose content, changing variables referenced in compose, or modifying services in the Containers tab (for non-compose templates).

Reverting and rollbacks

There are two common rollback paths:

  1. Redeploy an older Template revision (roll back config/YAML)
  • Open Templates > Your Template > History.
  • Pick a previous revision and click Deploy this revision.
  • Confirm variables; Daployi will use the older Compose content and redeploy to selected devices.
  • Result: Services are recreated/restarted as needed to match the older revision.
  1. Recreate with previously running image versions (hotfix)
  • If only one service failed after a tag change, you can pin the prior tag/digest in variables and redeploy the current revision.

Caveats

  • Rolling back the compose file may also roll back unrelated changes (e.g., env defaults). Review diffs carefully.
  • Devices with local overrides (device vars) keep their overrides unless you explicitly change them during deploy.

Notes on healthchecks and remediation

  • Define service healthchecks so failed updates are quickly visible in Events and can be remediated with post‑deploy scripts or automatic restarts.

Examples

services:
  api:
    image: ghcr.io/org/api:${API_TAG}
    environment:
      - DB_URL=${DB_URL}
    ports:
      - "${API_PORT}:8080"
    depends_on:
      - db
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"]
      interval: 10s
      timeout: 2s
      retries: 6
  db:
    image: postgres:${PG_TAG}
    environment:
      - POSTGRES_PASSWORD=${PG_PASSWORD}
volumes:
  db-data:

Best practices

  • Use digests (image@sha256:...) or pinned tags for production stability.
  • Keep secrets in variables, not hard-coded in YAML.
  • Validate compose locally in a lab before wide fleet deployment.