Upgrade WHD on Linux and macOS

This guide upgrades an existing Web Help Desk installation to a newer build on Linux (RHEL/CentOS) and macOS.

If you are installing Web Help Desk for the first time, use the installation guide for your platform instead — this guide assumes Web Help Desk is already installed and running.

What to Expect

• Upgrade only moves forward. There is no downgrade path. Going back means reinstalling the older build and restoring from backup.

• The database is not backed up for you. The installer copies files only. Backing up the database is not optional.

• Upgrade one server at a time. Where several servers share one database, upgrade the server that runs the background work first and let it finish completely before upgrading the others.

• Keep your configuration backup until you are satisfied. Encrypted values in the database can only be read with the keys in conf/aesconf/.

• Custom changes to packaged files may be replaced. Changes to Caddyfile, whd.env and logback-config.xml are kept, but other files shipped inside the package are replaced by the new build.

What an upgrade keeps

An upgrade replaces the application, not your data. The following survive:

Kept	What it holds
conf/.whd.properties	Your database connection, written by the setup wizard
conf/whd.env	Ports, host name and the database password
conf/Caddyfile	Any changes you made to the web front end
conf/logback-config.xml	Your logging settings
conf/cert.pem, conf/key.pem	Your TLS certificate
data/	The built-in database, when you use one
.helpdesk/	Licence state

The setup wizard should not reappear after an upgrade. If it does, your configuration was not carried over. You should stop and restore from the backup in Part 1 rather than completing the wizard again.

Before you upgrade

Do all of this while the current version is still running.

Write down the version you are on

cat /opt/webhelpdesk/VERSION

You need this information to confirm the upgrade moved you to the newer version.

Back up the database

The installer backs up files. It does not back up the database. If you use the embedded database, create your own copy:

sudo -u whd /opt/webhelpdesk/bin/pgsql/bin/pg_dump \
     -h 127.0.0.1 -p 20293 -U whd whd > ~/whd-backup.sql

If you use an external database (SQL Server, PostgreSQL or MySQL on another server), ask your database team for a backup at this point instead.

Keep your own copy of the configuration

sudo cp -a /opt/webhelpdesk/conf ~/whd-conf-backup

Keep this until the upgrade is confirmed to be working. conf/aesconf/ inside it holds the keys that unlock encrypted values in your database without it, a recovery is much more difficult.

Confirm space is available

df -h /opt

The upgrade writes a full backup copy next to the installation, so allow at least as much free space as /opt/webhelpdesk currently uses.

Upgrade based on your OS

Upgrade on Linux

Put the new package on the server

gunzip WebHelpDesk-<new-version>-linux.rpm.gz

Upgrade the package

sudo rpm -Uvh WebHelpDesk-<new-version>-linux.rpm

This replaces the files on the disk. It does not reconfigure anything yet.

Run the installer in upgrade mode

cd /opt/webhelpdesk
sudo bash install.sh --upgrade

The --upgrade flag is required. Without it the installer treats the server as a new installation.

What you should see near the top:

Mode              : UPGRADE

If it says FRESH, STOP immediately — you have missed the flag.

The installer stops the services, takes its own backup to /opt/webhelpdesk.backup-<timestamp>, replaces the application, and starts everything again. This takes several minutes. Let it finish.

Confirm Application Services restarted

systemctl is-active whd-pgsql whd-backend whd-frontend whd-caddy
curl -s http://127.0.0.1:8081/actuator/health; echo
cat /opt/webhelpdesk/VERSION

What you should see: every service active, the health check reporting "status":"UP", and a version higher than the one shown before the upgrade.

Upgrade on macOS

Run the newer installer

sudo installer -pkg WebHelpDesk-<new-version>-macos.pkg -target /

There is no upgrade flag on macOS — a .pkg accepts no options. The installer detects the existing installation on its own and switches to upgrade mode.

Watch it run

tail -f /tmp/whd-install.log

Press Ctrl+C to stop watching after it finishes. The installer stops the services, saves your configuration to a temporary location, installs the new build, puts your configuration back, and starts everything again.

Confirm it upgraded rather than reinstalled

grep -E "Mode: (UPGRADE|FRESH)" /tmp/whd-install.log
grep "Restoring preserved configuration" /tmp/whd-install.log
grep "skipping initdb" /tmp/whd-install.log

What you should see: Mode: UPGRADE, a line confirming your configuration was restored, and — if you use the embedded database — confirmation that the existing database was reused rather than recreated.

Confirm your previous configuration is in place

sudo launchctl list | grep com.solarwinds.whd
curl -s http://127.0.0.1:8081/actuator/health; echo
cat /opt/webhelpdesk/VERSION
ls -l /opt/webhelpdesk/conf/.whd.properties

What you should see: four services listed, "status":"UP", a newer version, and .whd.properties still present.

Confirm everything works

Perform these steps in a browser, not just on the command line.

1. Sign in as an administrator.

2. Open an existing ticket and confirm the history and attachments are there.

3. Open Setup and confirm your e-mail and database settings are unchanged.

4. Create a test ticket, then delete it.

Encrypted settings — mail passwords, database passwords, integration credentials — are the ones worth checking closely. If any appear blank or fail to authenticate after an upgrade, the keys that decrypt them did not carry over. Restore conf/aesconf/ from your backup and restart.

Troubleshooting: If something goes wrong

What you see	What it means	What to do
Mode: FRESH on Linux	--upgrade was missing	Stop. Restore from backup and re-run with the flag
The setup wizard appears	Configuration was not carried over	Do not complete it. Restore conf/ and restart
Services will not start	The upgrade did not finish	Linux: journalctl -u whd-backend -n 50 --no-pager. macOS: cat /tmp/whd-install.log
Blank or failing saved passwords	Encryption keys did not carry over	Restore conf/aesconf/ from Step 1.3, then restart
Health stays OUT_OF_SERVICE	The database cannot be reached	Check conf/.whd.properties still points at the right database

Revert to the previous version

The installer leaves a copy of your previous configuration and data:

ls -d /opt/webhelpdesk.backup*

To revert, reinstall the previous build, then restore conf/, data/ and .helpdesk/ from that folder and from your database backup. Restore the database first, then the files.