Upgrading from 1.1.x
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.