1. Regular update process
Make sure you have the Aegir repository in your sources.list, as per the installation docs.
If you are upgrading from a Debian installation whereby you used the koumbit.org repositories, you should change this entry in your sources.list to be debian.aegirproject.org as per the instructions linked to above, and run apt-get update to refresh.
If you want to upgrade all packages in one shot, use:
apt-get update apt-get install aegir
Note that you can upgrade Aegir in steps. Upgrading your backend to the Debian package should be as simple as running:
apt-get install aegir-provision
Upgrading the frontend to the Debian package works identically:
apt-get install aegir-hostmaster
As during install, you can use the DEBUG variable to run Drush in debugging mode:
env DEBUG=yes apt-get install aegir-hostmaster
Note: the DEBUG flag is deprecated. In 1.x releases, it is accepted, but in 2.x it won't. You should use DPKG_DEBUG instead, it is usable starting from 1.1-4.
2.x note: to upgrade to 2.x, use:
apt-get install aegir2.
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
/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.
2. 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/provision rm -rf /var/aegir/.drush/provision
You'll also need to go through steps 1 through 3 of Automatic install on Debian.
Then just install the package as if you were installing from scratch.
3. Custom distributions
If you have your own makefile, you can go ahead with the above process, but change the makefile to the one you want:
echo debconf aegir/makefile string /var/aegir/makefiles/aegir/aegir-koumbit.make | debconf-set-selections apt-get install aegir
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:
core = 6.x
api = 2
includes[aegir] = "/usr/share/drush/commands/provision/aegir.make"
projects = module_filter
Note that for this to work, you will need the patch from this issue, allowing drush_make to reference absolute system paths.
3.1. Keeping custom distributions up to date
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 drupal.org/project/provision as a starting point.)
- Add modules/features/themes/libraries/whatever to the makefile. Ex:
projects = token
projects = views
- Follow the manual upgrade path:
- drush @hostmaster hostmaster-migrate URL /path/to/platform --makefile='/path/to/makefile'
- Hope it's all green (no errors). If errors, fix makefile.
- A new platform should exist, the new site should be in there, verifying. If the task is not running, check that hosting-queue-runner is running. If it's not, restart it using '/etc/init.d/hosting-queue-runner force-reload'. (Since hostmaster changed location, it is normal for hosting-queue-runner to crash at this point.)
- When the debian package is upgraded, it should create a new hostmaster platform automatically. (You can test this with dpkg --configure.)
4. 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:
drush @hostmaster provision-delete vi ~/.drush/hostmaster.alias.drushrc.php
...And edit the alias to make the following changes:
1. change the platform to point to the older platform alias 2. change the platform root path 3. change the site path
During the upgrade, a backup was done and you need to find which backup file it was in the backups directory. Use this backup to redeploy the older platform:
drush @hostmaster provision-deploy ~/backups/hostmaster.date.tgz
5. Recovering a Failed Upgrade
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 could 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.