How Compose works

Stacks, projects, and app-composes are three different things — plus validation and GitOps.

Repository-validated operator guidance View source ↗

#Three models

Model	What it is	Endpoints
Compose stacks	Live runtime objects on a node (deploy, stop, logs, rollback).	/compose, /compose/:id, /compose/:id/deploy
Compose projects	Legacy store-only documents with revisions. No runtime.	/compose/projects
App-composes	Per-application editor view over source_config. No separate table.	/apps/:id/compose

#Validation

POST /compose/validate checks a document before anything is created: at least one service, each with an image or build step, and a security pass that rejects privileged mode, host networking/PID/IPC, dangerous capabilities, host device mounts, and Docker-socket or /proc mounts. Interpolation supports ${VAR}, defaults, errors, and $$ escapes. Imports are validated the same way, and env_file is rejected at the HTTP layer with a clear error.

FLOW

Compose intake

01Write YAMLcheck

02Server validationpersist

03Create stackprovision

04Deploy to nodepoll

05GitOps updates

#GitOps on stacks

A stack can deploy from a repository, track a branch, poll for updates, preview and diff incoming commits, roll back, and receive provider webhooks that redeploy on matching branches. Drift checks compare deployed SHA, YAML, and runtime state.

Under /api/v1

POST /compose                          create stack
POST /compose/validate                   validate only
POST /compose/import                     import as project
POST /compose/git/deploy                 deploy from repo
GET  /compose/git/:id/check-update|/preview|/drift|/status
POST /compose/git/:id/redeploy|/rollback|/pull-redeploy
POST /compose/webhook/:webhookId         provider webhook