Enhance Documentation

# Upgrading from version 11.0.x

# Overview

Enhance 12.0.0 was an almost complete rewrite of the software which powers the control panel, moving the remaining legacy Docker services to apt and systemd. Therefore the upgrade procedure from earlier versions is more complex than normal.

TIP

We offer support 9AM to 9PM UK time. It's best to upgrade during these hours in case you need any assistance.

# Prerequisites

Before beginning the upgrade process, please ensure that you:

  • Check your backups. Any data loss is unlikely but not impossible.
  • Run apt update && apt upgrade on every cluster member to update all o/s packages. If your kernel package was updated, reboot into the new kernel.
  • Ensure you have Enhance version 11.0.4, under settings->platform. Upgrades from earlier versions to 12.0.x are not supported.
  • Ensure that every server has at least 5GB free disk space.
  • Important check that all servers in your cluster are online and showing green in the Enhance panel. Any offline servers should be decommissioned and deleted.
  • Important if you rely on any 3rd party addons for Enhance, verify compatibility with Enhance 12.0.0 before updating Enhance.
  • If any of your servers have an external firewall (running outside of Enhance), make sure that it allows ports 50000, 50001, 50002, 50003 between the servers in your cluster. For example, the web server needs to be able to connect to the database server, the email server needs to be able to connect to the backup server, etc.

# Beginning the update process

WARNING

It is very important that these steps are followed in the exact order. Most issues with the upgrade process come from steps being missed.

  1. On your control panel server, run:
apt update
apt-get install -y ecp-core orchd ecp-filerd
v12-upgrade upgrade-panel-from-v11
v12-upgrade upgrade-app-server

Wait for each command to finish before proceeding.

  1. On every other server in your cluster, run:
apt update
apt install -y ecp-core ecp-filerd

Wait for each command to finish before proceeding.

  1. On your control panel server, run:
v12-upgrade replace-all-cluster-appcd-certs
v12-upgrade replace-all-filerd-certs
v12-upgrade convert-all-bkupds
v12-upgrade convert-all-mysql

Wait for each command to finish before proceeding.

  1. On every server with the application role or the email role, run:
v12-upgrade upgrade-app-server
  • This step will replace your running web server with the corresponding version from the official package vendor for your chosen web server variant.
  • You may need to replace any custom configuration that you have applied.
v12-upgrade convert-all-ftps

Wait for each command to finish before proceeding.

  1. On every server with the database role, run:
v12-upgrade upgrade-mysql

WARNING

In the unlikely event that you have /var/local mounted separately from /var, please contact support before running the above command.

Wait for each command to finish before proceeding.

This step will replace the running MySQL Docker container with the corresponding version from the official package vendor for your chosen database variant.

  • MySQL 8.0 will be upgraded to the latest 8.0.x release
  • MySQL 8.1 will be upgraded to the latest 8.4.x release
  • MariaDB 10 will be upgraded ot the latest MariaDB LTS release
  • MariaDB 11 will be upgraded to the latest MariaDB rolling stable release

Wait for each command to finish before proceeding.

You may need to re-apply any my.cnf customisations.

  1. On every server with the DNS role, run:
v12-upgrade convert-dnscd

Wait for each command to finish before proceeding.

  1. On your control panel server, run:
v12-upgrade convert-all-dns-zones
v12-upgrade update-all-website-backup-locations

Wait for each command to finish before proceeding.

  1. If you are using the central webmail feature, on your control panel server run:
cat /var/local/enhance/orchd.json | jq -r '.email_secret.secret'

Next, find your central webmail website in the websites list (it will have a WML tag) and open the file manager. Edit public_html/config/config.inc.php and change the value of $config['orchd_key'] to the output of the above command.

This is not required for the webmail which runs on each web server at mail.customerdomain.

# System generated emails

System generated emails (forgotten passwords and user invites) are no longer sent through a separate MTA, they are sent through the system MTA (via Postfix's sendmail drop-in). They will obey any smart host settings configured on the control panel server.

# Troubleshooting

  • If any of the above steps return a fatal error, please contact support through your my.enhance.com (opens new window) account.
  • If you see a white page in your Enhance UI, clear your browser cache.

# Optional cleanup

  • On every backup server, run:
    • docker stop bkupd bkupfilerd
  • If you are not running any Docker containers outside of Enhance, you can now run:
    • systemctl disable docker
    • apt-get remove docker-ce

WARNING

Do not remove Docker unless all previous steps have been completed successfully.

# Ongoing updates

  • It is now possible to update your entire system with apt update && apt upgrade.

← Users and Roles →