Unverified Commit 1cbbd6e6 authored by Colan Schwartz's avatar Colan Schwartz Committed by GitHub

Merge pull request #37 from aegir-project/distros

New documentation for deployment strategies (including Composer), distributions, and remote servers.
parents 2566aa34 26757b0b
......@@ -3,7 +3,7 @@ Contributed extensions
[TOC]
Note that the support and development status varies for these. Please evaluate each extension for yourself (or [ask the advice of an expert]()) before installing them on a production Aegir system.
Note that the support and development status varies for these. Please evaluate each extension for yourself (or [ask the advice of an expert](/community)) before installing them on a production Aegir system.
"Golden" Contrib
......@@ -62,10 +62,19 @@ However, we recommend instead maintaining a custom Aegir makefile that can inclu
Aegir Cloud allows Aegir to create servers directly in cloud hosting providers like IBM Softlayer and Amazon Web Services.
#### [Aegir Composer](https://www.drupal.org/project/hosting_composer)
This module adds the ability to install dependencies using Composer. In addition, it provides the [Aegir Deploy](/usage/advanced/deployment/) module that improves the platform form's support for an increasing number of platform deployment strategies. Finally, it provides a couple new such strategies, including the building platforms from Composer packages via project templates, and git-based deployments than maintain platform immutability.
#### [Aegir Config Management](https://www.drupal.org/project/aegir_config)
This module provides config-export and config-import commands for Aegir.
#### [Aegir Distributions](https://www.drupal.org/project/hosting_distribution)
This module simplifies and further automates platform maintenance and site updates. A distribution is a "type" or "flavour" of platform. It could just as easily be an off-the-shelf package like OpenAtrium or Thunder, as a custom cobe-base specific to a client's use-case.
#### [Aegir Feeds](https://www.drupal.org/project/aegir_feeds)
Provides [Feeds](https://www.drupal.org/project/feeds) integration with Aegir.
......@@ -84,6 +93,10 @@ This module adds [Kubernetes](http://kubernetes.io) support by allowing for host
Allow inter-communication between Aegir servers (to address the "smart nodes" use case). The point is to centralize information to facilitate management of multiple servers.
#### [Aegir Objects](https://www.drupal.org/project/aegir_objects)
This API-only module provides some base classes and traits to make object-oriented development of Aegir 3.x easier. It does not provide any functionality of it's own, and should only be installed when required by another extension.
#### [Aegir Reporting](https://www.drupal.org/project/hosting_report)
This module provides a reporting framework. It builds atop the [Aegir Monitoring API](https://www.drupal.org/project/hosting_monitor) to report on the health of hosted sites. It ships with some basic probes, but is intended to be extended, as with [Aegir Site Audit](https://www.drupal.org/project/hosting_site_audit).
......
......@@ -3,8 +3,10 @@ Aegir Hosting System
Aegir is a powerful hosting system that sits alongside a LAMP or LEMP server to create, deploy and manage Drupal sites.
Once Aegir is installed, you can setup a Drupal site in just a few clicks. Aegir creates the web server's site configuration files, the site's database, runs the Drupal installation process and reloads the relevant services, all automatically.
With Aegir, you can setup a Drupal site in just a few clicks. Aegir creates the web server's site configuration files, the site's database, runs the Drupal installation process and reloads the relevant services, all automatically.
This documentation will help you understand Aegir and how to get it set up and running, as well as how to use it on an ongoing basis.
This documentation will help you understand Aegir and how [install it](/install.md), as well as how to [use it](/usage.md) on an ongoing basis. In addition, for advanced users, you'll find a [list of extensions](extend/contrib.md), as well as other mechanisms you can use to [extend or customize its behaviour](extend.md). Finally, for anyone interested in customizing Aegir or contributing bug fixes or new features, there's a section on [developing Aegir](develop.md).
Aegir is Free/Libre Open-source Software, and so is driven by its welcoming and inclusive [community](community.md).
If you need professional support for your Aegir installation, check out the [Service Providers page](/community/services.md).
Deployment Strategies
=====================
[TOC]
"Deployment strategies" refer to the method used to deploy a platform in Aegir. Aegir core supports only manual and Drush makefile-based builds by default. However, a number of other options have become available.
By enabling the "Aegir Deploy" module, these options are moved into fieldsets controlled by a radio option list, in order to consolidate and clean up the platform node form.
Manual deployment
-----------------
In the beginning, Aegir did not support any automated build processes for platforms. It assumed that the platform had already been built, and so the platform form only prompted for a local system path. This remains the default, and allows systems outside of Aegir to build platforms without Aegir's knowledge or possible interference.
Makefile deployment
-------------------
The first automated build process supported by Aegir was Drush Make. A field is provided to enter the path or URL of a Drush makefile from which to build the platform. This has become the recommended best-practice for Drupal platforms through the 7.x release cycle.
Git-based platform management
-----------------------------
With the broad adoption of Git by the Drupal community, the ability to manage platforms using it was added. In order to support advanced development practices, additional features, such as the ability to pull in changes to the platform, and checkout specific commits were added. This is best-suited for hosting single custom sites, since it adds significant risk to multi-site deployments.
Git deployment
--------------
Since multi-site deployments require an immutable platform, an alternative Git deployment mechanism was recently added. It only performs the initial clone of the platform code-base, and treats it as immutable thereafter.
Composer deployment
-------------------
In order to host Drupal 8 distributions, a new deployment option was added that builds a platform from a Composer package. It takes a template project name (and optional version) which it then provides to Composer's `create-project` command.
### Composer install
While not specific to the `create-project` mechanism, Aegir will now scan for a `composer.lock` file, and run `composer install`, in order to install a platforms dependencies.
Distributions
=============
[TOC]
The [Aegir Distributions module](https://www.drupal.org/project/hosting_distribution) simplifies and further automates platform maintenance and site updates.
It extends the Aegir Hosting System to add a concept of "distributions". According to [drupal.org](https://www.drupal.org/project/project_distribution):
> Distributions provide site features and functions for a specific type of site as a single download containing Drupal core, contributed modules, themes, and pre-defined configuration. They make it possible to quickly set up a complex, use-specific site in fewer steps than if installing and configuring elements individually.
In Aegir terminology, a distribution is a "type" or "flavour" of platform (i. e., code-base). It could just as easily be an off-the-shelf package like OpenAtrium or Thunder, as a custom cobe-base specific to a client's use-case.
Background
----------
At its most basic, distributions are intended to simplify updating sites to the latest platform that is appropriate for them. It reduces the amount of contextual knowledge required to keep sites up-to-date.
Let's take a minute to explore the problems that distributions help to solve. For the sake of simplicity, let's assume that we have just a basic single-server Aegir installation, on which we're hosting a couple Drupal 7 and a couple Drupal 8 sites.
When a Drupal Security Advisory is released for Drupal 8, we need to build an updated D8 platform, then migrate our sites from the old D8 platform to the new one.
We first take a look at the existing platform node, which contains crucial information, such as the Drush makefile or Git repository from which the platform was built. Based on that, we can take the appropriate actions to build an up-to-date platform (i.e., update a makefile, merge an upstream git repository, etc.)
We then need to create a new platform node. We'll want to be careful about how we name it, so as to provide clear indications for later steps. One common practice is to append a unique identifier to the platform name. This could be:
* a version number (e.g. `Drupal 7.54`);
* a date-stamp (e.g. `Drupal 7 2017-03-14`); or a
* build iteration (e.g. `Drupal 7 build123`).
Once an up-to-date platform is ready, we then need to go back to the old platform, and trigger a 'migrate' task. Alternatively, we could visit each site individually and trigger 'migrate' tasks. Either way, while `migrate` is an effective description of the process, it is not at all intuitive that this is the process used to update a site. This is a common source of confusion for users new to Aegir.
Once we click the 'migrate' button, we're presented with a list of platforms to choose from. Here is where our platform naming from earlier becomes important. Hopefully the appropriate choice is reasonably obvious. However, in addition to the intended upgrade target, we'll also be offered, at least, the Drupal 8 platform, in this scenario. If you maintain multiple types of platforms, this choice can quickly become confusing, and lead to errors from which it can be difficult to recover.
If we wanted to update sites individually, then we'd need to repeat this possibly error-prone process for each of them. We're also offered the chance to change the site's URL, effectively renaming it. While certainly helpful functionality to have available, it is, again, just a distraction to our goal of updating the sites.
Let's next take a look at how distributions help with this scenario.
Basic Usage
-----------
Once enabled, this module provides a 'distribution' content-type, as well as adds a "Distribution" field to platform nodes. To begin, we'll create a distribution node (/node/add/distribution). Let's call it "Drupal7" for this example.
Then, we go back to each of our existing Drupal 7 platforms, edit them, and select "Drupal7" in the distribution field. This will also add a link to our distribution when we view these platforms. Visiting the distribution again, we'll now see a list of the platforms we just added.
If we then edit the "Drupal7" distribution node, we'll see a new `upgrade target` field. Here we select the newer platform that we just created earlier. We still have to be careful here, as decribed above. However, we only need to make this selection once, whenever we add a more up-to-date platform. With the addition of the "distribution updates" functionality described in the "Advanced Usage" section, the upgrade target is even updated for us, further simplifying this process.
Having designated an upgrade target, all other platforms using this distribution are automatically locked, making it impossible for new sites to be built on out-of-date platforms.
In addition, any platforms using this distribution will now "know" where it's sites need to be migrated in order to be updated. As a result, a new `Upgrade` task is now available on the out-of-date platforms, and all sites hosted on those platforms.
Running an `Upgrade` task provides a summary of the updates that will take place, and provides "Compare" links that will give details in a side-by-side table. If you were to click the "Confirm" button, a migrate task would be scheduled behind the scenes, that automatically specifies the "upgrade target" platform.
The `Upgrade` task is only available when appropriate. So, for example, sites on the "upgrade target" platform, are already up-to-date (by definition), and so the `Upgrade` task is disabled.
Advanced Usage
--------------
Automating the process of building new platforms is currently under development. This feature will include a queue to regularly check for updates to a platform, as well as webhooks, that will allow for new platforms to be created automatically, whenever a updates to a platform are required.
Distribution Updates
====================
[TOC]
The process of automatically building new platforms when needed has also been automated through distributions. There are a variety of update types, including tracking stock distributions published on drupal.org, as well as changes to a Drush makefile or a git repository.
Distribution updates keep an internal "signature" of the current upgrade target. For example, the Drush Makefile plugin stores an MD5 hash of the makefile, whereas the Git plugin stores a commit hash. This allows the updates system to check for the latest source, calculate a new signature, and thus determine whether an update is required.
Each distribution update type plugin includes a queue to regularly check for updates to all such distributions. This queue simply triggers the update check. This, in turn, creates new platforms automatically, whenever an update to a platform is required.
For more responsive update checks, such as kicking off a CI/CD process, webhooks are [under development](https://www.drupal.org/node/2868455).
Update types
------------
### Manual updates
By default, distributions don't assume anything about how their constituent platforms are created. As such, you can continue to use whatever your current mechanism is for keeping your platforms up-to-date. By setting the `upgrade target` fields manually, you still get all the benefits of distributions (`Upgrade` tasks, automatic locking of deprecated platforms, etc.)
### Drush makefiles
Distributions can track the contents of Drush makefiles. By calculating the md5 hash of a makefile and comparing it to the one it recorded last time it updated its platform, it can determine whether a new update is required.
### Git repositories
Git repositories that contain a Drupal code-base can also be used to automatically update distributions. Tracking a Git reference such as a branch (the default) will trigger a new platform build whenever a new commit is added to the tracked branch.
Specific tags or commits can also be referenced though they'll need to be changed manually, in order to update the distribution. The ability to track a Git repository based on tag patterns is currently [under development](https://www.drupal.org/node/2869061).
### Stock distributions
Drupal.org hosts a wide range of distribution projects, along with canonical update data for each. This is used by Drupal core's update check system, as well as Drush Make and other package management commands.
As a result, we can track such "stock" distributions by checking their latest update data against the version of our current upgrade target. As soon as a new release is published, a new platform will be built, set as upgrade target, and all other platforms in the distribution locked.
Behind the scenes, stock updates leverage the Drush makefile update mechanism, by creating a Drush makefile where the stock distribution name, along with version, checksum, and so forth, are injected as a "core" package.
### Composer packages
The Aegir Composer module adds support for building platforms using `composer create-project`. However, Drupal's Composer package publishing system is not yet mature enough to support this. We will support this as soon as it becomes possible. See [this issue](https://www.drupal.org/node/2874000) for the current status of this effort..
......@@ -39,6 +39,10 @@ pages:
- 'SSL': 'usage/advanced/ssl.md'
- 'Access control': 'usage/advanced/clients.md'
- 'ProvisionACL': 'usage/advanced/provisionacl.md'
- 'Distributions': 'usage/advanced/distributions.md'
- 'Distributions':
- 'Updates': 'usage/advanced/distributions/updates.md'
- 'Deployment strategies': 'usage/advanced/deployment.md'
- 'Extending Aegir': 'extend.md'
- 'Extending Aegir':
- 'Frontend': 'extend/frontend.md'
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment