Clusters

Several servers that act as one. When one stops, its apps move to another, with no click from anyone.

A cluster is several servers that act as one. If one stops, its apps move to another. Nothing of Kubernetes is involved.

  • You place an app or a database on the cluster, never on one of its servers. The cluster picks the server.
  • When a server stops answering, the cluster moves its work to another server. That is a failover. It needs no click.
  • Failover that does not depend on Deplo being up takes three servers or more. See How many servers.
  • Opt-in, and for experts. An app on a single server works exactly as before.

Creating and changing a cluster is for instance admins, under Settings -> Servers. Using one needs nothing new: the capability that places an app on a server places it on a cluster.

What a cluster gives you

You getHowRead
Apps that come back on another serverThe cluster's leader moves them after about 5 seconds of silence, and those with data after about 25 secondsWhen a server stops
Apps that reach each other by name on any serverThe servers share a private network, set up on their own, that keeps working while Deplo is downPrivate network
A domain that keeps its addressA domain on Cloudflare follows the app wherever it runsAddresses and Cloudflare
A database with a recent backup elsewhereEvery 15 minutes, on another server, set up for youDatabases
Replicas on several serversAn app with a Cloudflare domain spreads its replicasReplicas and mixed servers
Apps with a Volume that fail over tooReplication streams their data, and each database's changes, to the other servers as they happenReplication
Visitors shared between the serversLoad balancing sends each one to the nearest server, or the one with the most roomLoad balancing

Create a cluster

Open the Add dialog

Settings -> Servers -> Add, then pick Cluster ("Several servers as one") next to Server.

Name it and choose who can use it

A short name such as eu, up to 60 characters, unique on this Deplo. Then pick the teams, see below.

Add cluster

The cluster shows on the Servers page as a folder, and its leader starts on Deplo's own machine without being asked. There is nothing to install.

A cluster of one server is allowed. Inside it, a banner says Failover needs a second server: "With one server there is nowhere to move an App to. Drag another server onto this cluster."

How many servers

For failover that does not depend on Deplo being up, use three servers or more.

ServersFailover works
1Never: there is nowhere to move to
2Only while Deplo is up
3 or moreAlso while Deplo is down, as long as more than half of the servers are up and the leader runs on one of them. One of three may stop, two of five

When the second server joins, the toast says so: "Failover is on. With two servers it works only while Deplo is up."

If more than half of a cluster's servers are lost at once, the servers that are left stop their databases and their apps with a Volume within about half a minute, with Deplo up or not. Two copies of a database must never write at once, and the servers that are left cannot tell a stopped server from one they only cannot reach. See When a cluster is cut in two.

Let teams use it

A cluster is shared the way a server is: All teams, or Specific teams you tick. That is the list of teams allowed to place apps and databases on it.

  • Change it later from the cluster's menu, Manage: the name and the teams, then Save.
  • A team the cluster is not shared with does not see it in any picker, and is refused by the API: "That cluster isn't available to this team."
  • A team that still uses the cluster cannot be taken off the list: "These teams still have Apps or databases on this cluster: Acme. Move or delete them before taking the cluster away."
  • No new capability. Placing an app needs Create apps, moving one needs Configure apps. Moving an app off a cluster onto one server also needs Move & reorder apps. A database needs Create databases, or Configure databases to move it.
  • Nobody can place anything on one server of a cluster. Its servers leave every picker, and the API answers: "That server is a member of cluster eu, so nothing can be placed on it directly."

Turn failover off

Failover is on for every new cluster. To keep everything where it is when a server stops, turn it off:

  • Inside the cluster, the Failover switch beside its name.
  • On the Servers page, the cluster's menu, Turn failover off.

The toast says Failover off for eu, and Activity records Turned failover off for cluster eu. Instance admins only.

Off, nothing moves. A server that stops keeps its apps and databases until it comes back. The leader keeps nothing it could start them with, and the banners about failover go away. Apps waiting for room are still listed.

Turning it back on hands the leader everything again, with no redeploy.

Add a server

Drag the server onto the cluster's folder on the Servers page. Or, in the server's menu, Move to cluster, then the cluster's name.

A server that runs nothing joins at once: "server-b joined eu". One that runs apps or databases asks first, Move server-b into eu?: "2 Apps and 1 database on it move into the cluster too. They keep running without a restart." Then Move.

Joining moves nothing and changes no address: the apps and databases already on that server now belong to the cluster. Activity records Added server server-b to cluster eu with 2 apps and 1 database.

