Performing the upgrade
It is possible to upgrade from 1.2.0 to 1.2.2. It is a manual process due to the wide range of possible site configurations there could be. So you will need to adapt to the specific needs of your HUBzero installation. The steps outlined below work on the HUBzero 1.2.0 VMWare virtual machine image we distributed at HUBbub 2013. This environment had particular issues with limited disk space that complicated the process.
Some instructions will differ depending on how your site was installed. We have highlighted items like passwords, template names, and hub names which you may need to substitute with values specific to your hub. The text given here is valid for the HUBzero VMware virtual machine image that was distributed at the Hubbub 2013 Conference.
Be careful if you use cut and paste. Some commands will consume all standard input which will cause additional commands that you cut and pasted to not get executed. The steps below are intentionally broken down into chunks that avoid this problem.
You will have to perform the upgrade as the root user.
You changed your root password right? If hubzero2013 is still your root password you really must change it as soon as possible.
example.com login: root Password: hubzero2013
In the case of the HUBzero 2013 VMware virtual machine image the Network Time Protocol daemon isn't running so the time and date on the site could be wrong. While not critical it can eliminate a number of warning errors that might otherwise be confusing. We add a 10 second delay at the end to give it enough time to take effect.
apt-get install -y ntp ntpd -gq sleep 10
The HUBzero 1.2.0 installation failed to record the MySQL root password. You changed your MySQL root password right? If it is still hubzero2013 you should change it as soon as possible. It is necessary to add the mysql root password to the /etc/hubzero.secrets file.
echo -e "MYSQL-ROOT=hubzero2013" >> /etc/hubzero.secrets
Now we will back up the HUBzero databases and the HUBzero CMS installation. We do not back up the "site" directory here, you may do so however you see fit. Be careful, some of these lines are wrapping around but are supposed to be on a single line.
cd /root mysqldump --defaults-file=/etc/mysql/debian.cnf --default-character-set=utf8 --skip-extended-insert --compact --order-by-primary --result-file=example.`date +"%Y%m%d"`.sql example mysqldump --defaults-file=/etc/mysql/debian.cnf --default-character-set=utf8 --skip-extended-insert --compact --order-by-primary --result-file=example-metrics.`date +"%Y%m%d"`.sql example_metrics tar -czf template-hubbasic2013.`date +"%Y%m%d"`.tar.gz -C /var/www/example/templates hubbasic2013 tar -czf cms.`date +"%Y%m%d"`.tar.gz -C /var/www/example --exclude=site/* .
We are assuming you are running Debian 6.x right now. If you aren't then you may need to modify this section. The goal here is to get your current operating system all the way up to date. We convert the package repositories to the Debian 6 Long Term Support repository and the HUBzero shira-deb6 repository. The we peform the updates.
During the upgrade you will be asked whether to modify the configuration file /etc/submit/submit-server.conf. You may select No (keep the local version currently installed)
cat << HERE > /etc/apt/sources.list deb http://ftp.us.debian.org/debian/ squeeze main contrib non-free deb-src http://ftp.us.debian.org/debian/ squeeze main contrib non-free deb http://ftp.us.debian.org/debian/ squeeze-lts main contrib non-free deb-src http://ftp.us.debian.org/debian/ squeeze-lts main contrib non-free deb http://packages.hubzero.org/deb shira-deb6 main deb-src http://packages.hubzero.org/deb shira-deb6 main HERE apt-key adv --keyserver pgp.mit.edu --recv-keys 143C99EF apt-get update apt-get dist-upgrade -y
This is a good spot to clean up a little in case your system has limited disk space for package updates
Now we update the existing HUBzero 1.2.0 installation with the most recent version (updated during previous step).
Now we can install the HUBzero 1.2.2 package
apt-get install -y hubzero-cms-1.2.2
Then we update our HUBzero CMS instance to this new version
It is now time to update Debian to 7.x. We will do this in a couple steps in order to reduce disk usage which is necessary when trying to apply this procedure to the VMware virtual machine image that was distributed for HUBzero.
The first thing we do is change the package repositories to Debian wheezy (7.x) and HUBzero shira-deb7. Then fetch the package keys which are used to verify the integrity of the packages.
cat << HERE > /etc/apt/sources.list deb http://ftp.us.debian.org/debian/ wheezy main contrib non-free deb-src http://ftp.us.debian.org/debian/ wheezy main contrib non-free deb http://ftp.us.debian.org/debian/ wheezy-updates main contrib non-free deb-src http://ftp.us.debian.org/debian/ wheezy-updates main contrib non-free deb http://packages.hubzero.org/deb shira-deb7 main deb-src http://packages.hubzero.org/deb shira-deb7 main deb http://download.openvz.org/debian wheezy main HERE wget http://ftp.openvz.org/debian/archive.key -q -O - | apt-key add - apt-get update apt-get install -y debian-archive-keyring
In order to make remove for the upgrade we will remove the hubzero-texvc package temporarily
apt-get purge -y hubzero-texvc
Then autoremove all the dependencies that package had brought in (TeX)
apt-get autoremove -y
Then remove all the cached installation packages from the system
Now we can do the actual Debian 6 to Debian 7 upgrade. We found during testing that stopping the mysql server manually was necessary (although you may have already done this during the backup step earlier)
While running it will ask you a few interactive questions which you may want to answer as follows:
- let it restart services when asked
- don't change mysql password when asked
- /etc/vz/vz.conf update (Y, install the package maintainer's version)
- /etc/auto.master update (Y, install the package maintainer's version)
- /etc/default/grub update (Y, install the package maintainer's version)
- don't change mysql password when asked
- /etc/logrotate.d/apache2 update (Y, install the package maintainer's version)
- /etc/php5/apache2/php.ini update (Y, install the package maintainer's version)
apt-get update /etc/init.d/mysql stop apt-get dist-upgrade -y
Now we can re-install the hubzero-texvc package. We remove cached packages again to keep disk usage low for systems where that is a concern.
apt-get clean apt-get install -y hubzero-texvc
Now we clean just clean up some more leftover cruft.
apt-get clean rm /etc/php5/conf.d/oauth.ini rm /etc/php5/conf.d/stem.ini rm /etc/php5/conf.d/suhosin.ini
Now we reapply the HUBzero CMS 1.2.2 package to the current instance in case there were any differences between the Debian 7 and Debian 6 packaging and let it reapply any configuration that may have been undone by the operating system upgrade. We also re-enable webdav and openvz so that their configuration files get updated (they were replaced during the operating system upgrade).
hzcms update hzcms configure webdav --enable hzcms configure openvz --enable
Time to reboot to apply the new kernel that was installed during the operating system upgrade. This step can take many minutes for some reason as it sits at one spot for some time before finally shutting down. More investigation here might lead to another step that could be taken beforehand to reduce the reboot time.
Now we remove the old Debian 6 OpenVZ kernel
apt-get purge -y linux-image-2.6.32-5-openvz-amd64 linux-image-2.6-amd64
We clean up cached package yet one more time then reboot to make sure everything is working correctly. This reboot should be relatively quick
apt-get clean reboot
If you were using a default HUBzero template (hubbasic,hubbasic2012,hubbasic2013) without copying it to a new name you will need to restore it from the backups we made earlier as the upgrade process overwrites the standard HUBzero templates. Restoring this old template will likely break your site as your template will need to be upgraded to be compatible with this version of the HUBzero CMS. The web developer release notes outline the basic changes that will be needed for your template. If you prefer you can elect to not restore your backed up template and instead re-apply your customizations to the new template.
cd /var/www/example/templates tar -xvpf /root/template-hubzero2013.`date +"%Y%m%d"`.tar.gz
Finally it is necessary to update your tool container image to Debian 6 LTS (long term support), if you don't have any Debian 6 tool container images you can skip the remainder of these instructions.
chroot /var/lib/vz/template/debian-6.0-amd64-maxwell cat << HERE > /etc/apt/sources.list deb http://ftp.us.debian.org/debian/ squeeze main contrib non-free deb-src http://ftp.us.debian.org/debian/ squeeze main contrib non-free deb http://ftp.us.debian.org/debian/ squeeze-lts main contrib non-free deb-src http://ftp.us.debian.org/debian/ squeeze-lts main contrib non-free deb http://packages.hubzero.org/deb shira-deb6 main deb-src http://packages.hubzero.org/deb shira-deb6 main HERE apt-key adv --keyserver pgp.mit.edu --recv-keys 143C99EF apt-get update
We install the hubzero-policyrcd package which will prevent all future package installations and updates for this container image from stopping or restarting services (which would start/stop services running on the host which would not be a good thing.
apt-get install -y hubzero-policyrcd
Some packages require access to the /proc filesystem to get information about the system. So we mount this special filesystem inside the container image chroot environment for the duration of the update then unmount it
mount -t proc proc /proc
Do the package upgrade to switch to Debian 6 LTS.
apt-get dist-upgrade -y
After the upgrade is complete we unmount the temporary /proc mount and remove any packages that are no longer needed
umount /proc apt-get autoremove -y
Lastly we remove any cached packages from the image in order to conserve disk space. Then we exit the chroot environment and go back to the host computer environment.
apt-get clean exit
That's it. Your hub should now be upgraded to Debian 7.x and HUBzero 1.2.2
Your tool container images remain Debian 6 as it may be necessary to update your tools for Debian 7 and that process is outside the scope of this document.