Linux Distribution Upgrade

If you ever need to upgrade your Matrix server’s host OS (distribution) from one major version to another, you can contact us and we will handle the upgrade for you for a one-time fee. We will take care of the entire process, ensuring your server is fully operational.

However, if you prefer to do it yourself at no extra cost, you can follow our guide for the process.

Ubuntu¶

Please use LTS (Long Term Support) versions of Ubuntu only. We recommend using the latest LTS version available at the time of installation.

1. Take a backup¶

Hosting customers: Daily backup (snapshot) is taken automatically every day, the backups are retained for 7 days, you don’t need to do anything.

On-premises customers: Make sure to back up your server before proceeding. All cloud providers have some kind of backup functionality and make snapshots either automatically or on-demand (manually).

2. Set up a fallback port¶

During the upgrade process, the SSH process on your host may be restarted and you may lose connectivity.

The upgrade process usually opens another fallback SSH port (1022) that may be used to get back to the upgrade process. Though the port will be opened automatically, you need to update your firewalls to allow incoming connections to this port.

Also, ensure the screen utility is installed on your system, and start a screen session before proceeding:

screen -S upgrade

If you lose connectivity during the upgrade, reconnect with screen -r upgrade. See resuming a screen session for details.

Hosting customers: the 1022 port is already open on the provider-level firewall, so you only need to update the on-server firewall:

ufw allow 1022/tcp

On-premises customers:

1. Update your provider-level firewall rules to allow connectivity to the 1022 (TCP) port, if you have one

2. Update the on-server firewall to allow incoming connections to the fallback port:

   ufw allow 1022/tcp
   

3. Update the system¶

Before performing the actual distribution upgrade, make sure your system is up-to-date:

# Update the package list
apt-get update
# Upgrade the system packages
apt-get dist-upgrade

You may reboot your server after this step, if prompted to do so.

4. Unpin Docker¶

We pin Docker to a specific version on your server to prevent accidental upgrades to a newer release that may not yet be compatible. Before performing the distribution upgrade, you must remove those pins — otherwise the upgrade process may fail to resolve package dependencies.

# Remove the apt-mark holds
apt-mark unhold docker-ce docker-ce-cli containerd.io docker-buildx-plugin
# Remove the apt-preferences block
rm -f /etc/apt/preferences.d/docker-ce-block

After the distribution upgrade is complete and you have run maintenance via Ketesa Server Actions, the pins will be re-applied automatically.

5. Upgrade to the new release¶

Finally, run the upgrade command:

do-release-upgrade

Follow the on-screen instructions — they are quite straightforward.

Note: if you are upgrading from an older LTS release (e.g., Ubuntu 20.04 while the currently supported LTS release is Ubuntu 24.04), you may need to repeat the process multiple times, as Ubuntu only supports direct upgrades between consecutive LTS releases. We recommend always upgrading to the latest LTS version available.

When doing a multi-hop upgrade, run maintenance after each intermediate release before continuing to the next one. Maintenance will re-pin Docker, so you will need to repeat step 4 (Unpin Docker) before each subsequent do-release-upgrade.

Post-upgrade steps¶

After the upgrade is complete:

1. Close the fallback port you opened in step 2:

   ufw delete allow 1022/tcp
   

2. Run maintenance via Ketesa Server Actions. This will:

   • Re-apply the Docker version pin
   • Update the Docker apt repository to reference the new distro codename (without this, apt may show errors or install unexpected Docker versions)
   • Ensure your server is fully reconfigured for the new OS release

If your Matrix server happens to be down after the upgrade, contact us and we will help you bring it back online.