Documentation

Upgrading from 1.2.0

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

apt-get clean

Now we update the existing HUBzero 1.2.0 installation with the most recent version (updated during previous step).

hzcms update

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

hzcms update

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

apt-get clean

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.

reboot

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.

Last modified:

  • Copyright © 2022 Hubzero
  • Powered by Hubzero®