README.md 5.46 KB
Newer Older
1 2
Consensus: Aegir Policy [![pipeline status](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/badges/master/pipeline.svg)](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/commits/master)
=======================
Dan Friedman's avatar
Dan Friedman committed
3

Dan Friedman's avatar
Dan Friedman committed
4 5 6 7 8
Consensus Enterprises' Aegir policy role.

Overview
--------

9
This role represents a set of sensible defaults for [the Aegir hosting system](https://www.aegirproject.org/) as deployed via the Consensus Aegir role, [consensus.aegir](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir).
Dan Friedman's avatar
Dan Friedman committed
10 11 12 13 14

In general, this set of defaults represents our policy when deploying Aegir
internally at Consensus; by invoking this role out of the box, you can deploy Aegir according to our standards.

Alternately, you can use this role as a baseline, and then selectively override its defaults to customize your own Aegir further.
Dan Friedman's avatar
Dan Friedman committed
15 16 17 18

Requirements
------------

19
Same as [consensus.aegir](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir).
Dan Friedman's avatar
Dan Friedman committed
20

Dan Friedman's avatar
Dan Friedman committed
21 22 23
Example Playbooks
-----------------

24
Example playbook for deploying Aegir according to our standard policy:
Dan Friedman's avatar
Dan Friedman committed
25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52

```yaml
---
- hosts: localhost
  remote_user: root
  roles:
    - ansible-role-aegir-policy
```

Example playbook for deploying Aegir and overriding 2 defaults:

  * Deploy on Apache instead of Nginx.
  * Supply an alternate admin email.

```yaml
---
- hosts: localhost
  remote_user: root

  vars:
    aegir_policy_overrides:
      - aegir_http_service_type: apache
      - aegir_admin_email: [email protected]

  roles:
    - ansible-role-aegir-policy
```

53
Note: this could also be accomplished using [group and host vars](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html#group-and-host-variables) to customize particular Aegir hosts/groups as needed.
Dan Friedman's avatar
Dan Friedman committed
54 55 56 57 58

Role Variables: aegir_policy_defaults
-------------------------------------

The main functionality of consensus.aegir-policy is delivered via the
59
`aegir_policy_defaults` [role variable](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/blob/master/defaults/main.yml). It is a list of sensible default values to be applied to
60
the [variables in the consensus.aegir role](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir/blob/master/defaults/main.yml) and [the other roles we use to deploy MySQL, Nginx, and PHP](#dependencies). See [consensus.aegir's documentation](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir) for details.
Dan Friedman's avatar
Dan Friedman committed
61 62 63

Other Role Variables
--------------------
Dan Friedman's avatar
Dan Friedman committed
64

Dan Friedman's avatar
Dan Friedman committed
65 66
Role variables other than `aegir_policy_defaults` 
are listed below, along with their default values; see also 
67
[defaults/main.yml](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/blob/master/defaults/main.yml):
Dan Friedman's avatar
Dan Friedman committed
68 69 70 71 72

```yaml
aegir_policy_branch: consensus-stable
```

73
By default, we deploy Aegir and its subcomponents (Provision, Drush, etc.) [from source](https://gitlab.com/consensus.enterprises/aegir); this variable indicates what branch to use.
Dan Friedman's avatar
Dan Friedman committed
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101

```yaml
aegir_policy_roles:
  - geerlingguy.mysql
  - geerlingguy.nginx
  - geerlingguy.php
  - consensus.aegir
```

The list of roles to invoke, in order, when deploying Aegir.

```yaml
aegir_perform_legacy_cleanup: false
```

Whether to run scripts that clean up unused/deprecated components when redeploying Aegir on legacy servers.

```yaml
bind_mounts:
  '/var/aegir/backups':
    src: '/opt/var/aegir/backups'
    owner: aegir
    group: aegir
  '/var/lib/mysql':
    src: '/opt/var/lib/mysql'
```

Default set of bind mounts to create for Aegir backups and the MySQL database;
102
this is done via the [consensus.utils](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-utils) role, a subdependency of consensus.aegir. Set `bind_mounts: {}` to skip this step and have `/var/aegir/backups` and `/var/lib/mysql` on the root partition.
Dan Friedman's avatar
Dan Friedman committed
103 104 105 106 107 108 109 110 111 112 113 114 115

```yaml
print_aegir_login_link: True
```

Whether to print a login link (via `drush @hm uli`) for the Aegir front-end after deploying.

```yaml
use_msmtp: True
deploy_msmtp_config: True
msmtp_domain: "localhost"
```

116
Default configuration for the MSMTP MTA to be used by Aegir.
Dan Friedman's avatar
Dan Friedman committed
117 118 119 120

Dependencies
------------

Dan Friedman's avatar
Dan Friedman committed
121
In its default configuration, this role invokes the following roles, in order:
Dan Friedman's avatar
Dan Friedman committed
122

Dan Friedman's avatar
Dan Friedman committed
123 124 125
  - [geerlingguy.mysql](https://github.com/geerlingguy/ansible-role-mysql)
  - [geerlingguy.nginx](https://github.com/geerlingguy/ansible-role-nginx)
  - [geerlingguy.php](https://github.com/geerlingguy/ansible-role-php)
126
  - [consensus.aegir](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir)
Dan Friedman's avatar
Dan Friedman committed
127

128 129
Development and Testing
-----------------------
Dan Friedman's avatar
Dan Friedman committed
130

131
This role is built using [Drumkit](https://drumk.it), and includes 
Dan Friedman's avatar
Dan Friedman committed
132
[tests](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/tree/master/features), written in [Behat](https://behat.org), for use in [our Gitlab CI environment](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/-/jobs). See also Drumkit's [documentation on test support](https://drumk.it).
Dan Friedman's avatar
Dan Friedman committed
133 134 135 136

Issue Tracking
--------------

Dan Friedman's avatar
Dan Friedman committed
137
For bugs, feature requests, etc., please visit the [issue tracker](https://gitlab.com/consensus.enterprises/ansible-roles/ansible-role-aegir-policy/-/boards).
Dan Friedman's avatar
Dan Friedman committed
138 139 140 141

License
-------

Dan Friedman's avatar
Dan Friedman committed
142
GNU AGPLv3
Dan Friedman's avatar
Dan Friedman committed
143 144 145 146

Author Information
------------------

Dan Friedman's avatar
Dan Friedman committed
147
Written by [Christopher Gervais](https://consensus.enterprises/team/christopher/) and [Dan Friedman](https://consensus.enterprises/team/dan/). To contact us, please use our [Web contact form](https://consensus.enterprises/#contact).