Arch Linux AUR openhab3 to openhab4 Upgrade Instructions

openhab3-4.md

These are conservative Arch Linux openHAB 3 to 4 upgrade instructions which allow an unrushed upgrade procedure and testing on a separate machine.

On the production openHAB server, firstly upgrade to latest openhab3 package. Then make a backup using openHAB's official tool:

export OPENHAB_USERDATA=/var/lib/openhab3
export OPENHAB_CONF=/etc/openhab3
/usr/share/openhab3/runtime/bin/backup openhab3-backup.zip

Transfer openhab3-backup.zip to another machine and then run as root:

pacman -S openhab3-addons openhab4-addons
export OPENHAB_USERDATA=/var/lib/openhab3
export OPENHAB_CONF=/etc/openhab3
/usr/share/openhab3/runtime/bin/restore openhab3-backup.zip
systemctl start openhab3.service
tail -f /var/log/openhab3/openhab.log

Ensure that openHAB 3 starts up and appears like your original installation by visiting http://localhost:8080/. Once satisfied:

systemctl stop openhab3.service
rm -rf /etc/openhab4/*
rm -rf /var/lib/openhab4/*
cp -r /etc/openhab3/* /etc/openhab4/
cp -r /var/lib/openhab3/* /var/lib/openhab4/
rm -f /var/lib/openhab4/core /var/lib/openhab4/*.log
rm -rf /var/lib/openhab4/cache/*
rm -rf /var/lib/openhab4/tmp/*
chown -R openhab4:openhab4 /etc/openhab4
chown -R openhab4:openhab4 /var/lib/openhab4/
find /var/lib/openhab4 -type f -exec sed -i 's/\/var\/lib\/openhab3/\/var\/lib\/openhab4/g' {} \;
find /var/lib/openhab4 -type f -exec sed -i 's/\/usr\/share\/openhab3/\/usr\/share\/openhab4/g' {} \;
find /var/lib/openhab4 -type f -exec grep -Hi openhab3 {} \;    # ensure no results found

At this point we have the openhab3 configuration in the directories and file ownerships expected by the openhab4 package. We can now run the upgrade using the openHAB-provided tools:

archlinux-java status
archlinux-java set java-17-openjdk             # minimum version required for update JAR to execute
export OPENHAB_USERDATA=/var/lib/openhab4
export OPENHAB_CONF=/etc/openhab4
export OPENHAB_LOGDIR=/var/lib/openhab4
cd /usr/share/openhab4
/usr/share/openhab4/runtime/bin/update 4.0.1   # version must match latest openhab4 package version

Look for confirmation of a successful upgrade. Then reinstall the usual openhab4 package (in particular to remove unnecessary files and pick up the patches made to oh_dir_layout) and then start the service:

cd /
rm -rf /usr/share/openhab4
pacman -S openhab4 openhab4-addons
systemctl start openhab4.service
tail -f /var/log/openhab4/openhab.log

Again visit http://localhost:8080 to verify success. Make any adjustments needed (in particular monitor the log for scripting errors; you may need to install the "JavaScript Scripting (Nashorn)" add-on and append ;version=ECMAScript-5.1 to previous scripts). Once testing and migration are complete, make a backup using openHAB's official tool:

export OPENHAB_USERDATA=/var/lib/openhab4
export OPENHAB_CONF=/etc/openhab4
systemctl stop openhab4.service
/usr/share/openhab4/runtime/bin/backup openhab4-backup.zip

Transfer openhab4-backup.zip to your production machine and then make an operating system backup using your normal approach (eg container snapshot). Install openHAB 4 and restore the openHAB backup:

systemctl stop openhab3.service
pacman -S openhab4-addons
export OPENHAB_USERDATA=/var/lib/openhab4
export OPENHAB_CONF=/etc/openhab4
/usr/share/openhab4/runtime/bin/restore openhab4-backup.zip
systemctl start openhab4.service
tail -f /var/log/openhab4/openhab.log

Remove openhab3-addons and openhab3 after a final check that the upgrade was successful.

I had to also migrate some custom settings from /etc/default/openhab3.