Skip to content
Install

Deploy a compose stack

A compose stack lets you bring an existing docker-compose.yml file to Orchard instead of creating each app by hand. Orchard reads the file from a GitHub repository and turns each service into its own app in the project, so you can scale, redeploy, and roll back each service on its own.

  • A GitHub repository that contains the compose file.
  • For a private repository, a GitHub account linked to Orchard that can read the repository. To link one, go to Account settings > Connections. A public repository works without a linked account: paste owner/repo into Repository.
  1. Open the project.
  2. Go to Compose.
  3. Select Deploy compose file. If the project already has a stack, select New stack.
  4. Enter a name for the stack. To deploy into another environment, select it next to the project name.
  5. In Repository, select the repository.
  6. In Branch, select the branch.
  7. In Path to docker-compose.yml, confirm the path.
  8. (Optional) Turn off Auto-deploy on push.
  9. Select Deploy stack.

Orchard opens the stack page. Builds run in the background.

Orchard names each app <stack>-<service>. Services reach each other by their compose names, as they do in Docker Compose: db:3306 works, on the container’s port. Each name must be free in the project’s environment, so two stacks with a service named db need separate environments or projects. A name with an underscore or another character that DNS does not allow has no such address. To find the full internal address, open the app and go to Network > Ports.

Compose keyOrchard result
imageAn app that runs the image.
buildAn app that Orchard builds from the repository, with context and dockerfile.
portsThe app’s ports. The first TCP port that is not a known database or other non-HTTP port gets a URL, which only your organization can open until you make it public.
exposeMore ports on the app, for other services. No URL.
environmentThe app’s variables.
volumes with a named volumeA persistent volume, 1 GiB unless driver_opts.size sets another size. Orchard reads only the short string form. Two services cannot share a volume.
deploy.replicasThe replica count.
deploy.resourcesThe CPU and memory sizes.
commandThe start command.

Each service must have image or build.

Orchard does not apply these keys:

  • Bind mounts of host paths. For files that must persist, use a named volume or storage.
  • network_mode and other container networking settings.
  • depends_on. Services must tolerate a dependency that is unavailable when they start.
  • Build contexts that need files outside the repository.

Check each service after you deploy the stack.

Redeploying reads the compose file from GitHub again. A service that still exists keeps its app, along with its domains, volumes, and variable edits. Orchard creates or deletes apps only for services you added to or removed from the file.

  1. Open the stack from the project’s Compose tab.
  2. Select Redeploy.

To turn auto-deploy on or off, use Deploy on push to <branch> on the stack page.

Deleting a stack also deletes its services.

  1. Open the stack.
  2. Select More actions > Delete stack.
  3. Confirm the deletion.
You don't have access to this repository on GitHub. Connect your GitHub account or request access.

Cause: The repository is private, and your linked GitHub account cannot read it, or you have no linked GitHub account.

Fix: Link your GitHub account in Account settings > Connections, and make sure that account can read the repository. To deploy on push, also install the GitHub App on the repository’s account.