Documentation

Upgrading from 1.1.x

Download (pdf)

Performing the upgrade

It is possible to upgrade from HUBzero 1.1.x to 2.1.x.  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 have been tested on the HUBzero 1.1.x VMWare virtual machine images that were distributed at the HUBbub 2012 conference and made available on the HUBzero website. This environment had particular issues with limited disk space that complicates the process somewhat.

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 1.1.x VMware virtual machine images that were distributed at the Hubbub 2012 conference and made available on the HUBzero website.

Be careful if you use cut and paste. Some commands will consume all standard input which will cause subsequent commands 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 hubzero2012 is still your root password you really must change it as soon as possible.

You changed your MySQL root password right? If hubzero2012 is still your MySQL root password you really must change it as soon as possible.

Template incompatability

Be aware that your existing template (unless using an unmodified HUBzero core template) will not work on your upgraded hub. You may want to develop a HUBzero CMS 2.1 compatible template on a fresh installation before upgrading an existing hub.

Backup HUBzero 1.1.x

Before we start we will back up the HUBzero databases and the HUBzero CMS installation. We do not back up the "site" directory (/var/www/example/site) 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-hubbasic2012.`date +"%Y%m%d"`.tar.gz -C /var/www/example/templates hubbasic2012
tar -czf cms.`date +"%Y%m%d"`.tar.gz -C /var/www/example --exclude=site/* .

Update Debian 6

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 version all the way up to date. Since Debian 6 is no longer even on long term support we have to configure the machine to use the the archived Debian 6 repositories.  Then we perform a full package update.

cat << HERE > /etc/apt/sources.list
deb http://archive.debian.org/debian squeeze main contrib non-free
deb http://archive.debian.org/debian squeeze-lts main contrib non-free
deb http://packages.hubzero.org/deb manny main
HERE
cat << HERE >> /etc/apt/apt.conf

Acquire::Check-Valid-Until false;

HERE
apt-key adv --keyserver pgp.mit.edu --recv-keys 143C99EF
apt-get update
apt-get dist-upgrade -y

While running it will ask you a few interactive questions which you will want to answer as follows:

  • read and dismiss ('q') apt-listchanges output
  • let it restart services when asked

In the case of the HUBzero 1.1.x VMware virtual machine image the Network Time Protocol daemon isn't installed 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.

apt-get install -y ntp

We initiate a manual time update and add a 10 second delay at the end to give it enough time to take effect.

ntpd -gq
sleep 10

This is a good spot to clean up a little in case your system has limited disk space for later package updates. Autoremove any packages no longer needed.

apt-get autoremove -y

Then remove all the cached installation packages from the system

apt-get clean

Re-run the hubzero openvz configuration in case there was an OpenVZ kernel update

hzcms configure openvz --enable

Reboot the machine to ensure that any packages (especially kernel) are fully applied.

reboot

Update HUBzero 1.1.x

Now we update the existing HUBzero installation:

hzcms update

Upgrade to Debian 7

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). 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://security.debian.org/ wheezy/updates main contrib non-free
deb-src http://security.debian.org/ wheezy/updates main contrib non-free

deb http://packages.hubzero.org/deb manny main
HERE
apt-get update
apt-get install  -y debian-archive-keyring

In order to free up disk space 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 have to do an extra step to preinstall the mysql-server-5.5 package due to a problem with APT::Immediate-Configure failing to resolve upgrade issues before doing the distribution upgrade.

apt-get update
apt-get install -y mysql-server-5.5 libc-dev

While running it will ask you a few interactive questions which you will want to answer as follows:

  • read and dismiss ('q') apt-listchanges output
  • let it restart services when asked
  • don't change the MySQLl root password when asked

 

Then perform the full distribution upgrade:

apt-get dist-upgrade -y

While running it will ask you a few interactive questions which you will want to answer as follows:

  • read and dismiss ('q') apt-listchanges output
  • /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 (Y, install the package maintainer's version)
  • /etc/logrotate.d/apache2 update (Y, install the package maintainer's version)

Remove packages no longer required.

apt-get autoremove -y

Remove cached packages again to keep disk usage low for systems where that is a concern.

apt-get clean

Re-install the hubzero-texvc package.

apt-get install -y texlive-latex-base ghostscript imagemagick texlive-latex-extra

We remove cached packages again to keep disk usage low for systems where that is a concern.

apt-get clean

Now we can remove a leftover configuration file for the suhosin php package that was deprecated in Debian 7.

rm /etc/php5/conf.d/suhosin.ini

Now we reapply the current HUBzero updates to the current instance 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

 

Upgrade OpenVZ Kernel

Debian 7 does not have an OpenVZ kernel package available from Debian so we need to install one that has been created by the OpenVZ kernel developers.

First add the OpenVZ package repository to your apt repository configuration

cat << HERE >> /etc/apt/sources.list

deb http://download.openvz.org/debian wheezy main
HERE
wget http://ftp.openvz.org/debian/archive.key -q -O - | apt-key add -

Then install the OpenVZ kernel package

apt-get update
apt-get install -y vzkernel

Configure system to boot with new kernel by default

hzcms configure openvz --enable

Reboot to apply the new kernel. 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

Remove any packages that are no longer required

apt-get autoremove -y

Remove all the cached installation packages from the system

apt-get clean

Upgrade to HUBzero 2.1

Change the HUBzero package repository to ellie-deb7 in /etc/apt/sources.list

sed -i -e 's/manny/ellie-deb7/g' /etc/apt/sources.list

Then run a full distribution upgrade (a regular upgrade doesn't handle package renames and other versioning issues that have changed since HUBzero 1.1.x).

apt-get update
apt-get dist-upgrade -y

While running it will ask you a few interactive questions which you will want to answer as follows:

  • /etc/vz/vz.conf update (Y, install the package maintainer's version)

The HUBzero 1.1.x installation failed to record the MySQL root password.  It is necessary to add the MySQL root password to the /etc/hubzero.secrets file.

cat << HERE >> /etc/hubzero.secrets

MYSQL-ROOT=hubzero2012

HERE

Then autoremove any packages that are no longer needed after the upgrade

apt-get autoremove -y

Then remove all the cached installation packages from the system

apt-get clean

Apply the HUBzero upgrade

hzcms update

Updating the HUBzero CMS Template

If you were using a default  HUBzero template (hubbasic or hubbasic2012) without copying it to a new name you will need to restore it from the backups we made earlier as the upgrade process overwrites all the standard HUBzero templates.

cd /var/www/example/app/templates
tar -xvpf /root/template-hubzero2012.`date +"%Y%m%d"`.tar.gz

You will then need to rename the template and upgrade it to be compatible with HUBzero CMS 2.1. After renaming it you can have the site discover the new template via the Extension discovery process.  The web developer release notes outline the basic changes that will be needed for your template.

If you were using a custom template it SHOULD have been moved to /var/www/example/app/templates/YOUR_TEMPLATE_NAME and may have been partially upgraded for HUBzero CMS 2.1 but will almost certainly require extensive work to make it fully compatible.

 

Updating the HUBzero Tool Container Image

Finally it is necessary to update your Debian 6 tool container image to the last Debian 6 release and HUBzero 2.1.x support packages. If you don't have any Debian 6 tool container images you can skip this section.

chroot /var/lib/vz/template/debian-6.0-amd64-maxwell
cat << HERE >  /etc/apt/sources.list
deb http://archive.debian.org/debian squeeze main contrib non-free
deb http://archive.debian.org/debian squeeze-lts main contrib non-free
deb http://packages.hubzero.org/deb ellie-deb6 main
HERE
cat << HERE >> /etc/apt/apt.conf

Acquire::Check-Valid-Until false;

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 unmount the temporary /proc

umount /proc

Remove any packages no longer required

apt-get autoremove -y

Lastly we remove any cached packages from the image in order to conserve disk space.

apt-get clean

Exit the chroot environment and go back to the host computer environment.

exit

 

Conclusion

That's it. Your hub should now be upgraded to Debian 7.x and HUBzero 2.1.0

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: