# Deploy your first app

Deploy a public container image, open it at its default URL, read what the deployment did, and delete it again, in about ten minutes.

The tutorial runs the public image `docker.io/library/nginx:1.27-alpine`, which listens on port 80. Replace app-id with the id the create step returns, and deployment-id with the
id the deploy step returns.

## Prerequisites

- Permission for `deploy:CreateApp`, `deploy:DeployApp`, `deploy:DescribeApp` and
  `deploy:DeleteApp`. The `AdministratorAccess` policy has them.
- For the CLI: `dcloud` installed and signed in.

**Important:**
The first deployment creates a machine, and you pay for it per started hour until you delete the
app in [Clean up](#clean-up).

## Step 1: Create the app

**Console**
1. Open **Apps**, then choose **Create app**.
2. Under **What to run**, choose **A container image**.
3. If your registry already holds images, for **Image from**, choose **From somewhere else**.
4. For **Image reference**, enter `docker.io/library/nginx:1.27-alpine`.
5. Choose **Continue**.
6. For **Name**, enter my-app.
7. For **Container port**, keep `80`. The console sets it for an nginx image; for another image,
   enter the port it listens on (the console's default is `8080`).
8. For **Machine size**, keep the default, then choose **Continue**.
9. Under **Rollout**, keep **Deploy immediately** selected. Cleared, the app is created without a
   deployment.
10. Choose **Create and deploy**. The app page opens and the first deployment starts.

**CLI**
```sh
dcloud deploy apps create --name my-app --builder image \
  --image-ref docker.io/library/nginx:1.27-alpine --port 80
```

The answer holds the app's `id`.

**API**
```http
POST /deploy/api/apps
{ "name": "my-app", "builder": "image", "imageRef": "docker.io/library/nginx:1.27-alpine", "port": 80 }
```

The answer holds the app's `id`.

## Step 2: Deploy it and wait

**Console**
1. Open the app's **Deployments** tab. **Activity** lists each step as it happens: the machine
   being created, the image pulled, the health check, the domain moved.
2. Wait until the status reads **Live**. A first deployment installs the machine and takes a few
   minutes.

**CLI**
```sh
dcloud deploy apps deploy app-id --wait
```

The command prints the deployment's activity as it happens and exits `0` once it is live.

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/deployments
{ "trigger": "manual" }
```

Then call `GET /deploy/api/deployments/deployment-id/wait?timeoutSec=55` until the answer
has `terminal: true`.

## Step 3: See it live

**Console**
1. On the app page, choose **Open**. The nginx welcome page loads at the app's default URL, over
   HTTPS.

**CLI**
```sh
dcloud deploy apps get app-id
```

The answer names the default URL. Open it in a browser.

**API**
`GET /deploy/api/apps/app-id` names the default URL; `GET
/deploy/api/deployments/deployment-id/events` returns the activity you saw in the console.

## Clean up

Delete the app so that its machine stops costing money.

**Console**
1. Open the app's **Danger zone** tab.
2. Choose **Delete app**, enter the app's name to confirm, and confirm. The app list shows it as
   deleting until everything it created is gone.

**CLI**
```sh
dcloud deploy apps delete app-id --yes
```

**API**
`DELETE /deploy/api/apps/app-id` answers `202` with `status: "deleting"`.

## Next steps

- [Create an app from a repository](create-an-app-from-a-repository.md)
- [Set environment variables](set-environment-variables.md)
- [Add a custom domain](add-a-custom-domain.md)
- [Deploy from GitHub Actions](deploy-from-github-actions.md)
