# Choose locations and scaling

> Run a deployment in one location, several or all of them, scale its instances with traffic, sleep when idle, and add workers and scheduled jobs.

Source: https://www.coritan.com/docs/managed-containers/locations-and-scaling/

In the dashboard:

- /dashboard/deployments/…/instances: https://www.coritan.com/dashboard/deployments

A deployment runs in the locations you choose, and each location runs its own *instances*: running copies of the current release, each the size of the plan you ordered. By default a deployment runs one instance in each location. The edge sends each visitor to the closest location that is serving, so running in several locations brings the deployment closer to its visitors and keeps it answering when one location has a problem.

A web service or a hybrid site can change its locations at any time, scale between a minimum and a maximum number of instances as traffic changes, and sleep when nobody is using it. A game server or a database keeps its own data in each location, and a static site answers from every location without instances ([How each kind runs](#how-each-kind-runs)).

## Before you begin

- The plan sets how many locations one deployment can run in: 1 on Free, 5 on Pro, and as many as you need on Business and Enterprise, up to 20. Scaling above the minimum needs Pro, Business or Enterprise ([Pricing](https://www.coritan.com/pricing)).
- Each instance is billed while it runs, at the price of the plan you ordered ([How App Deployment is billed](/docs/managed-containers/how-billing-works/)).

## Choose where it runs {#choose-locations}

1. Open the deployment and select the **Instances** tab.
2. Under **Locations**, select **Change locations…**.
3. Under **Where it runs**, choose **One location**, **Several** or **All locations**. **All locations** takes in every location that can run it, including locations we add later.
4. Set the **Instances per location**: the fewest the location keeps running, and the most it can scale to.
5. Turn on **Sleeps when idle** to let a location stop its instances when nobody uses it ([Sleep when idle](#sleep-when-idle)).
6. Select **Save locations**.

The current release starts in the locations you added straight away. Instances beyond a location's new count, and those of a location you removed, stop once another location is serving, so the deployment is never without an instance.

A location can run a minimum of up to 5 instances and a maximum of up to 10. A location with no room left for the plan is refused, and the error names it.

## Scale with traffic {#autoscaling}

A location scales when its maximum is above its minimum. Under **Scaling**, select **Change scaling…** to choose what one instance should carry:

- **Requests a second**: requests each instance should answer every second.
- **Requests at once**: requests each instance should be working on at the same time.
- **CPU**: how busy each instance's processor should be, as a share of its plan. Without any target, we scale to keep it at 70%.

The target that needs the most instances decides. A location adds instances when the load needs more than 10% above what it runs, at most once a minute. It removes them when one instance fewer would still carry the load at 80% of every target, at most once every five minutes and never more than half at once.

Instances above a location's minimum run only while your plan includes autoscaling, no spend limit is reached, and no allowance is used up on a deployment set to **Stop at the allowance** ([At a limit](/docs/managed-containers/how-billing-works/#at-a-limit)). When one is, every location goes back to its minimum until the limit is raised or the month turns. On a monthly commitment, instances above the ones you committed to are billed by the hour, as pay as you go is.

## Sleep when idle {#sleep-when-idle}

A location with **Sleeps when idle** turned on stops its instances once no request has reached them for the idle time: 15 minutes unless you set another under **Sleep after**, from one minute to seven days. A sleeping instance is not billed.

The next request wakes it. The edge holds the request for up to 25 seconds while an instance starts and passes its health check, then answers it as usual. If the instance is not ready by then, the visitor sees a page headed `This deployment is starting`, which reloads by itself after five seconds; an API client gets a `503` with `Retry-After: 5`. Use it for a deployment that can take a slow first answer, such as a staging copy or an internal tool.

Previews always sleep when idle. Workers and scheduled jobs never sleep, because no request comes to wake them.

## Add workers and scheduled jobs {#processes}

Besides the web instances that answer requests, a web service or a hybrid site can run other commands from the same release. Under **Processes**, select **Add process…** and choose its kind:

**Worker**
: A command that runs all the time, such as a queue consumer, with the number of instances to run in each location, up to 10. A worker has no address and no health check: it is healthy once it has kept running for 10 seconds, and we replace one that stops.

**Cron**
: A command that runs on a schedule, written as a cron expression such as `*/15 * * * *`. It runs in the deployment's first location, never twice at once, and is stopped after an hour.

**Web**
: The instances that answer requests. Give it a command only to run something other than the image's own start command.

Only production runs workers and scheduled jobs; previews run the web only. A worker or a scheduled job can read its process's name in `CORITAN_PROCESS`. A changed command reaches a scheduled job at its next run, and a worker when it next starts.

## How each kind runs {#how-each-kind-runs}

Web service or hybrid site
: Everything on this page applies. The web instances answer on the port in `PORT` and pass the health check before they serve: two good answers in a row from the health check path.

Game server or database
: One instance in each location you chose when you ordered it, each with its own files and databases. Its locations cannot change afterwards: to run it somewhere else, take a snapshot and start a new deployment from it in that location ([Start from a snapshot](/docs/managed-containers/order-a-server/#start-from-a-snapshot)). Its instances have their own tabs: select one on the **Instances** tab to open its console, files and the rest.

Static site
: No instances at all. The edge serves its files from every location ([Host a static site](/docs/managed-containers/static-sites/)).

## Result

The **Instances** tab lists every instance with its location, its release and its state, and the deployment's **Overview** shows each location's health, traffic and errors today.

## Troubleshooting

`These locations cannot run App Deployment instances now: ...`
: The locations it names have no room for this kind right now. Choose others; the answer lists the ones that can.

`A template deployment keeps its own data in each location, so it runs where you name: single or several`
: A game server or a database cannot use **All locations**. Choose **One location** or **Several**.

The deployment does not scale above its minimum
: Check that the location's maximum is above its minimum, that your plan includes autoscaling, and that no spend limit is reached. The **Instances** tab says until when bursts are held when a limit or an allowance was reached.

The first request after a quiet time is slow
: The location was asleep. Turn off **Sleeps when idle**, or set a longer **Sleep after**.

## Related

- [How App Deployment is billed](/docs/managed-containers/how-billing-works/) explains instance hours and monthly commitments.
- [Logs and metrics](/docs/managed-containers/logs-and-metrics/) shows each instance's output and each location's traffic.

## With the API

The routes are under `/api/v1/client/deployments/{uuid}` for your own deployment and `/api/v1/orgs/{org_slug}/deployments/{uuid}` for an organization's.

`GET /placements` answers where the deployment runs and the locations it could run in now. `PUT /placements` takes the same block as an order's `placement`: `mode` (`single`, `several` or `all`), `locations` with each location's `min`, `max` and `sleep` (`never` or `idle`), and `min`, `max` and `sleep` for every location it does not name:

```bash
curl -X PUT https://api.coritan.com/api/v1/client/deployments/$DEPLOYMENT/placements \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "several", "locations": {"fra": {"min": 1, "max": 3}, "iad": {"min": 1, "max": 1, "sleep": "idle"}}}'
```

A game server or a database answers `409` with `template_placement`. A static site takes only `{"mode": "all"}`.

`PUT /scaling` takes `{"autoscale": {"rps": 50, "concurrency": 20, "cpu": 70}, "sleep_after_seconds": 900}`; a key you leave out is cleared. `PUT /processes` replaces the whole list, each with `name`, `kind` (`web`, `worker` or `cron`), `command`, `instances`, `schedule` and `enabled`. `GET /instances` lists the running instances.

## API

- `GET /api/v1/client/deployments/{deployment_uuid}/placements`: Get placements (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-get-api-v1-client-deployments-deployment-uuid-placements)
- `PUT /api/v1/client/deployments/{deployment_uuid}/placements`: Change where a deployment runs (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-put-api-v1-client-deployments-deployment-uuid-placements)
- `GET /api/v1/client/deployments/{deployment_uuid}/instances`: The deployment's running copies (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-get-api-v1-client-deployments-deployment-uuid-instances)
- `GET /api/v1/client/deployments/{deployment_uuid}/processes`: Get processes (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-get-api-v1-client-deployments-deployment-uuid-processes)
- `PUT /api/v1/client/deployments/{deployment_uuid}/processes`: Replace a deployment's processes (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-put-api-v1-client-deployments-deployment-uuid-processes)
- `GET /api/v1/client/deployments/{deployment_uuid}/scaling`: Get scaling (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-get-api-v1-client-deployments-deployment-uuid-scaling)
- `PUT /api/v1/client/deployments/{deployment_uuid}/scaling`: Change a deployment's autoscaling (https://www.coritan.com/docs/api/reference/client/deployments/deployments/#op-put-api-v1-client-deployments-deployment-uuid-scaling)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements`: Get placements (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-placements)
- `PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/placements`: Change where a deployment runs (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-placements)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/instances`: The deployment's running copies (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-instances)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes`: Get processes (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-processes)
- `PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/processes`: Replace a deployment's processes (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-processes)
- `GET /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling`: Get scaling (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-get-api-v1-orgs-org-slug-deployments-deployment-uuid-scaling)
- `PUT /api/v1/orgs/{org_slug}/deployments/{deployment_uuid}/scaling`: Change a deployment's autoscaling (https://www.coritan.com/docs/api/reference/organizations/organization-deployments/deployments/#op-put-api-v1-orgs-org-slug-deployments-deployment-uuid-scaling)