A server that just joined reads Provisioning until the cluster's leader answers for it, usually within seconds. It takes no work until then. The cluster's folder counts it: "2 servers · 1 provisioning".

A server that cannot join is greyed out in Move to cluster, and dropping it on the folder shows the reason:

It saysWhat to do
"server-b is offline. Bring it back online first."Wait for it, or fix it
"The server agent on server-b is too old to join a cluster. Deplo updates it on its own."Nothing to do: try again in a few minutes
"server-b is already in cluster us. A server is in at most one cluster."Remove it from the other one first
"server-b only keeps backups, so it can't run Apps."Pick a server that runs apps. The same goes for one that only builds images
"server-b runs work of Acme, which eu is not shared with. Share the cluster with them first."Share the cluster with that team, or move its apps away

Deplo's own server can join too, so a first cluster needs only one more machine. Read what that means for the leader first.

Put an app or a database on it

Every place that picks where something runs lists clusters next to servers, with a Cluster badge.

WhatWhere
A new appThe new app page, Deploy to
An app you already haveSettings -> General -> Server -> Move, then pick the cluster
A new databaseCreate database, the Server field
A database you already haveIts Settings -> General -> Server -> Move

Moving onto a cluster is an ordinary server move: the app is redeployed on the server the cluster picked and its data is copied across.

The Server card then reads Runs on eu · now on server-b. To get an app off the cluster and onto one machine you choose, Move it to a server. When the cluster is the only place your team can put the app, the line is still there, without a Move button.

How the cluster picks a server

Among the servers that are online, not being removed, able to run the app's image and with room for it, the cluster prefers, in this order:

  1. a server already running a database of the app's environment
  2. a server running none of the app's other replicas
  3. the server with the most memory left
  4. the server running the fewest things

Room is the app's or database's memory limit. Without a limit it is its memory peak of the last 24 hours, and never less than 256 MB. Nobody can pin an app to one server of a cluster.

When there is no room

The move or deploy is refused before anything stops:

  • "No server in cluster eu has 512 MB free. Add a server to it or lower web's memory."
  • "No server in cluster eu is online and ready right now, so web has nowhere to run. Bring a server back or add one."

On the Servers page

Settings -> Servers shows each cluster as a folder, next to the servers that are in no cluster. A server of a cluster is found inside its folder.

The folder shows the cluster's name, how many servers it has ("2 servers · 1 provisioning") and a warning sign when a banner inside needs you. Its menu has Open, Manage, Turn failover off, Turn replication on and Delete.

Open it to see its servers. The top line reads Servers / eu, with the Failover, Replication and Load balancing switches and a menu with Manage and Delete. Each server shows its status, and Leader on the one the leader runs on.

The banners

Above the servers, one banner per thing to know. Deplo checks the leader every 30 seconds in the background, so the page never waits on a server.

BannerIt says
2 Apps waiting for room"web, api. Deplo tries again every 30 seconds." See Waiting for room
Failover needs a second serverShown with one server
Failover is not working right nowThe leader does not run, or too few servers answer it. See The leader
Deplo's own machine leads this cluster"Until server-b answers again." See When the leader's server stops answering
Failover may stop workingA leader update that failed, a refused Cloudflare token, or the leader on Deplo's own server
Failover is not ready for 1 App yet"Their latest version is still being copied: web on 2 of 3 servers."
Replication is not ready for 1 App yetNo whole copy of its data is on another server yet. See Replication
Replication is behind for 1 AppA server's copy stopped following, and why

These version copies are made on their own: an app Deplo built is copied to the other servers after each build, so any of them can start it; an app that runs a pulled image needs no copy. A copy that failed while a server was away is retried every 2 minutes. They copy what an app runs, not what it stores: that is replication.

With failover off, only the first banner is shown.

What a cluster does not do

  • Deplo itself does not fail over. If Deplo's own machine is lost, see Disaster recovery. The apps on the other servers keep running.
  • A domain that is not on Cloudflare does not follow the app. See Addresses and Cloudflare.
  • A pull request preview never fails over.
  • Replicas are not added under load, and an image is not built for both ARM and x86.
  • Over MCP, a cluster's replication and load balancing are the only things that change. An instance admin's AI agent turns them on or off (set_cluster_replication, set_cluster_load_balancing). Any agent can read clusters (list_clusters, get_cluster) and place an app or a database on one (move_app_to_cluster, move_database_to_cluster, and clusterId on create_app_from_template).

In this section

Did this page help you?

On this page