# Create an app from an image

Create an app that runs a container image from your registry or any public registry.

Replace my-app with your app's name and
`org-example1234.ecr.example.com/orders:1.4.2` with your image. Creating an app does not start
it; the first deployment does.

## Prerequisites

- Permission for `deploy:CreateApp`. The console's later steps need more: `deploy:ManageEnv` to
  save the environment, `deploy:ManageDomain` to attach the custom domain, and `deploy:DeployApp`
  for **Deploy immediately**. When one of them fails, the app is still created and the console
  lists what did not happen under **The app was created, but not everything landed.**
- An image reference: from your organization's registry, or any public image. An image in another
  private registry also needs a registry credential, which is set on the app after it is created;
  see [Pull from another registry](pull-from-another-registry.md).
- In the console, also `deploy:DescribeApp` to open **Apps** (without it the console shows **Access
  denied** and names that action).

## 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 container
   image**.
3. If your organization's registry has repositories, for **Image from**, choose **From your
   registry**, then choose the **Registry repository** and the **Tag** (resolved to a digest when
   the rollout starts); or choose **From somewhere else**. Otherwise only **Image reference** is
   shown. For an image from elsewhere, for **Image reference**, enter the reference.
4. Choose **Continue**.
5. On the **App, machine and domain** step, for **Name**, enter my-app. The **Subdomain
   label** follows the name until you change it.
6. For **Container port**, enter the port the container listens on. The field starts at `8080`,
   and at `80` for an official `nginx` or `httpd` image.
7. For **Machine size** and **Replicas**, choose what the app needs. More than 10 replicas is
   refused.
8. (Optional) For **Custom domain**, enter a hostname you own.
9. Choose **Continue**.
10. (Optional) On the **Environment** step, add variables, plain or bound to a secret.
11. (Optional) Under **Rollout**, clear **Deploy immediately** (selected by default) to create the
    app without deploying it.
12. Choose **Create and deploy**, or **Create app** when **Deploy immediately** is cleared. The
    app page opens.

**CLI**
```sh
dcloud deploy apps create --name my-app --builder image \
  --image-ref org-example1234.ecr.example.com/orders:1.4.2 \
  --ecr-repository-id 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9 \
  --port 8080 --instance-type performance-2 --replicas 1
```

`--ecr-repository-id` is the registry repository's id; leave it out for a public image. Without it,
the first deployment binds the app to the repository its image reference names in your registry.

**API**
```http
POST /deploy/api/apps
{
  "name": "my-app",
  "slug": "my-app",
  "builder": "image",
  "imageRef": "org-example1234.ecr.example.com/orders:1.4.2",
  "ecrRepositoryId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "port": 8080,
  "instanceType": "performance-2",
  "replicas": 1
}
```

**Terraform**
```hcl
resource "dcloud_app" "web" {
  name          = "my-app"
  builder       = "image"
  image_ref     = "org-example1234.ecr.example.com/orders:1.4.2"
  port          = 8080
  instance_type = "performance-2"
  replicas      = 1
}
```

The CLI, API and Terraform create the app without deploying it; deploy it as in
[Deploy an app](deploy-an-app.md). The request is refused with `409` when another app of the
organization has the same subdomain label (`An app with slug "my-app" already exists`), with `400`
without `imageRef`, and when the organization's app quota is used up.

## Result

The app is listed under **Apps** with its default URL,
`https://<app>.<organization>.apps.platform-development.deutschecloud.app`. With **Deploy immediately**, the first
deployment creates the machine, and you pay for it from then on.

## Related

- [Apps and sources](apps-and-sources.md)
- [Deploy an app](deploy-an-app.md)
- `deploy.apps.create` · `dcloud deploy apps create` · `dcloud_app`
