One of the most powerful features of Aegir is the way it can help you to upgrade large numbers of websites safely.

For example, you may have dozens of sites hosted on a drupal 6.18 codebase. But suddenly the 6.19 release comes out with vital security fixes. Previously you'd have to go to each site, back up the files and database, upload the new codebase, run update.php, check everything worked and then onto the next site.

With Aegir you simply click a button in the frontend and it handles everything. This is called 'migrating' sites in Aegir terminology, because it might be used in more cases than simply upgrading the main codebase. For example you may have different 'platforms' with different mixes of contrib modules and themes and charge clients for tiers of 'basic', 'advanced' and 'gold' packages. When they choose to move from basic to advance, you simply migrate their site.

Other examples of using Migrate include:

• moving a standard Drupal site to a Pressflow platform for performance enhancements
• renaming a site (giving it a new URL entirely)
• the Clone feature (discussed in later chapters) is a subsidiary of Migrate, except it doesn't move but copy the site.

How to migrate a site

Enabling the feature

Aegir version 2.x

• The "Site migration" feature is enable by default. So you don't have to enable it.

Aegir version 1.x

• By default, Migrate is not enabled in Aegir after a fresh installation, as it is an optional feature. This means that the 'Migrate' button is not immediately present in the list of available tasks for a site.
• To enable the Migrate feature, simply go to /admin/hosting/features and check the Migrate feature. Submit the form and then return to the site node, and you'll see that the Migrate task is now available.

Migrating a site - the Migrate form

In the Aegir frontend, click on the website that you want to migrate. As per usual, in the 'Site view' you are present with some summary information about the site, as well as a list of available tasks. Click the the 'Run' button for the 'Migrate' task. A modalframe dialog will appear in your browser.

The Migrate form has several options. These are:

• Domain name (this is already the domain of the existing site. If you are intending to simply rename the site (give it a new URL altogether), you can simply change this field and leave the target platform be the 'current platform'. This will make the site accessible under the new URL.

• Platform selection. A radio selection of available platforms on the Aegir system. Certain platforms will be un-selectable. This is because they contain 'Errors' - that is, they contain versions of packages (modules, libraries or themes) that are of an older version than that of the original platform. You cannot upgrade a site to older versions of the same package.

Upgrades, warnings, errors?

What's this about upgrades, warnings and errors on each potential platform to migrate the site to?

Up until now you might be forgiven for thinking that Aegir is simply automating the install of sites and creating Apache vhosts and databases.

The truth is, Aegir actually is a much more advanced tool than that. It keeps a running registry in its database of your Platforms and Sites and what modules, themes, libraries and install profiles are available on platforms and installed on sites.

Not only does it keep track of what these packages are, but it also keeps track of what version of a package is installed (say, Views 6.x-2.11), and whether it is actually an enabled module or not.

The Migrate task, despite its name, is the tool for upgrading your site, because the Migrate code actually invokes the command drush updatedb in the backend, automatically. drush updatedb is the equivalent of running '/update.php' in your browser against your site.

In this way, when the time comes (and it always does) to Migrate your site, Aegir is able to intelligently analyse the available platforms on the system and make a sane judgement on where you can upgrade your site to. The logic is as follows:

1. Current platform has module X, schema version 6002 and 6003
2. Site module has module X, schema version 6003 installed
3. Target platform A has module X, schema version 6002. Site cannot be upgraded to an older schema version. An error.
4. Target platform B does not have module X at all. Theoretically this is still a possible upgrade, but module X will probably be disabled by Drupal's upgrade logic during the process. This is a warning.
5. Target platform C has module X, schema version 6003. Site is upgradeable, there is no change.
6. Target platform D has module X, schema version 6004. Site is upgradeable. There is a module update to be performed.

In the logic laid out above, examples 4, 5 ,6, or platforms B, C and D would be listed as valid target platforms. Target platform D would actually upgrade the site's module to a newer version, which may involve database updates.

To view the schema differences between current and target platforms in this way, click the 'Compare platforms' link against each target platform in the form.

If your intention is to upgrade your site between versions of any package (this can include core or contrib!), you need to make sure the relevant packages are present and up to date on the platform you want to migrate to. Aegir can only try and make this judgement call based on the information you feed into the system by adding and verifying platforms with the correct components.

If you've had to download extra packages to the target platform to make them possible candidates for an upgrade, you may need to visit that platform node in the Aegir frontend, and run the Verify task against the site (this is a re-runnable task). This updates Aegir's registry of information about all the packages on the platform.

Migrating

Select the relevant target platform and click 'Migrate' to submit the form. The modalframe dialog will close and Aegir will spawn a new Migrate task into the Task queue, and process it on the next cron run.

The process of Migration in the backend occurs automatically, like all Aegir tasks, and is as follows:

• The site is placed into maintenance or 'site offline mode' as a precaution. Safety first!
• A 'backup' task is implied silently. The site and its database are backed up into a tarball. Still safety first!
• Depending on the settings sent to the backend (are we migrating the site under its current name, or just renaming the site, or renaming the site and migrating as well), various metadata regarding the site is updated
• If we are moving to a new platform (upgrading, not just renaming), the backup tarball that was made earlier, is used in a silent 'provision-deploy' command, which essentially unpacks the tarball into the target platform and creates a new database and database user for the site, importing the database dump that was made in the backup
• The deploy task above, invokes drush updatedb, effectively upgrading the site by calling all hook_update() functions.
• Various bits and pieces are fixed up, such as paths to files in the 'files' table of the database.
• Caches are cleared
• A verify task is run, settings.php and apache vhost are updated to reflect the new path (new platform) and new database credentials, site gets brought back out of maintenance mode.
• If all went well and nothing has fatally errored here, we remove the old copy of the site from the previous platform (it wasn't touched til now, other than backing it up)

Potential errors?

If something goes wrong during all this work, the metadata reflecting where the site is located on the system (which platform it is on) and other information is reverted. The task will become 'red' in the task queue, indicating an error.

Aegir will attempt to restore the site's vhost and settings.php to reflect the original platform and database credentials, and bring the site out of maintenance, in an effort to return the site to a state where it was prior to the Migrate.

The user may be requried to manually recover from this error depending on what has occurred. Nonetheless, remember that a backup was made early on, and this can be used to restore the site easily.