Stacks

A stack is a set of resources defined together in one Docker Compose file: several services, the volumes they keep data on, the routes that reach them, and the config files they read. Applying the stack creates or updates all of them at once; each is then an ordinary service, volume or route you can open, marked as managed by the stack.

Where the spec comes from

Written here: edit the Compose file in the stack’s editor.
From git: a Compose file in a repository, fetched on its own or with the whole repository cloned around it. Sync pulls the latest from the branch.
From a template: a one-click template creates its app as a stack. See Templates.

A stack’s variables fill in ${NAME} in its spec, so one spec serves with different values.

Apply and destroy

Apply makes the cluster match the spec: new services are created and changed ones updated, and any service that has never run is started, which is how the rest of a stack comes up after its first rollout stopped part way. A service someone stopped stays stopped. A service taken out of the spec is unlinked from the stack, not deleted: it keeps running as a service of its own, for you to keep or delete.

On a stack from git the two are distinct, and nothing arrives from the repository except through a sync:

Sync fetches the branch’s latest commit: its Compose file, the files it mounts, and, for a service built from the repository, the code at that commit. Then it applies.
Apply again applies the last sync as it was: the same file, the same mounted files, and the same commit for anything it builds. It fetches nothing, so it is the way to retry a rollout, or roll out a change made in Meshploy, without taking what has landed on the branch since. The repository itself is never kept: a sync reads what it needs and drops its clone.

Destroy tears the stack’s services down but keeps the stack and its spec, so applying again brings them back. Its volumes and routes are removed only if you choose to: a volume holds data, and a route holds a name someone may be using.

How Compose maps

A stack runs a Compose file the way Docker Compose would, with Kubernetes underneath:

Names. Each service is reached by its Compose name on any port it listens on, as on a Compose network, and by its container_name and network aliases too. No ports: are needed for one service to reach another.
Builds. A build: section builds from its Dockerfile: dockerfile: if given, else Dockerfile in the context, with its args:. A monorepo whose services share one Dockerfile and differ by a build argument works as written.
Run once. A service another one waits for with condition: service_completed_successfully (a migration, a setup step) runs to completion on each deploy instead of being kept up, and shows as completed. restart: on-failure:N retries it N times.
Start order. A Sync or Apply rolls services out in the order compose starts them: what depends on nothing first, then each service once everything it depends_on is up, a one-shot step having completed. A layer that fails stops what depends on it. The Rollouts tab follows each one, service by service, with each deployment’s log.
What a service reads. A value that refers to a variable another service in the stack publishes, such as DATABASE_URL: $${SHOP_DB_URL} ($$ keeps compose from filling it in), attaches that service’s published group at Apply, before anything starts. A reference nothing defines is a warning on the Apply, and the service starts with it written as it is.
Published ports. A port published everywhere (5432:5432) is reachable on the mesh, never on the internet unless you add a TCP route. One published on a single address of the host (100.81.6.12:5433:5432) gets a TCP route bound to that address, created by its first deploy. One published on 127.0.0.1 stays inside the cluster.
Bind mounts of the repository’s own files (./migrations, ./scripts/setup.sh) arrive where Compose put them, read-only, up to 1 MB per service in all. A bind mount of a path on the host, such as /var/run/docker.sock, is left out, and the apply says so.
Resources. mem_limit, cpus, mem_reservation and deploy.resources set the service’s limits and requests. Where the file says nothing, a new service gets Meshploy’s defaults, and a limit set on the service since is kept by the next apply.
Images kept for rollback. A stack’s built services keep every image they build until the stack says otherwise, on its Services tab: then each keeps its last few, as a service made on its own does. A service’s own x-meshploy.rollback (enabled, retention) in the file wins over the stack’s.
Routes name a port. A route to a service names the port it serves, and that port is routable from then on, even one the file only published on 127.0.0.1 or never listed.

Terms

Apply: Makes the cluster match the stack’s spec. A service taken out of the spec is unlinked, not deleted. More
Apply again: On a stack from git, applies the last sync as it was, its commit included, fetching nothing. Only Sync brings in newer commits. More
Destroyed: The stack’s services are torn down; the stack and its spec are kept, and applying again recreates them. Volumes and routes go only if you chose so. More
Run once: A service that does its work and exits, run to completion on each deploy. Compose marks it by another service waiting for it to complete. More
Stack variables: Values filled in for ${NAME} in the stack’s spec. More