Create an app from a compose file

Create an app that runs every service of a docker-compose file, with one of them published through the app's domain, and edit the file later.

Last updated 18 November 2026View as Markdown

The file is pasted, or read from a path in a connected repository. Replace my-app with your app's name. What the file may contain is in Compose files.

Prerequisites

  • Permission for deploy:CreateApp; to edit the file later, deploy:UpdateApp; to deploy, deploy:DeployApp.
  • Every image in the file already built and pushed: a compose build: section is refused.
  • Images from your organization's registry come from one repository only, which must exist: the app is given a pull credential for that repository (400, No repository called "…" in … or This file pulls … and … from …).
  • In the console, also deploy:DescribeApp to open Apps (without it the console shows Access denied and names that action).

A minimal file that runs a web service with a Postgres beside it:

services:
  web:
    image: org-example1234.ecr.example.com/orders:1.4.2
    depends_on: [db]
  db:
    image: docker.io/library/postgres:17-alpine
    environment:
      POSTGRES_USER: orders
      POSTGRES_PASSWORD: orders
      POSTGRES_DB: orders
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

Create the app

  1. Open Apps, then choose Create app.
  2. On the What to run step, under Where does this app come from?, choose A compose file.
  3. Under Where is the compose file?, choose Paste it here and paste the file into Compose file (Insert an example fills in a web service with a Postgres), or choose Read it from a repository, choose the Repository and enter the Path (default docker-compose.yml).
  4. For Published service, enter the service reachable from outside (web above).
  5. For Its port, enter that service's container port (the field starts at 8080).
  6. Choose Continue and complete the App, machine and domain and Environment steps as in Create an app from an image. The compose app has no Container port field: the published service's port is used.
  7. Choose Create and deploy, or, with Deploy immediately cleared, Create app. A pasted file with problems is refused before anything is created, each message naming the key and the line. A file read from a repository is checked when a deployment reads it, and a problem fails that deployment.

The CLI, API and Terraform create the app without deploying it; deploy it as in Deploy an app. A file with composeSource git needs gitRepositoryId and composePath; the request is refused with 400 otherwise.

Edit the compose file

Open the app's Runtime tab, change the file under Compose file, and choose Save compose file; or send composeFile with PATCH /deploy/api/apps/{id}. Saving validates the file and stores it on the app; the running deployment is unchanged until you deploy again. A file read from a repository is changed in the repository. Each deployment pins a copy of the file (from a repository, the file at one commit).

Result

Every service in the file runs on each of the app's machines, on one app network. Only the published service is reachable from outside, through the app's domains.

Did this page help you?