Upgrading Aegir is designed to be as easy as it possibly can be, and regularly improves over time as the developers attempt to streamline the process for users.
Nonetheless, the upgrade process can seem a little daunting to users. This is mainly because some expectation arises that because Aegir is built on Drupal, and is made for managing Drupal sites, it seems reasonable to expect the upgrade process to be as straightforward as, say, upgrading a regular Drupal site.
Aegir is a powerful system that goes beyond a normal Drupal application by being split into two parts: a frontend (the browser-based control panel) and the backend (bits on the system in /var/aegir, such as Drush and Drush extensions), along with a system user on your server that runs command-line scripts and restarts services, and cronjobs.
Typically what this means is that when it comes time to upgrade Aegir, you not only have to upgrade the frontend site, but also update the components that reside in the 'backend'.
But don't panic! We have instructions and even a script to run, to take care of almost all of it for you, eliminating as much as possible the chance for human error.
There are three options you can choose to upgrade your Aegir install when a new release comes up:
Upgrades using Debian packages
Upgrades using the upgrade.sh.txt script
New release of Drupal core
Just as you would use the Migrate task in Aegir to upgrade one of your sites to a new copy of Drupal core, you can follow the UPGRADE.txt to upgrade your actual Aegir frontend system to a new copy of Drupal core too. The upgrade process (including the script) will always fetch the latest available copy of Drupal core to place the frontend on.
Most of the instructions on this page are targetted to minor updates, e.g. Aegir 3.1 to 3.2.
When upgrading from Aegir 2.x there are a few extra precautions to take. But apart from that the normal upgrade options apply.
To avoid the upgrade breaking run these drush commands:
This section outlines the requirements for doing a manual upgrade of Aegir to a new release. Before going ahead with this, you probably want to read the upgrade path and version-specific notes.
Conventions & Tips
All instructions and in general all commands must be run as aegir user, so all permissions are always set correctly.
To become aegir user you can issue this command. Note you must run this as root or prefix with sudo.
su -s /bin/sh aegir
Note that /bin/sh is an example. You may wish to instead use the shell of your choice, i.e /bin/bash
A standard umask of 022 is assumed. This is the default on most systems.
As part of your Aegir upgrade, you may need to upgrade Drush to the latest stable version compatible with the target Aegir release. Aegir 3.x works with Drush 6, 7 and 8. Note that to install and manage Drupal 8 sites, Drush 8+ is required.
Upgrading the backend
After drush is updated, you must then proceed to upgrade the backend. The reason for upgrading the backend first before the frontend, is that the frontend upgrade process is instigated by the backend using Drush Make. Thus you need to be running the new backend first in order to successfully produce a new frontend.
In general, we try to keep the backend and the frontend compatible with each other during release cycles. That is: provision 3.2 and hosting 3.3 will always be able to talk to each other, but hosting 3.x may have trouble talking to the 2.x backend, so you need to upgrade the backend first when you do a major upgrade (for example, 2.4 -> 3.0).
Bottomline: first you upgrade the backend, then the frontend.
Upgrading the frontend
Once your backend is upgraded, you can upgrade your frontend. Think of this as the backend fetching a new copy of Drupal core and the Hostmaster frontend application onto your server, and then moving the Aegir site's settings.php and other bits and pieces over to the new codebase.
The hostmaster-migrate command
The command will make sure the target directory is a valid Aegir install. If the directory does not exist, provision will use drush_make to fetch and assemble the correct version of the front end for the specific release of the backend you are running.
drush hostmaster-migrate will also update the crontab entry for the aegir user.
If you have customized your Aegir installation and are maintaining your own makefile, you can use the --makefile flag so the platform is created with another makefile than the default. Be warned that this may create problems if the makefile doesn't include the right Aegir modules.
If there is a newer release of Aegir than what you have installed, the hostmaster command will fetch the latest stable Drupal release. If you have the latest stable version of Aegir already installed, this won't happen because Drupal core changes could affect the stability of the distribution. So it cannot simply be run whenever a new security release of core Drupal is made available (unless your instance was installed via the unstable channel, which is not recommended).
To upgrade Drupal core (say for a new security release) while running Aegir stable, this method should work, but make sure to test on a development instance before running on your production environment:
Become the Aegir user.
sudo -Hsu aegir
Upgrade Drupal core.
drush @hostmaster pm-updatecode drupal
Verify the upgraded platform.
drush @platform_hostmaster provision-verify
Verify the Hostmaster site.
drush @hostmaster provision-verify
Run database updates
drush @hostmaster updatedb
Upgrades with Debian packages
Regular update process
Make sure you have the Aegir repository in your sources.list, as per the installation docs.
If you want to upgrade all packages in one shot, use:
apt-get updateapt-get install aegir3
Note that you can upgrade Aegir in steps. Upgrading your backend to the Debian package should be as simple as running:
apt-get install aegir3-provision
Upgrading the frontend to the Debian package works identically:
apt-get install aegir3-hostmaster
As during install, you can use the DEBUG variable to run Drush in debugging mode:
Note on contrib modules: some Aegir-specific contrib modules may have been installed on your Aegir deployment. This may fail if you are doing a major upgrade. In this case, you will probably want to disable those contrib modules. Look for directories in ~/.drush or /usr/share/drush/commands or other components of the Drush commandfiles search path, and move them out of the way. After the upgrade, download the new versions of the modules that are compatible with the new Aegir release.
Temporarily upgrading to the unstable Debian package
Occasionally, you might be facing a bug that has been fixed in Aegir's git repos, but hasn't made it into a new release yet. The Aegir Project's CI system automatically builds and uploads new Debian packages for each commit to one of the core repos. As such, you could download and install the .deb directly. Note that this is not recommended.
Ensure that the latest build is passing the test suite.
Find the latest unstable release packages for aegir3-provision and aegir3-hostmaster (they'll be the ones with a long suffix).
Download the Provision package to your Aegir server (e.g., wget aegir3-provision_3.7+438.10e2f5b_all.deb)
Download the Hostmaster package to your Aegir server (e.g., wget aegir3-hostmaster_3.7+438.10e2f5b_all.deb)
Install the Provision package to your Aegir server (e.g., sudo dpkg -i aegir3-provision_3.7+438.10e2f5b_all.deb)
Install the Hostmaster package to your Aegir server (e.g., sudo dpkg -i aegir3-hostmaster_3.7+438.10e2f5b_all.deb)
The idea here is that you're only running the unstable version of Aegir until the next full release, at which point the normal update procedure (e.g., apt-get install aegir3) will install the next stable release.
Upgrading from non-Debian installs
The Debian package supports migrating from existing installs. You will need to move /var/aegir/.drush/provision out of the way before going ahead:
tar cfz /var/aegir/backups/provision.tgz /var/aegir/.drush/provisionrm -rf /var/aegir/.drush/provision
Usually no questions are asked when upgrading - this allows you to specify the makefile path for your custom distribution of Aegir, even if you're upgrading. It's also how you can switch distributions.
An example aegir-koumbit.make file could look like:
This section describes how to upgrade the code for custom distributions in between debian package upgrades. Here, we assume that Aegir is already installed through the debian package.
Create a new Aegir makefile, or update the custom Aegir makefile. (You can use the makefile in http://git.drupal.org/project/provision as a starting point.) Add modules/features/themes/libraries/whatever to the makefile. Ex:
Hope it's all green (no errors). If there are errors, fix the makefile.
A new platform should exist, the new site should be in there, verifying. If the task is not running, check that hosting-queued is running. If it's not, restart it using /etc/init.d/hosting-queued force-reload. (Since hostmaster changed location, hosting-queued may have crashed at this point.)
When the debian package is upgraded, it should create a new hostmaster platform automatically. (You can test this with dpkg --configure.)
Rolling back the upgrade
If something went wrong with the upgrade, you can rollback by deleting the hostmaster site and redeploying on the older platform:
When using the regular update process and you encounter an error it leaves the debian package in a broken state.
First you need to figure out why it failed. For example is there a permission problem? Once you determined the issue correct it and clean up the environment. It may be necessary to remove the new hostmaster platform. It is up to you to determine what state Aegir is in.
Next you need to fix the broken package by running the fix-broken parameter:
apt-get install -f
This tells the debian package system to start through the process again.
Upgrades with upgrade.sh script
This page describes the upgrade script in the Provision repository that tries to automate much of the upgrade process.
It is imperative that you read the version-specific upgrade notes before attempting to run the upgrade.sh script, as the script will assume you have your system set up appropriately to handle the upgrade process.
You can download the upgrade.sh script for Aegir 3.x with the following command: