# Control Panel Migration

# Introduction

This guide will help you to migrate your control panel role to new hardware. It is intended for experienced systems administrators only.

If you have difficulties or concerns, please contact support.

WARNING

These instructions are intended for Enhance v12 and above. If you are running an earlier version, you must update your cluster first using this guide.

# Preparing

To migrate the control panel role, you must be running the latest version of Enhance. On every server in your cluster, run:

apt update
apt upgrade -y

Your control panel server must be running no websites or services other than the control panel websites for you and your resellers (if applicable).

Migrate any customer websites to other servers in your cluster. This includes the backup role if you are using your control panel server as a backup target.
Delete any phpMyAdmin or central webmail websites (websites with the PMA or WML) tags. You will recreate them after the migration is complete.
- You may wish to back up the MySQL database for the central webmail websites if your customers are using contact featues. You will find the database name in public_html/config/config.inc.php.
Uninstall the DNS role if installed.
Uninstall the database role if installed.
Uninstall the email role if installed.

Check your website backups are intact and up to date

# Set up the new control panel server

Provision a new server with Ubuntu 24.04 LTS
Install Enhance as if it were a new cluster. You do not need a licence key.

curl https://install.enhance.com/install.sh | bash

Shut down orchd and appcd on the new control panel server

systemctl stop orchd
systemctl stop appcd

# Transfer data

TIP

Where you see 9.9.9.9, replace this with the IP of the new control panel server

WARNING

Be very careful to run the right commands on the right server. A mistake could be disastrous!

Shut down and disable appcd and orchd on the old control panel server.

systemctl stop orchd
systemctl stop appcd
systemctl disable orchd
systemctl disable appcd

It is imperative that these services are never started again.

Dump the orchd and authd databases to sql files and transfer to the new server:

sudo -u orchd pg_dump -O -d orchd > /var/orchd/orchd.sql
sudo -u orchd pg_dump -O -d authd > /var/orchd/authd.sql

scp /var/orchd/orchd.sql [email protected]:/var/orchd/orchd.sql
scp /var/orchd/authd.sql [email protected]:/var/orchd/authd.sql

# copy mTLS certificates

scp -r /etc/ssl/certs/enhance [email protected]:/etc/ssl/certs/
scp -r /etc/ssl/private/enhance [email protected]:/etc/ssl/private/
scp -r /var/local/enhance/orchd/private [email protected]:/var/local/enhance/orchd
scp /var/local/enhance/rca.pw [email protected]:/var/local/enhance/rca.pw

# copy control panel assets

scp -r /var/www/control-panel/assets [email protected]:/var/www/control-panel/

# copy cloudflare key (if in use)

scp /var/local/enhance/orchd/cloudflare.key [email protected]:/var/local/enhance/orchd/cloudflare.key

Import the database on the new control panel server

# remove the control panel data from the initial installation and create an empty database in its place

sudo -u postgres psql -c "DROP DATABASE orchd;"
sudo -u postgres psql -c "DROP DATABASE authd; "
sudo -u postgres psql -c "CREATE DATABASE orchd;"
sudo -u postgres psql -c "CREATE DATABASE authd;"
sudo -u postgres psql -d orchd -c "GRANT USAGE, CREATE ON SCHEMA public TO orchd;"
sudo -u postgres psql -d authd -c "GRANT USAGE, CREATE ON SCHEMA public TO orchd;"

# import the data

sudo -u orchd psql -d orchd  < /var/orchd/orchd.sql
sudo -u orchd psql -d authd  < /var/orchd/authd.sql

# start services

systemctl start orchd
systemctl start appcd

Reinstate control panel websites

(Replace 9.9.9.9 with the IP of your control panel server)

sudo -u orchd psql -At -c "
SELECT 'appcd-cli create-website ' || w.id || ' ' || w.unix_user || ' ' || d.domain || ' php83 control-panel'
FROM websites w
JOIN domain_mappings dm ON w.id = dm.website_id
JOIN domains d ON dm.domain_id = d.id
WHERE w.kind = 1 and dm.kind = 'primary';
" | bash

# set primary IP for SSO
sudo -u orchd psql -c "UPDATE servers SET primary_ip = '9.9.9.9' where id = '00000000-0000-0000-0000-000000000000';"

# chown certificate files
ssh [email protected] chown orchd:orchd /var/local/enhance/orchd/private/orchd.key /etc/ssl/certs/enhance/orchd.crt

# chown brand assets
ssh [email protected] chown -R orchd:orchd /var/www/control-panel/screenshots /var/www/control-panel/assets

# chown cloudflare key (if used)
ssh [email protected] chown orchd:orchd /var/local/enhance/orchd/cloudflare.key

Access the panel and update DNS

You can now run ecp sso to access the panel and check everything is working. This address uses port 2087 - if you can't access it, check your firewall config.

At this point you should re-save your existing licence key under settings->licence.

Then, on the new control panel server, run:

ecp regenerate-control-panel-proxies

To reinstate filerd and to make your custom control panel URLs function again.

Update the DNS for your control panel domain to the new IP and wait for your local DNS cache to update, your panel should be working normally.

# Cleanup

Once you are happy with the transfer, delete /var/orchd/orchd.sql and /var/orchd/authd.sql from the new control panel server.
Shut down the old control panel server and ensure it cannot be started again.
Re-create central webmail and phpMyAdmin websites if required.

# Troubleshooting

This is a new guide. If anything doesn't work as expected or if any part of the process generates an error message, please contact support.

← Installing WHMCS