Revision of Automatic upgrades with Debian packages from Fri, 02/08/2013 - 23:56

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.

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:

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.

1. 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.)
2. Add modules/features/themes/libraries/whatever to the makefile. Ex:
       projects[] = token
    projects[] = views
3. 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.