Migrate legacy WHD with embedded PostgreSQL from one Linux machine to another

This article provides steps for moving legacy WHD version specifically using PostgreSQL 13 on the backend, from its current home on a Linux server to another Linux server.

Assumptions:

• Both servers are supported 64-bit Linux.
• You will run the same WHD version on both servers, or upgrade separately using the documented path.
• Embedded DB listens on port 20293 and the user is whd, unless you changed it.

<WHD_HOME> is used for the Web Help Desk install directory (/usr/local/webhelpdesk).

a) Prepare and back up on the old Linux server

1. Log in to WHD as an admin and confirm you’re using the embedded PostgreSQL database:

• Go to Setup > General > Database and verify Use Embedded Database is selected and the vendor is PostgreSQL.
1. Deactivate the license on the old server:
• Setup > General > License > Deactivate.
2. Take a database backup (pick one method):
   Option A – via WHD UI (simplest)
• Still in Setup > General > Database, click Backup Now and wait for it to complete.
• Note the Backup Folder path (this is where WHD writes the backup file).

Option B – via command line (recommended for large DBs)
From the Linux shell (as root or with sudo), run a pg_dump of the whd database. Example for embedded PostgreSQL 13 on port 20293:

sudo -u whd /usr/local/webhelpdesk/bin/pgsql13/bin/ pg_dump   -h 127.0.0.1 -p 20293 -U whd /  -Fc -f /tmp/whd_backup.pgdump whd

Note: You may be prompted for a DB password, enter your DB password (default is whd)

2. Stop WHD so no new data is written during migration:

/usr/local/webhelpdesk/whd stop

3. Copy the following from the old server to a secure location (or directly to the new server):

• <WebHelpDesk>\conf\whd.conf
• <WebHelpDesk>\conf\keystore.jks
• <WebHelpDesk>\bin\jre\lib\security\cacerts
• <WebHelpDesk>labels\CustomLabels*.properties
  
  

4. Copy the database backup file (.backup or .pgdump) from the old server to the new server

b)  Install WHD with embedded PostgreSQL 13 on the new Linux server

6. On the new Linux server, install the same WHD version you’re currently running
7. During the Setup Wizard on the new server:
• Choose Use Embedded PostgreSQL database (recommended).
• Let the wizard create a temporary database (you can use any DB name/user here; this DB will be replaced).
8. Confirm WHD starts and you can reach the login page, then stop WHD again:
   sudo systemctl stop webhelpdesk

c) Rename or drop the default empty PostgreSQL embedded WHD database on the new Linux server

9. Navigate to /usr/local/webhelpdesk/bin/pgsql13/data/ and edit the pg_hba.conf and set the following lines to trust

# "local" is for Unix domain socket connections only
local   all             all                                     trust
# IPv4 local connections:
host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
host    all             all             ::1/128                 trust

10. Run the following command:
    cd /usr/local/webhelpdesk/
11. Connect to database using the following command:
    sudo bin/pgsql13/bin/ /psql -h 127.0.0.1 -p 20293 -U whd -d template1
    
    Note: You may be prompted for a DB password. Enter the one used in the steps above.
12. Execute the following statements:

ALTER DATABASE whd rename to whd_old;
CREATE DATABASE whd;

Enter \q to exit the psql tool.

d) Restore the embedded PostgreSQL 13 database and configuration files on the new server

13. Restore the database from backup by running the command
    
    /usr/local/webhelpdesk/bin/pgsql13/bin/pg_restore -Fc -v -p 20293 -U whd -d whd "path_to_whd.pgdump"

9. Restore the following files copies from the old server to same locations

• <WebHelpDesk>\conf\whd.conf
• <WebHelpDesk>\conf\keystore.jks
• <WebHelpDesk>\bin\jre\lib\security\cacerts
• <WebHelpDesk>labels\CustomLabels*.properties
  
  

e) Post-migration cleanup

10. Start WHD so no new data is written during migration:

/usr/local/webhelpdesk/whd stop

11. Log into WHD on the new server and update the server identity if the hostname or port changed:

• Go to Setup > General > Options.
• Set Server DNS Name to the new FQDN (and port if not 443/80, for example helpdesk.example.com:8443).
• Save. This ensures ticket links and attachment URLs point to the new server.

12. Activate the license on the new server

• Setup > General > License > Reactivate via online/offline activation.

13. Verify functionality on the new server:

• Log in and confirm tickets, clients, assets, and attachments are present.
• Test incoming/outgoing email, task processing, and any integrations.
• Once satisfied, keep the old server powered off or repurposed (do not let both instances process real tickets against different DBs).