# 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.

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](compose-files.md).

## 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:

```yaml
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

**Console**
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](create-an-app-from-an-image.md). 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.

**CLI**
```sh
dcloud deploy apps create --name my-app --builder compose \
  --compose-source inline --compose-file "$(cat compose.yaml)" \
  --compose-service web --compose-port 3000
```

**API**
```http
POST /deploy/api/apps
{
  "name": "my-app",
  "builder": "compose",
  "composeSource": "inline",
  "composeFile": "services:\n  web:\n    image: docker.io/library/nginx:1.27-alpine\n",
  "composeService": "web",
  "composePort": 80
}
```

**Terraform**
```hcl
resource "dcloud_app" "web" {
  name            = "my-app"
  builder         = "compose"
  compose_source  = "inline"
  compose_file    = file("compose.yaml")
  compose_service = "web"
  compose_port    = 3000
}
```

The CLI, API and Terraform create the app without deploying it; deploy it as in
[Deploy an app](deploy-an-app.md). 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 `deploy.apps.update`. 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.

## Related

- [Compose files](compose-files.md)
- [Configure the release command and health checks](configure-release-and-health-checks.md)
- `deploy.apps.create` · `dcloud deploy apps create` · `dcloud_app`
