Compose stacks

Pick a Compose stack when the software you want already has a docker-compose.yml, or when you want to describe several containers in one file. For one container built from your code, an Application gives you more: previews, rollbacks and patches.

What you can do

• Write the compose file in the console, or deploy it from a repository.
• Apply it as Docker Compose on one machine or as a Swarm stack.
• Give any service in the file a Domain and a port.
• See the file Cloudgate actually deploys on the Converted tab.
• Act on single containers, read logs and open a shell.
• Run it on a Server, or in AWS or Google Cloud on its own Stack VM.
• Ask Cloudgate’s AI provider to draft one with Draft one with AI.

Add a Compose stack

1. Open the Environment

   Open the Environment, such as production in storefront, and its Services tab. Press Add a Compose stack.

2. Name it and pick its Server

   Enter a Name and an optional Description, then choose the Server, such as fra-1.

3. Choose where the compose file comes from

   Under Where the compose file comes from, choose:

   • A file written here: stored in Cloudgate and edited on the stack’s own screen. Nothing is cloned.
   • From a repository: cloned from a git provider on every Deployment. You set the connection on the stack’s screen next, with the path to the file.

4. Choose how it is applied

   Under Applied as, choose Docker Compose (brings the file up on one machine) or Swarm stack (schedules it across the Swarm). You can change this later; the next deploy removes the old kind first and keeps its volumes.

5. Write the file and deploy

   The stack opens on its Overview. Paste or write the file in the Compose file editor, which checks the YAML, save it, then press Deploy.

   cloudgate.octabyte.app/compose/…

   

A stack’s tabs are Overview, Converted, Containers, Logs, Shell, Deployments, Domains, Health, Traces, Requests, Variables and Advanced.

Draft a stack with AI

Draft one with AI, on the same Services tab, describes what you want in words, shows suggestions and writes a compose file for the one you choose. It needs an AI provider in Settings > AI. The stack is created but not deployed: read its file, then deploy it.

See what Cloudgate deploys

The Converted tab shows the file Cloudgate actually applies and what it changed. For example, when a Docker Compose stack’s service has no restart policy, Cloudgate adds restart: unless-stopped.

Give a service in the stack a Domain

Open the Domains tab and add a Domain such as shop.northwind.example. Choose which Service in the compose file it routes to, and the port that service listens on inside its container. Certificates work as they do for Applications: see Domains.

Set variables for the compose file

The Variables tab holds values the compose file substitutes, such as ${POSTGRES_PASSWORD}. For Docker Compose they are written to a .env file beside the compose file; Swarm has no .env support, so a Swarm stack gets them in front of the deploy command. Project and Environment variables are available to reference by name, never inherited. See Environment variables.

Keep the stack to itself

On Advanced, Network isolation decides whether the stack shares Cloudgate’s network with every other Service. Turn on Deploy onto its own network to keep it apart; the next Deployment applies it.

Stop, remove containers or delete a stack

Action	What it does
Stop	Stops the stack’s containers.
Start	Starts them again.
Remove containers	Docker Compose stacks only: removes the containers and keeps the network, the directory, the volumes and the record.
Delete stack	Destroys the stack. Its volumes go only if you tick Delete its volumes too.

Use Remove containers before restoring a volume the stack uses: a volume cannot be restored while any container, running or exited, still references it.

Compose stacks in AWS and Google Cloud

In an Environment whose Deploy target is a Cloud account, each Compose stack runs on its own Stack VM in that account and region, inside the Environment network. The Environment’s next Plan makes the VM; you choose its Size and its Data disk (GB), where its named volumes live, snapshotted daily. The stack page’s facts card shows whether the VM is running, starting, stopping, stopped or not made yet, read from the cloud.

• Its Domains are rules on the Environment network’s load balancer. Two services’ Domains cannot share a port.
• Only the Docker Compose type runs there: a type: stack entry is refused.
• The Containers tab’s per-container actions are not offered on a Stack VM; the stack’s Restart restarts its containers.
• Delete takes a final snapshot of the data disk unless its data is deleted too.

Resize a Stack VM or grow its disk

A Stack VM changes only through its Environment’s Plan, on AWS and Google Cloud alike. A new size in the Project config, or a new Size on the stack page for a stack made in the console, is a change line that says it restarts the Stack VM and shows the old and new monthly price, for example “analytics Stack VM: t3.small (2 vCPU, 2 GB) → t3.medium (2 vCPU, 4 GB), restarts the Stack VM”. An entry with no size keeps the machine it was made on.

A disk grown on the stack page is a change line too, grown in place with no restart and priced; the Apply grows its filesystem. A disk only grows: a smaller size is refused, naming the stack.

When Cloudgate’s pinned Ubuntu image, Docker Engine or compose plugin moves on, the Plan offers a replace VM line naming each pin’s old and new value. Applied, it makes a new Stack VM, keeps the data disk and its volumes, and deploys the stack onto the new VM.

Stop, start and restart a stack on a Stack VM

Action	What it does
Stop	Stops the stack’s containers, then stops the VM, so a stopped stack pays only for its disk.
Start	Starts the VM, waits until its tunnel answers, then starts the containers Stop stopped, as they were.
Restart	Restarts the stack’s containers and never touches the VM.

A Deployment of a stack whose Stack VM is stopped is refused with 409 (“start it first, then deploy”), and so is a Deployment, Stop, Start or Restart before the Environment’s next Plan has made the VM. A frozen Organization’s Stack VMs keep running, and Stop is refused like any other change.

Describe a stack in the Project config

A stack whose file is in a repository can be written in the Project config:

services:
  analytics:
    kind: compose
    source:
      github: northwind/analytics
    file: deploy/docker-compose.yml
    type: docker-compose

The config names the file; it never holds a copy. A change to the file’s contents reaches the stack at its next Deployment, not as a Plan line. A stack whose file is written in Cloudgate stays console-managed: the config lists it by name and kind, and a Plan never changes or destroys it.

What you cannot do

• Deploy a stack by pushing to its repository.
• Reserve GPUs for a Compose stack. Its containers are not kept off a GPU Server’s cards either.
• Use previews, rollbacks or patches: those are for Applications.
• Schedule volume backups for a stack from its own screen: the console’s Volume backups tab is on Applications and buckets.
• Run a Swarm stack in a Cloud account, or move a stack to another Server.

Related pages

• Applications, for one container built from your code.
• Domains, TLS and CDN.
• Backups and volume restores.
• Templates, which set up whole apps for you.
• Servers and Cloud accounts.
• See what Cloudgate runs on the features page.

Questions

Does a git push deploy a Compose stack?

No. A Compose stack from a repository is cloned on every Deployment, but no push starts one: every deploy is one someone starts.

What is the difference between Docker Compose and Swarm stack?

Docker Compose brings the file up on one machine. A Swarm stack schedules it across the Swarm. You can change it later; the next deploy removes the old kind first and keeps the volumes.

Can a Compose stack run in AWS or Google Cloud?

Yes. In a Cloud account each stack runs on its own Stack VM inside the Environment network, made by a Plan and reached through the cloud tunnel.