Update an existing installation

This page shows how to install a new version on servers that already run our product. This is an upgrade. Read the whole page before you start. An upgrade changes the customer’s database, and there is no way back except the database backup.

For the words used here, see Words you need to know.

What makes an installation an upgrade

This section explains the one field that decides an upgrade.

An installation is an upgrade, not a fresh install, for one reason only: you state which product version is already on the servers. You type it in the field Version already installed. Everything else follows from that field.

Nothing checks the number you type. This tool cannot read the version from a customer’s server. So this number is the most important input of the whole upgrade.
If the number is too low, the tool runs steps that already ran.
If the number is too high, the tool skips steps that the site needs.
Type the version as numbers with dots, for example 6.4.14. The tool reads the numbers at the start and ignores the rest. It refuses a value that does not start with a number, like latest, when you press Next →. The message is: "Dotted numbers, e.g. 6.4.14 — a version nothing can order selects no migrations at all."
An empty field means "this is a fresh install after all".

The costly mistake: leaving the field empty on servers that are not empty. Then the bundle does nothing about upgrades. The new services start on a database that nobody migrated.

Before you start

This section lists what you need before an upgrade.

The exact version that runs on the customer’s servers today. Ask the customer, or check the servers. Do not guess.
A maintenance window. If a migration step fails, there is no automatic way back. See The backup, and why there is no rollback.
Enough free disk on each database server for a full database backup. The tool checks this and stops if there is not enough.
If the customer runs their own database, a way to back it up yourself. This tool does not back up or migrate that database.
SSH access to the servers, or a way to carry the bundle to the site. See SSH access.

Steps: upgrade a site for the first time with this tool

This section shows how to create an installation for servers that already run our product.

Open the Installations tab.
Click + New Installation.
On Topology, type the Environment name and the Customer.
In Topology, pick the topology that matches the servers.
In Installation, choose Over an existing installation.
In Version already installed, type the version that the customer runs today, for example 6.4.14.
Click Next →.
On Instances, type the addresses. See Step 2. Create an installation.
Click Next →.
On Variables, pick the new release in Fill versions from a release.
Read what the new version changes. See what picking a new version changes.
Fill in every new required value. Then click Next →.
On Review & Generate, check the line at the top. It says Installing over an existing and the version.
Click Create installation.
Deploy the installation. See Installing over an existing install.

Steps: move an installation in this tool to a new release

This section shows how to update an installation that this tool already has.

Open the Installations tab.
Find the installation’s card and click Variables.
In Fill versions from a release, pick the new release.
Read what the new version changes. See what picking a new version changes.
Fill in every new required value.
Click Next →, then Save changes.
Click Deploy on the card. See Installing over an existing install.

Saving changes nothing on the servers. Only the deploy does.

What you see

This section explains what the tool does during an upgrade.

The review step shows this sentence: "Installing over an existing <version> — deploying this runs schema migrations against that installation’s database." The card shows a badge: over and the version.

Which migration steps run

This section explains which database migration steps the tool chooses.

The tool chooses every step, from any service, whose target version is newer than the version you typed.
It orders the steps by version, across all services.
It runs them before the services that need them start.

A redeploy where every step already ran takes no new backup. The plan still shows the number of steps. The run then says that each step is already applied, and skips it. This is normal. It is not a fault.

The backup, and why there is no rollback

This section explains the database backup.

There is no schema rollback. If a migration step fails, the database stays where the step stopped. The tool names the step and the file that failed. The server records the steps that already ran. So a new run continues from there and does not repeat them. The database dump is the only way back. Plan the maintenance window with this in mind.

Before the first step changes a database that this tool installs, the tool makes a backup (a dump):

One dump per database, not one per step. The tool takes it before the first step on that database. So the dump holds the state before the whole upgrade.
It stops if there is not enough disk. The tool measures the free space where the dump goes. It compares it with a size estimate from the database. If there is not enough space, no step runs. The tool says so.
A dump is accepted on four conditions. The dump finished. It is not empty. It ends with the marker that shows it is complete. Free space is left after it. If one condition fails, the tool deletes the dump and stops. So "The dump was rejected" always means that no migration ran.
Two dumps per database are kept. The tool removes older dumps by count, never by age. Copy a dump off the server if you need it after the next two upgrades.
The restore command is printed on the spot, for that server and that file. Important: the dump holds data, not accounts and grants. A migration that stopped half-way leaves any accounts that it created. A restore does not remove them.

A database that the customer runs is not backed up or migrated by this tool. The tool gives you its steps as SQL. You apply them. The deploy waits until someone confirms that the steps were applied. Take your own dump before you confirm. For that database, this tool has no backup and no rollback.

What happens to the files on the server

This section explains what stays on the server after an upgrade.

The tool copies the bundle over the existing install directory. It does not replace the directory. So the record of steps that already ran stays.

The environment files (.env) are merged, not replaced. The server keeps its own values and its secrets. New variables are added. For the details, see Installing over an existing install.

When a file changes, the old version is kept. You can swap it back. See Rolling back the .env. This covers configuration only, never the database schema.

Good to know

This section lists related pages.

A new version can add, remove or change variables. See what picking a new version changes.
A new version can move a service’s configuration files to another service. See when a version needs another service.
This tool cannot take over a site that it did not create. See a site that this tool did not create.

If something goes wrong

This section lists the refusals and failures of an upgrade.

These three refusals come before the tool generates anything. So nothing has been sent to any server when you see them:

Refusal What it means

Refusal	What it means
A step’s baseline has not been reached	A needed step requires a minimum version that this install has not reached. The refusal names both versions. The site must first go through its own upgrade path. You cannot skip the gap from here. The deploy preview shows this, before you type any secret.
No backup method is declared for a database	A step would run on a database that this tool installs, but nothing says how to dump it. The tool does not migrate a database that it cannot back up. It refuses to generate. The service’s contract has no `backup:` block. Ask the service owner to add it. Then sync the service contracts and try again.
The version needs a service this topology does not schedule	The new version moved a service’s configuration files to another service. That other service is not in the topology. The Variables screen names it before you save. Generation refuses in the same way.

A step’s baseline has not been reached

A needed step requires a minimum version that this install has not reached. The refusal names both versions. The site must first go through its own upgrade path. You cannot skip the gap from here. The deploy preview shows this, before you type any secret.

No backup method is declared for a database

A step would run on a database that this tool installs, but nothing says how to dump it. The tool does not migrate a database that it cannot back up. It refuses to generate. The service’s contract has no backup: block. Ask the service owner to add it. Then sync the service contracts and try again.

The version needs a service this topology does not schedule

The new version moved a service’s configuration files to another service. That other service is not in the topology. The Variables screen names it before you save. Generation refuses in the same way.