# Change or delete an app

> Change an app's name, build, size, regions or replicas, see which changes need a new deployment, and delete an app you no longer need.

Source: https://docs.coritan.com/apps/app-settings/

In the dashboard:

- /dashboard/apps/…/settings: https://www.coritan.com/dashboard/apps

You can change most of an app's settings after you create it, on the app's **Settings** tab or through the API. Some changes apply at once, and others reach the running replicas only with the next deployment or the next build. The app's source type and its name on the platform stay as you created them.

## Before you begin

- For an organization's app, you need the owner or admin role in the organization.
- To delete an organization's app from the staff console, you need to have confirmed it is you in the last 10 minutes ([Confirm it is you](/organizations/staff-console/sign-in/#confirm-it-is-you)).

## Change the settings

1. Open the app from **Apps** in the [dashboard](https://www.coritan.com/dashboard/apps) and select the **Settings** tab.
2. Change the fields on one card. Its foot counts what you changed, such as `2 changes to save`, and **Discard** puts the fields back.
3. Select **Save changes** on that card.

A message confirms the save, such as `Run settings saved.` Each card saves only its own fields, so save each card you change. The rules for each value are the same as when you create an app ([What you choose](/apps/create-an-app/#what-you-choose)).

**General**
: **Name**. **Name on the platform** is shown but cannot change.

**Source**
: For a git app, **Repository**, **Branch**, **Directory** and **Access token**. For an image app, **Image**.

**Build and start**
: For a git app, **Framework**, **Dockerfile**, **Install command**, **Build command** and **Start command**.

**Run**
: **Port**, **Health check path** and **Size**.

**Regions and replicas**
: **Every region** or **The regions I choose**, and **Replicas per region**.

**Push webhook**
: For a git app, the address and secret that let pushes deploy it ([Deploy on every push](/apps/push-webhook/)).

**Delete this app**
: Deleting the app ([Delete an app](#delete-an-app)).

A few fields work differently:

- To replace the access token of a private repository, type the new one in **New access token**. To remove it, tick **Remove the saved token**. We never show a token, and the field's hint shows its last four characters.
- To clear the directory, the Dockerfile, the framework or a command, empty its field.
- To run the app in every region again, choose **Every region**.

Changes to environment variables have their own tab ([Set environment variables](/apps/environment-variables/)), and so do custom domains ([Add a custom domain](/apps/custom-domains/)).

## When a change applies

| Setting | When it applies |
| --- | --- |
| Name | At once. It is a label and changes nothing that runs. |
| Health check path | At once. The next health check of every replica uses it. |
| Repository and branch | At once for the push webhook, which then deploys only pushes to the new branch and repository. At the next build for the running app. |
| Directory, access token, Dockerfile, install, build and start commands | At the next build. |
| Image, for an app that runs an image | At the next deployment of the new image. |
| Size, regions, replicas per region | At the next deployment. A redeploy is enough. |

After a save that needs a new deployment, a note under the app's header says which kind: `A redeploy applies the saved changes`, `A new build applies the saved changes`, or for an image app `The new image is not running yet`. Its **Redeploy…** button starts the redeploy, with **Build the branch again** or **Pull the image again** ticked when the change needs it ([Redeploy](/apps/deploy-an-app/#redeploy)). A plain redeploy of an image app runs the image that is running now, so after changing the image, pull it again or deploy it.

A change to the port also asks for a redeploy, and a change to the framework for a new build. Neither setting changes how the app runs: replicas listen on the port in their `PORT` variable ([What your app must do](/apps/how-apps-work/#what-your-app-must-do)), and the build does not read the framework.

> [!WARNING]
> A new health check path applies to the running replicas at their next check. Change it only when the running version answers on the new path, or its replicas fail their checks and we start to replace them.

## A suspended app

We can suspend an app. Suspending it cancels its deployments on their way, stops its domains reaching it and stops its replicas. Its `status` is then `suspended`, and the app's page shows `This app is suspended` with an **Open a ticket** button.

While an app is suspended, you can read it, change its settings and delete it. **Deploy…** and **Redeploy…** are turned off, no deployment offers **Roll back to this…**, and the API answers `409` with `The app is suspended; it cannot deploy`. The push webhook ignores pushes. When we resume the app, its current deployment starts again. Open a ticket, or [contact support](/support/conversations/), to find out why an app was suspended.

## Delete an app

> [!CAUTION]
> Deleting an app cannot be undone. Save anything you need from it, such as its environment variables, first.

Deleting an app does all of this:

- Cancels its deployments on their way.
- Removes its platform name and custom domains, with their routes and certificates, so visitors can no longer reach it.
- Stops its replicas and removes them.
- Erases its environment variables, its access token and its push webhook secret.
- Frees its name on the platform, so another app can take it.

To delete it in the dashboard:

1. On the app's **Settings** tab, go to **Delete this app** at the bottom and select **Delete app…**.
2. Type the app's name on the platform, as the dialog shows it, such as `web-shop`. Case and spaces around it do not matter.
3. Select **Delete app**.

A message confirms `Web shop deleted.`, and the **Apps** list opens. Through the API, you can also give a reason of up to 500 characters, which goes into the audit log with the deletion.

For an organization's app, only an owner or admin can delete it. From a staff console session, they also need to have confirmed it is them in the last 10 minutes. A request made with the member's own Coritan access token needs only the typed name.

## Result

After a save, the card shows the new settings. Settings that need a new deployment or build apply once you start one.

After you delete an app, it no longer appears in your apps, and a request for it answers `404` with `App not found`. Its domains stop reaching it at once.

## Troubleshooting

`Could not save the changes`
: We refused the change, and the reason is under this heading or under the field. The messages below are the common ones.

`SYD takes no new replicas`
: A region the app asks for no longer takes new replicas, so the next deployment fails. Untick it, or choose **Every region**, and save.

`Type the app's name, web-shop, to confirm`
: The name you typed is not the app's name on the platform. Type it as the message shows it.

`Confirm your password or a code from your authenticator to do this.`
: The staff console session has not confirmed it is you in the last 10 minutes. Confirm it, then delete the app again.

`Admin access required`
: Only an owner or admin of the organization can change or delete its apps.

`image_ref is for apps that run an image; this app builds from git`
: A git app cannot switch to an image, or back. Create a new app with the other source.

`'release 2' is not a branch name git accepts`
: A branch name cannot have spaces and some other characters. Check the branch's name at your git host.

`These regions cannot run apps: syd`
: A region you chose cannot run apps now. Choose from the regions the platform offers ([Regions, sizes and limits](/apps/#regions-sizes-and-limits)).

`min_replicas must be between 1 and 5`
: Choose from 1 to 5 replicas in each region.

`Too many changes to apps. Wait a while and try again.`
: You made 120 changes to apps in the last hour. Wait, then try again ([Requests](/apps/limits/#requests)).

## Related

- [Deploy an app](/apps/deploy-an-app/#redeploy)
- [Set environment variables](/apps/environment-variables/)
- [App and deployment fields](/apps/fields/)
- [Organization roles and permissions](/organizations/roles-and-permissions/)

## With the API

### Change settings through the API

[`PATCH /api/v1/client/apps/{app_uuid}`](/api/reference/client/apps/#op-patch-api-v1-client-apps-app-uuid) changes an app's settings. For an organization's app, send it to [`PATCH /api/v1/orgs/{org_slug}/apps/{app_uuid}`](/api/reference/organizations/organization-apps/#op-patch-api-v1-orgs-org-slug-apps-app-uuid). Send only the settings you change.

```bash
curl -X PATCH https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_branch": "production", "instance_size": "medium", "min_replicas": 3}'
```

The body takes the fields of [the create request](/apps/create-an-app/#with-the-api) except `slug`, `source_type`, `env` and `deploy`. Sending one of those answers `422` with a field error whose `type` is `extra_forbidden` ([A list of field errors](/api/errors/#a-list-of-field-errors)).

- A new `repo_token` replaces the token, and an empty one removes it. The app's `repo_token_hint` shows the last four characters of the token it holds.
- An empty `repo_subdir`, `dockerfile_path`, `framework`, `install_command`, `build_command` or `start_command` clears it.
- An empty `health_check_path` sets it to `/`.
- `["*"]` or `null` as `regions` sets them to every region.
- A `max_replicas` below the new `min_replicas` is raised to it.

It answers with the app and what changed:

```json
{
  "app": {
    "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
    "repo_branch": "production",
    "instance_size": "medium",
    "memory_mb": 1024,
    "cpu_percent": 200,
    "disk_mb": 4096,
    "min_replicas": 3,
    "max_replicas": 3
  },
  "changed": ["cpu_percent", "disk_mb", "instance_size", "max_replicas", "memory_mb", "min_replicas", "repo_branch"],
  "redeploy_required": true,
  "rebuild_required": true
}
```

The example shortens `app`, which carries every field ([App and deployment fields](/apps/fields/)). `changed` lists the fields whose value changed, and names a new or removed token as `repo_token`. A size sets `memory_mb`, `cpu_percent` and `disk_mb` with it.

`rebuild_required` is `true` when the change reaches the app only through a new build, so [redeploy with a rebuild](/apps/deploy-an-app/#redeploy) or push a commit. `redeploy_required` is `true` when a new deployment of the current image is enough, so a plain redeploy applies it. After changing an app's image, redeploy with a rebuild or deploy the image, because a plain redeploy runs the image that is running now. `redeploy_required` is also `true` after a change to the port, and `rebuild_required` after a change to the framework.

| Status | `detail` | Cause |
| --- | --- | --- |
| `404` | `App not found` | The app belongs to someone else, or does not exist. |
| `422` | `repo_url is for apps that build from git` | An app that runs an image was sent a repository field. |
| `422` | `image_ref is for apps that run an image; this app builds from git` | A git app was sent `image_ref`. |
| `422` | `{"message": "These regions cannot run apps: syd", "unavailable": ["syd"], "available": ["fra", "iad"]}` | A region in `regions` cannot run apps now. |
| `422` | `min_replicas must be between 1 and 5` | `min_replicas` is out of range. |
| `429` | `{"error": "rate_limited", "message": "Too many changes to apps. Wait a while and try again.", "retry_after_seconds": 3600}` | You made 120 changes to apps in the last hour. |

### Delete an app through the API

[`DELETE /api/v1/client/apps/{app_uuid}`](/api/reference/client/apps/#op-delete-api-v1-client-apps-app-uuid) deletes an app. Give the app's name on the platform as `confirm`, and a reason as `reason` if you like. For an organization's app, send it to [`DELETE /api/v1/orgs/{org_slug}/apps/{app_uuid}`](/api/reference/organizations/organization-apps/#op-delete-api-v1-orgs-org-slug-apps-app-uuid).

```bash
curl -X DELETE "https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21?confirm=web-shop&reason=Moved%20to%20a%20new%20app" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "deleted": true,
  "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
  "slug": "web-shop",
  "routes_removed": ["web-shop.apps.example.net", "www.example.com"]
}
```

`routes_removed` lists the hostnames that stopped reaching the app.

| Status | `detail` | Cause |
| --- | --- | --- |
| `403` | `Admin access required` | The member is not an owner or admin of the organization. |
| `403` | `{"error": "reauth_required", "message": "Confirm your password or a code from your authenticator to do this.", "max_age_seconds": 600}` | A staff console session has not confirmed it is you in the last 10 minutes. |
| `404` | `App not found` | The app belongs to someone else, does not exist, or is deleted already. |
| `422` | `{"error": "confirm_mismatch", "message": "Type the app's name, web-shop, to confirm"}` | `confirm` is not the app's name on the platform. |
| `429` | `{"error": "rate_limited", "message": "Too many changes to apps. Wait a while and try again.", "retry_after_seconds": 3600}` | You made 120 changes to apps in the last hour. |

## API

- `PATCH /api/v1/client/apps/{app_uuid}`: Change an app's settings (https://docs.coritan.com/api/reference/client/apps/#op-patch-api-v1-client-apps-app-uuid)
- `DELETE /api/v1/client/apps/{app_uuid}`: Delete app (https://docs.coritan.com/api/reference/client/apps/#op-delete-api-v1-client-apps-app-uuid)
- `PATCH /api/v1/orgs/{org_slug}/apps/{app_uuid}`: Change an app's settings (https://docs.coritan.com/api/reference/organizations/organization-apps/#op-patch-api-v1-orgs-org-slug-apps-app-uuid)
- `DELETE /api/v1/orgs/{org_slug}/apps/{app_uuid}`: Delete app (https://docs.coritan.com/api/reference/organizations/organization-apps/#op-delete-api-v1-orgs-org-slug-apps-app-uuid)