# Where services run

This page explains how Alf decides which servers a service runs on, what makes it move, and what doesn't. You choose a service's regions under **Scaling**: it runs one instance in each. See [Choosing regions](/docs/servers#choosing-regions) for how.

## The short version

- **One instance, one server.** A service runs on as many servers as it has instances, never two instances on the same server.
- **One instance in each region you pick.** Kept to Europe and the US, a service runs once in each; **Anywhere**, once, where Alf picks. Through the API or alf.toml it can also say a number of instances to spread, or how many each region runs (below).
- **What runs stays where it is.** A service moves only when you change it, when its server goes offline, or when the operators move or remove a server.

## Which servers it can use

A server is a candidate for a new instance when all of these are true:

- **It's yours or shared.** Once your organization has [private servers](/docs/servers#private-servers), your services run only on those.
- **It's in the service's regions**, if you chose any.
- **It's in the project's network zone.** A project's services share a [private network](/docs/networking), so they all run on servers that can join it.
- **It's online.** A server is online when it has reported in the last minute.
- **It has room.** It's not [full right now](/docs/capacity#when-a-server-is-full), and the sizes it has given out leave room for this one's, and for its volumes' sizes on its disk. (A service that sleeps counts as a share of its size, since most are asleep most of the time; one that never sleeps counts in full.) A full server only takes an instance to stand in for one that was lost (see below).
- **The service isn't on it already.**

## Which one it picks

Among the candidates, Alf goes down this list until one server is left:

1. **The region of the instance it replaces.** When an instance is lost because its server went offline, the replacement goes to that server's region.
2. **A region the service isn't in yet**, so instances spread over regions.
3. **A server the project's other services already run on**, so they reach each other on the same machine.
4. **A country the service isn't in yet.**
5. **The server with the fewest services**, then the one with the least CPU in use.

Steps 2 and 3 swap places depending on the regions:

- **Anywhere** (no regions chosen): staying near the project's other services comes first. A two-instance service whose database is in Europe runs both instances there if there's room, rather than one across the ocean.
- **Kept to several regions:** spreading over them comes first. You chose those regions to be run in.

## How many in each region

A service can say how many instances each region runs: two in Europe, where most visitors are, and one in the US (`region_instances` in the API, as in alf.toml). Picking regions under **Scaling** is one in each; the service's instances are the sum.

- Each region is placed on its own, with its own count, by the rules above. A lost instance is made up for in its region, and only there: a count is where you asked for it to run.
- A region runs at most as many instances as it has servers (each runs on a server of its own), and a service at most 10 in all. Asking for more is refused, and nothing changes.
- A region with fewer servers that can take it than its count runs fewer. **Scaling → Where it runs** shows each region with how many run there against how many it wants, and the card on the canvas has a dot for every instance (a hollow one for each it wants and hasn't got).
- Choosing regions again without counts, or a plain number of instances, lets the counts go: its instances are spread over its regions by themselves again.

## Every case

| What happens | What moves |
| --- | --- |
| **You create a service** | It's placed by the rules above. If no server it may use has room, creating it is refused and nothing is made. |
| **You raise its instances** | New instances are added by the rules above; the ones running stay. If every server it could still go to is full, the change is refused. If there are fewer servers than instances, it runs on all of them and takes the next one that joins. |
| **You pick fewer regions** | The instances in the regions you took away stop; the others stay. |
| **You change its regions** | Instances outside the new regions move into them. If a region you added has none of its instances and another region has two, one moves over. Otherwise nothing moves. |
| **You set it back to Anywhere** | Nothing moves. |
| **Its server goes offline** | After about a minute without a report, each lost instance is replaced, in the same region if a server there can take it (a full one stands in if needed), else in another of its regions. If nothing can take it, it stays on its server and starts again when that's back. |
| **That server comes back** | Nothing moves back. The server drops the copies it no longer runs. |
| **A server is full** | It takes nothing new, and what runs on it keeps running. It may stand in for an instance lost elsewhere: that's what the room it keeps is for. |
| **No server in its regions can take it** | It runs on fewer servers than it wants, or, with none, shows **No server yet**. It gets one by itself as soon as one can take it. |
| **A server joins** | Nothing moves. Services that are short of servers, or have none, take it if it suits them. |
| **The operators retire a server** | Everything on it moves to the closest server with room that it may use (in its regions, if it's kept to some), before the server goes. A service without a volume moves at once; one with a volume, a database or a computer moves [with its data](#services-with-a-volume): stopped for the copy, started there, and you're told. Nothing new goes to a server that's being retired. |
| **The operators move a server to another region** | Services kept to its old region leave it. Others stay. |
| **The operators rename or merge a region** | Services kept to it are kept to the new one, and stay where they are. |
| **Traffic rises** | [Replicas](/docs/scaling#under-load-more-containers) start more containers on the servers it's already on. When those are full, [another server in the same region](/docs/scaling#when-its-servers-are-full-another-server-in-the-region) runs it too until the load is gone. Load never adds regions. |
| **It sleeps, wakes or is deployed** | It stays on the same servers. |

## Services with a volume

A service with a [volume](/docs/volumes) keeps its data on one server's disk, so it runs on one server and stays there. That includes databases and computers.

- **When the server goes offline,** it waits for that server instead of moving by itself: elsewhere its data wouldn't be there.
- **It runs in one region.** Choosing several is refused.
- **Choosing another region moves it there with its data**, to a server picked there with the room for it. Under **Scaling → Regions**, or `alf move shop/db Europe`:
  1. It's stopped, so nothing is written while its data is copied.
  2. Each volume is snapshotted, with a copy off the server; for a computer, everything installed in it too.
  3. It's put on the new server, and its data is put back there.
  4. It starts, and the old server deletes the volume it left.

  It's down for as long as that takes: a few minutes for a small volume, longer for a big one. The service's page shows each step. If something goes wrong before it runs on the new server, it stays where it was and runs again there.
- **If its server is away** (offline for good, say), choosing another region moves it with its data as it was in each volume's newest copy off the server, and says how old that is. Without such a copy, it moves only if you ask it to move without its data, and starts empty. Copies off the server, on a [schedule](/docs/backups#on-a-schedule), are what make a lost server a short outage rather than lost data.

## Which instance visitors reach

With several instances, a visitor's request goes to the nearest instance that's awake. A sleeping instance that's much closer (more than about 1,500 km nearer) is woken instead. If the first one doesn't answer, the next nearest is tried.

## Examples

**Europe and the US, one instance.** It runs on one server, in Europe or the US: near the project's other services, else on the least busy server. If that server goes offline, it moves to another server in the same region. It moves to the other region only when no server in its own can take it.

**Europe and the US, two instances.** One runs in Europe and one in the US. If the European server goes offline, the replacement goes to another European server, even when the US has an emptier one.

**Europe and the US, two instances, then only Europe.** The US instance leaves, and a second European server takes it. With only one server in Europe, it runs there once and takes the next European server that joins.

**Anywhere, two instances.** It runs on two servers near the project's other services, in different countries when that's possible. A third region added later changes nothing.