Deploy and run
Regions and where your data lives
Choose the region a project's apps, databases and backups stay in, set a default for new projects, and see what CLI keeps centrally.
Each project can choose where its data lives, such as the United States or the European Union. Its apps, databases and backups then stay in that region, which keeps them close to your users and helps with data rules.
How to do it: choose under Where its data lives when you make a project, or change it later in the project's Settings (CLI moves everything for you, with a short pause).
"Make a new project in the EU."
Each project can choose a region, such as the United States or the European Union. Its apps, databases and their backups then stay in that region. Use it to keep data close to your users, or to meet a rule about where data is stored.
Pick a region
When you make a project: in the dashboard, choose under Where its data lives on the New project form. Agents pass region:
POST /v1/projects{ "name": "berlin-shop", "region": "eu" }The choice only appears when the server has more than one region open. GET /v1/regions lists them, each with its servers and whether it's open for new projects:
{
"home": "us",
"regions": [
{ "id": "us", "name": "United States", "home": true, "available": true },
{ "id": "eu", "name": "European Union", "home": false, "available": true }
]
}A default for new projects: under Account → Default region, or PUT /v1/me/region {"region": "eu"}. A project made without a region takes your default.
Environments (staging, previews) always use their project's region.
What stays in the region
Once a project has a region:
- Apps and databases run only on servers in that region. New services are placed on the region's least busy server that's answering. Moving a service to a server elsewhere is refused (
PATCH /v1/services/:id {"serverId"}answers that the server is in another region). - Volumes and database data are on those servers, so they're in the region too.
- Database backups go to that region's storage, and restores read them from there.
- Your own servers (see /docs/own-cloud) can run the project's services when they're labelled with the same region, like
euoreu-west.
If the region has no servers answering, deploys wait with a clear error instead of running somewhere else.
What CLI keeps centrally
Your account, members and roles, billing and the credit ledger, the activity log, and settings like variables are kept by CLI's control plane in its home region (for clicloud.app, the United States). Logs are read from the servers your services run on when you ask for them.
Change a project's region
The project's owner can change the region under Settings → Region, or with PUT /v1/projects/:id/region {"region": "eu"}. An empty project just switches.
A project with services moves: under Settings → Region, pick the region and See the plan, or send {"region": "eu", "move": true} (add ?dryRun=true to see the plan first). CLI then:
- Stops the project's apps, so nothing writes to its databases during the copy.
- Copies each database to the new region, as a new database named after it (
postgres-eu). - Points the apps at the copies (variables like
${{postgres.DATABASE_URL}}become${{postgres-eu.DATABASE_URL}}, and linked variables get the copy's URL) and deploys every app again in the new region.
The apps are down while the databases copy, so pick a quiet time. The original databases are stopped and kept, with their data, until you delete them; they can't be started in the new region. If a copy fails, CLI removes the copies, puts the project back in its old region and starts its apps again. GET /v1/projects/:id/region-move shows the latest move. Apps with a persistent volume can't move this way, because volumes aren't copied: detach the volume first. Each move is in the project's activity.
Projects without a region
Projects made before regions existed, and projects made without a region by someone with no default, run wherever CLI places them, as before. They show as being in the home region. Give one a region while it's empty to pin it.
For operators
The control plane's own machines are the home region, CLI_HOME_REGION (default us). Each platform server in CLI_SERVERS labelled with a region code (eu, ap, eu-west) adds that region. Labels that aren't region codes (like iad) don't. A region opens for new projects once it has servers and backup storage, set with CLI_REGION_STORAGE:
CLI_REGION_STORAGE='{"eu": {"bucket": "cli-backups-eu", "region": "eu-central-1"}}'Credentials default to CLI_S3_ACCESS_KEY_ID and CLI_S3_SECRET_ACCESS_KEY; each entry can set its own, and an endpoint for S3-compatible stores. CLI_REGION_NAMES names extra codes, for example {"me": "Middle East"}.