You are here
OrangeHRM
OrangeHRM Upgrade
Assumptions and limitations
OrangeHRM and TurnKey base OS
This doc explicitly covers upgrading OrangeHRM v4.x (TurnKey v17.x) and/or OrangeHRM v5.x (TurnKey v18.x) to the latest stable OrangeHRM release (v5.7 at the time of writing). It does NOT cover upgrading the underlying TurnKey/Debian OS to the latest release.
TurnKey v17.x is based on Debian 11/Bullseye. Bullseye is currently in “LTS” (long term support) and will receive security updates at least until August 31, 2026. TurnKey v18.x is based on Debian 12/Bookworm. Bookworm will be supported until at least June 30, 2028.
This doc also assumes:
- TKLBAM is enabled (or you enable it) - note this isn’t necessary, but is highly recommended.
- Your server has sufficient free space for the upgrade - 2GB is recommended but more is always better.
This doc uses terminal commands for most of the process. Many steps may be possible via Webmin but terminal commands are concise and can be copy/pasted so are quite easy to follow. Any steps where you know how to achieve the same results via Webmin, feel free to use that instead.
Access to your TurnKey server’s CLI via “SSH” (secure shell) is recommended. Recent Windows 11 releases, Mac OSX and all Linux desktop flavors all ship with OpenSSH client pre-installed but there are a number of alternate SSH clients which also work well.
Alternatively on TurnKey v17.x you can use your server’s “Webshell” via your browser; https on port 12320. E.g. https://your.domain.com:12320. On TurnKey v18.x you can use the Webmin “proper” interactive terminal module (v18.x does not include WebShell).
DO NOT use the TurnKey v17.x Webmin terminal! It is not a true interactive terminal and will cause problems.
Generally a local SSH client will give a better user experience (e.g. copy/paste should work reliably) but v17.x's Webshell or v18.x's Webmin interactive terminal module should work fine.
To launch an SSH session:
ssh root@DOMAIN_OR_PUBLIC_IP
If you are using authentication keys instead of a password, you may need to explicitly include the path to the private key on your local system:
# Linux/OSX ssh -i ~/path/to/my_private_key root@DOMAIN_OR_PUBLIC_IP # Windows C:\Users\ME\path\to\my_private_key root@DOMAIN_OR_PUBLIC_IP
Note for AWS Marketplace users
AWS Marketplace instances have the ‘root’ account disabled by default. So either enable root or log in as ‘admin’ and then become root like this:
sudo su -
First steps - preparation
Before starting the OrangeHRM upgrade ensure that you have a current backup and enough free space. I also recommend that you upgrade all system packages and reboot the system before starting the upgrade.
Backup
I recommend creating both a “snapshot” and a “proper” backup. A snapshot is technically not a backup, but loading a snapshot is a quick and easy way to get back to exactly where you are right now if needed.
If your server is running via the TurnKey Hub, you can trigger a snapshot via the Hub’s “servers” page. Please note that it can take some time to complete. Other virtualization/cloud platforms should also have this functionality - consult the relevant docs if you aren’t sure how. Bare metal servers can use a tool such as Clonezilla.
Assuming you are using TKLBAM, manually trigger a full TKLBAM backup of your server. You can either do that via Webmin, or via a terminal:
tklbam-backup --full-backup now
Check free space and cleanup if required
To check free space:
df -h /
Example output (Hub server with 10GB root volume):
Filesystem Size Used Avail Use% Mounted on /dev/xvda 10.0G 2.1G 8.0G 21% /
Look at the “Avail” column (8.0G in the above example). I recommend at least 1GB bare minimum free space, preferably at least 2GB. If you do not have enough, first do a clean up as below. Please DO NOT just blindly enter ‘y’ on the second (autoremove) command:
apt clean apt autoremove
The ‘autoremove’ command should only list a few packages, probably including old kernels (packages that start with ‘linux-image’). If it lists a large number of packages or lists any core packages please be sure to check their function and if any raise concerns you can manually remove the ones that appear safe to remove using ‘apt remove PKG1 PKG2 …’. If you have concerns and have sufficient free space, just skip this step for now.
Upgrade OS software (optional)
To update the system software to the latest packaged versions:
apt update apt upgrade
If you do run this step, I also recommend re-running the above apt cleanup commands, reboot your server and double check free space.
Manual local backup (optional)
With both a snapshot and a TKLBAM backup, making another backup may seem like overkill. However I would argue that multiple layers of redundancy are always desirable. Then if something goes wrong you have multiple recovery options and pathways to restore functionality. Regardless, this step is purely optional and a snapshot and a full TKLBAM backup provide sufficient recovery options.
Manual DB dump
mysqldump orangehrm > orangehrm_db.sql.orig
Upgrade OrangeHRM v4.x to v4.10.1
The latest OrangeHRM release at the time of writing is v5.7. But you must be running v4.10.1 (the latest v4.x release) to upgrade to v5.x. If you are already running v4.10.1 or later, then please skip this step.
OrangeHRM provide upgrade documentation but I will provide a more detailed and TurnKey specific step-by-step here.
Download v4.10.1
wget https://sourceforge.net/projects/orangehrm/files/stable/4.10.1/orangehrm-4.10.1.zip
Move existing install
mv /var/www/orangehrm /var/www/orangehrm.orig
Unpack new version
unzip orangehrm-4.10.1.zip mv orangehrm-4.10.1 /var/www/orangehrm
Give webserver write access to the required OrangeHRM files:
chown -R www-data:www-data /var/www/orangehrm/lib/{confs,logs}
chown -R www-data:www-data /var/www/orangehrm/symfony/{config,apps/orangehrm,cache,log}
Get the existing DB ‘orangehrm’ user password (from the old config file):
grep -m 1 password /var/www/orangehrm.orig/symfony/config/databases.yml
Install and enable the php zip extension:
apt install --yes php-zip systemctl restart apache2
Load upgrade page in your web browser
Open in your web browser and browse to your OrangeHRM site domain’s “upgrade” page:
https://DOMAIN_OR_PUBLIC_IP/upgrader/web
E.g.:
https://orangehrm.domain.com/upgrader/web
Unless you want to do a “clean” install DO NOT just load your domain without the ‘/upgrader/web’ URL. Otherwise it will overwrite your existing data.
Enter the DB details
Host*: 127.0.0.1 Port: 3306 Username* orangehrm Password <password from the above 'grep' command> Database Name: orangehrm
Then click the “Proceed” button.
System check
Everything should be fine, but double check that each line has a green “OK” on the system check page.
Assuming all is well, click the “Proceed” button.
Select current OrangeHRM version
From the dropdown, select the current/old OrangeHRM version. Unless you have already upgraded, TurnKey v17.1 should have OrangeHRM version ‘4.9’. Regardless, you can confirm the current/old version with this command:
grep -m 1 'OrangeHRM ver' /var/www/orangehrm.orig/CHANGELOG.TXT
By default it should return:
New & Changed Features for OrangeHRM ver 4.9
Select the relevant version and click the “Proceed” button.
Apply manual changes - if required
The next page will display any manual steps/changes that you may need to perform. During my testing, the only additional manual step noted applied to data encryption.
If you have enabled data encryption, copy the cryptographic keys from your old OrangeHRM directory. I.e.:
cp /var/www/orangehrm.orig/lib/confs/cryptokeys/key.ohrm /var/www/orangehrm/lib/confs/cryptokeys/
Once you have performed any additional manual steps, click the “Proceed” button.
Update database
The next page will actually perform the database upgrade. As noted, the upgrade may take a little while and it is VERY important that you do not close or reload that page until the progress reaches 100% and the “Start” button changes to a “Proceed” button.
Click the “Start” button and once it has completed, click the “Proceed” button.
Create new config files
The next page will generate the new config files. This step shouldn’t take long but as per the previous database upgrade page, DO NOT close or reload that page.
Click the “Start” button and once it has completed, click the “Proceed” button.
Finalize upgrade
You should be greeted with a page titled “Congratulations!”, noting that you are now running OrangeHRM v4.10.1.
As noted on that page, ensure that any manual steps are complete (should have been handled within the previous “Apply manual changes” step, but you can double check them from the noted file within your OrangeHRM directory:
cat /var/www/orangehrm/upgrader/log/notes.log
Click the “Proceed” button.
Validate your upgraded OrangeHRM data
After the previous step you will be redirected back to the log in page. Log in using your ‘admin’ user and password.
As was noted on the final “Congratulations!” page: > […] do a full round of data verification to see whether data from previous > version has been imported properly.
In particular check that these pages are available and include your data: - Admin - PIM - Leave
Upgrade OrangeHRM v4.10.1 to v5.7
A number of the steps to upgrade to v5.7 are very similar to the previous upgrade. These steps will most likely also apply to later v5.x updates. However OrangeHRM v5.x includes a CLI installer/upgrader which these instructions will cover.
As per the v4.10.1 upgrade, OrangeHRM provide upgrade documentation but that only covers the webUI upgrade. These instructions will provide TurnKey specific notes using the CLI tool.
Preparation
Double check free space and create a new OS backup & snapshot as per initial OrangeHRM v4 upgrade.
Also create a manual database local backup:
mysqldump orangehrm > orangehrm_v4.10.1_db.sql
Download v5.7
wget https://sourceforge.net/projects/orangehrm/files/stable/5.7/orangehrm-5.7.zip
Move existing install
mv /var/www/orangehrm /var/www/orangehrm-4.10.1
Unpack new version
unzip -o orangehrm-5.7.zip mv orangehrm-5.7 /var/www/orangehrm
Upgrade install via CLI
The CLI upgrade is much quicker and easier IMO.
Ensure that you have your existing database password:
grep -m 1 password /var/www/orangehrm.*/symfony/config/databases.yml
Then change to the new OrangeHRM directory (that you downloaded and
unpacked above) and run the CLI tool. Note that you will need to replace
‘
cd /var/www/orangehrm
php installer/console upgrade:run \
--dbHost=127.0.0.1 \
--dbPort=3306 \
--dbName=orangehrm \
--dbUser=orangehrm \
--dbUserPassword=<db password> \
--currentVersion=4.10.1
Verify environment
The above command will output a fair bit of text. Much of it can safely be ignored, but please double check the ‘System Check’ section. All the values should be green (or yellow if not used).
If any of the system checks are red, you will need to answer “n” and resolve them first before you rerun the upgrade command above.
Assuming that all the system checks are ok, hit Enter (“yes” is the default).
The upgrade may take a little while, but eventually it will complete and exit without any error message.
Validate your upgraded OrangeHRM data
Once the upgrade script completes, log into your OrangeHRM instance via your web browser and validate that all your data is there and everything is working as it should.
Assuming so, congratulations - you are now running the latest OrangeHRM! :)