David Williamson @ Varilink Computing Ltd
A library of Ansible roles that are used in playbooks to automate the management of Varilink Computing Ltd's IT services. We either use those services internally within Varilink Computing Ltd or to provide services to our customers.
The services are:
- Backup of the hosts that we operate.
- Calendars, including task lists, for our staff.
- DNS lookup on our internal network.
- Dynamic DNS lookup for services hosted on our internal network that we expose externally via our ISP's dynamically provisioned IP address.
- Mail for our own domain and for the domains of our customers.
- WordPress hosting of our own website and those of our customers.
My Services - Docker repository provides the automated means to test these Ansible roles in container based test environments and so is an ideal place to start if you want to understand them better - see also my blog post Testing Ansible Roles Using Containers.
The table List of Roles below lists the roles defined in this repository by Role Name. It indicates whether each role is Deployed explicitly to a host or only as a dependency of another role and also, for each role, which other roles are pulled in as Dependencies.
The table also indicates the deployment Levels that are encapsulated within each role; for example, the wordpress_apache role's main task list deploys the core WordPress host service, whereas its create-site task list deploys a WordPress site on to that host service.
The deployment levels implemented by roles within this repository are:
- host - As above, the core service onto which a domain, project or site can be configured.
- domain - For example, the configuration of the mail service for example.com.
- project - For example, the dynamic DNS entry that must be configured for external backup clients to connect to our on-site backup storage daemon.
- site - As above, the configuration of a WordPress site; for example, test.example.com or www.example.com.
| Role Name | Deployed | Dependencies | Levels |
|---|---|---|---|
| backup_client | explicitly | host | |
| backup_director | explicitly | backup_dropbox 1 mta |
host |
| backup_dropbox | dependency | host | |
| backup_storage | explicitly | backup_dropbox 1 | host |
| calendar | explicitly | host domain |
|
| database | explicitly | host site |
|
| dns | explicitly | host domain site |
|
| dns_api | dependency | host | |
| dns_client | explicitly | host | |
| dynamic_dns | explicitly | dns_api 2 | host project |
| dependency | host | ||
| mail_certificates | explicitly | dns_api 2 | host domain |
| mail_external | explicitly | mail mta |
host domain |
| mail_internal | explicitly | mail mta |
host domain |
| mta | dependency | host | |
| reverse_proxy | explicitly | host site |
|
| wordpress | dependency | mta | host site |
| wordpress_apache | explicitly | wordpress | host site |
| wordpress_nginx | explicitly | wordpress | host site |
1 Only if the backup service is integrated with Dropbox for offline copy of backup media - see Integration with Third-Party Cloud Services below.
2 Only if integration with the Akamai (formerly Linode) domain management services is enabled - see Integration with Third-Party Cloud Services below.
Backup client based on the Bacula Client - see What is Bacula?
This is deployed to every host that is backed up in my automated, backup schedule. It facilitates communication with the host by the backup_director and backup_storage roles so that they may backup the host.
Backup director service based on the Bacula Director and using MariaDB to store its Catalog.
Dropbox integration for making off-site copies of the backup media created by backups of on-site hosts for disaster recovery purposes. This is a dependency of both the backup_director and backup_storage roles if backup integration with Dropbox is enabled.
Backup storage service based on the Bacula Storage component.
CalDAV based calendar service (including task lists) based on the Radicale CalDAV and CardDAV server.
Database service based on the MariaDB server. This is used by both the backup_director role to store its catalog and by the wordpress role for its site databases.
DNS service based on Dnsmasq. We run Dnsmasq on our office network to supplement our ISP's DNS service with additional lookups for hosts, services and projects that are required on that office network.
A very simple role that merely deploys the key for API access to Akamai (formerly Linode) hosted DNS zones for use by both the mail_certificates and dynamic_dns roles, if integration with the Akamai domain management service is enabled - see Integration with Third-Party Cloud Services below.
We deploy this to a single host on our office network so that we're only holding our API access tokens in one place and that is not on a public network.
Role that configures hosts on our office network to use the DNS service provided on that network by the dns role.
Keeps our Akamai based DNS zones up to date with the dynamic IP address provided by our ISP. We do this so that we may expose some services that are hosted on our office network externally without requiring a fixed IP address for our Internet connection.
Implements an IMAP mail server based on Dovecot for hosts that provide a mail service, either internally using our own domain or for customer domains.
In our mail architecture we have two such hosts, one on our office network for our internal staff using the mail_internal role and one hosted externally using the mail_external.
Provides SSL certificates that are obtained from Let's Encrypt for encrypting IMAP and SMTP connections to our mail services.
External (to the office network) mail service using Exim as a Mail Transfer Agent and Dovecot as an IMAP mail server, via the mta and [mail][#mail] roles respectively.
Internal (to the office network) mail service using Exim and Dovecot exactly as the mail_external role does. It integrates with the mail_external role by using it as an SMTP relay for sending emails from our office network to recipients outside of that network and using Fetchmail to fetch emails sent to us.
Implements a Mail Transfer Agent using Exim4 for all hosts that need to send or receive emails.
Reverse proxy service based on Nginx. In our WordPress architecture we use a reverse proxy in front of the WordPress sites.
Base WordPress service - see also wordpress_apache and wordpress_nginx roles. This role implements the common aspects of our WordPress hosting.
WordPress service variant using Apache as a web server with mod_php.
WordPress service variant using Nginx as a web server with PHP-FPM. In time we expect to retire this mode for implementing WordPress sites and base all of our WordPress hosting on the wordpress_apache role.
The roles in this repository support integration with four Cloud service providers as follows:
Akamai (formerly Linode) is our preferred partner for Linux virtual hosts and also domain zone management. The dynamic_dns and mail_certificates roles both support the use of the Linode API service to automate the management of DNS records.
To enable this integration you must:
-
Create an account with Akamai, I believe this must be specifically via linode.com for access to the Linode API service.
-
Create an API personal access token with Read Only access to the Account scope and Read/Write access to the Domains scope. Those access levels and scopes are features of the Linode v4 API service.
-
Set the variable dns_linode_key to the key of the API token that you just created.
Since you can't enable this integration without executing these steps, it is disabled by default. If you don't enable it then both the dynamic_dns and mail_certificates roles are rendered completely redundant and there's no point deploying them to live environments.
The backup service can use a Dropbox account to make off-site copies of backup media for on-site hosts for disaster recovery purposes. To enable this integration, you must:
-
Create a Dropbox account to use. Since you must of course have a Dropbox account for this integration to work, it is disabled by default.
-
Create a top-level folder within your Dropbox account, which will be where the backup service will write its off-site copies to. By default this is expected to be
baculabut you can change the name by setting a different value for thebackup_copy_folderdirectory. -
Set the
backup_linked_to_dropboxvariables to a boolean true YAML value, I recommendyesfor readability.
After you've deployed the backup_director and backup_storage roles with the Drobpox integration enabled, you will have to link the hosts for those roles to your Dropbox account - see Dropbox Headless install via command line. You will need to run the Dropbox daemon and "copy and paste a link in a working browser to create a new account or add your server to an existing account" when prompted.
It's possible to rehearse this using my Services - Docker repository.
The WordPress hosting and mail services both support integration with Let's Encrypt to obtain TLS certificates. In the case of the mail service this relies on Akamai integration (see above) being enabled to support validation via the Let's Encrypt DNS-01 challenge. Certificates for the WordPress hosting service are validated via the Let's Encrypt HTTP-01 challenge and so don't require Akamai integration.
Both the WordPress hosting and mail services can also use self-signed certificates, though of course these are suboptimal compared to those provided by a certification authority.
In the context of Let's Encrypt integration and the use of SSL more generally, see the following variables in the Variables section below:
Our mail service uses Mailgun as an Exim smarthost (SMTP relay) when sending emails externally from our domain or our customers' domains, to enhance deliverability and for access to their service monitoring and management tools. Just as with the Dropbox and Akamai integration, this requires that you have a Mailgun account and so is disabled by default.
To use this integration you must:
-
Have an account with Mailgun.
-
Register each domain that you want to use in the list of Sending domains in the Mailgun dashboard.
-
Configure the domain_smarthost_username and domain_smarthost_userpass variables with the SMTP credentials configured in Mailgun for the domain when you deploy a domain using the mail_certificates role.
Without this integration in place the mail_certificates role will still send emails externally but will do so directly from the host it resides on, which is likely to have an adverse impact on email deliverability and could well get you blacklisted.
The roles in this repository use a number of variables, over and above any Ansible built-in variables that they use. Some of these are internal to the roles only, i.e. it's never necessary for playbooks or the inventories used by those playbooks to set values for them. Others could or must have their values set by playbooks that use these roles or their associated inventories.
The table List of Variables below contains:
-
The variables by Name that could or must have their values set by playbooks that use the roles in this repository or the inventories used by those playbooks.
-
The roles that each of those variables is Used In, as opposed to set by; for example, role A declares role B as one of its dependencies and, in doing so, role A sets the value of a variable that role B uses but that role A does not use. In that example, this table would identify role B as a role that it is used in but not role A.
-
Whether it is Mandatory for playbooks or inventories used by those playbooks to set a value for the variable. The default behaviour if a value is not set is described within the list of Variable Descriptions that follow the table.
-
Where Set (short for "Where (the variable is) set"), specifically in my Services - Docker repository. I use that repository to test the roles within this library in three Test Environments that Services - Docker implements, which are distributed, now and to-be.
Since the test environments in my Services - Docker repository are used for desktop based testing only and not any live services, I can share the values for variables set within them openly, whereas I could not for a live environment since they would in that environment be sensitive data. Thus Services - Docker serves as a useful illustration of how to set the variables used by the roles in this library for anybody wanting to use those roles themselves.
The values used in the Where Set column are one or more of:
- default = Not set in a test environment's inventory or playbooks and so the default value set in the role applies.
- extra = Set at playbook execution time via the
--extra-varsoption. - inventory/all = Set within the all group of the inventory for test environments.
- inventory/external = Set within the external group of the inventory for test environments.
- inventory/internal = Set within the internal group of the inventory for test environments.
- host(s) = Set for one or more specific hosts in the inventory for test environments.
- my-roles = Set in the my-roles wrapper to this role library in Services - Docker . This equates to setting a common value for the variable in the all group of the inventory for all Services - Docker test environments without having to repeat it for all three.
- nowhere = The variable is optional and no value is set, either in a role nor in the inventories and playbooks for test environments.
- playbook = Set directly within project playbooks.
- projects/all = Set within the all group of project playbooks for test environments.
- projects/host(s) = Set for one or more specific host(s) within project playbooks for test environments.
| Name | Used In | Mandatory | Where Set |
|---|---|---|---|
| admin_user | backup_client mta wordpress |
Yes | inventory/all 1 |
| admin_user_email | backup_director backup_storage mail_certificates wordpress wordpress_apache |
Yes | inventory/all |
| backup_archive_media_directory | backup_dropbox backup_storage |
No | default |
| backup_client_director_password | backup_client backup_director |
Yes | inventory/host(s) 2 |
| backup_client_monitor_password | backup_client | Yes | inventory/host(s) 2 |
| backup_copy_folder | backup_director backup_dropbox |
No | inventory/all 3 |
| backup_database_host | backup_director | No | inventory/all 4 |
| backup_database_password | backup_director | No | default 5 |
| backup_database_user | backup_director | No | default 5 |
| backup_director_console_password | backup_director | Yes | inventory/all |
| backup_director_host | database | No | inventory/all 4 |
| backup_director_monitor_password | backup_director | Yes | inventory/all |
| backup_director_name | backup_client backup_director backup_storage |
Yes | inventory/all |
| backup_director_schedules_active | backup_director | No | inventory/all 6 |
| backup_linked_to_dropbox | backup_director backup_storage |
No | default 7 |
| backup_monitor_name | backup_client backup_director backup_storage |
Yes | inventory/all |
| backup_storage_director_password | backup_director backup_storage |
Yes | inventory/all |
| backup_storage_host | backup_director | No | inventory/all 4 |
| backup_storage_monitor_password | backup_storage | Yes | inventory/all |
| backup_storage_name | backup_storage | Yes | inventory/all |
| database_expose_externally | database | No | inventory/all 4 |
| dns_client_nameservers | dns_client | Yes | inventory/external inventory/internal inventory/host(s) 8 |
| dns_client_options | dns_client | No | nowhere |
| dns_host_patterns | dns | Yes | inventory/external 9 |
| dns_linode_key | dns_api dynamic_dns |
Yes | inventory/all 7 |
| dns_upstream_nameservers | dns | Yes | inventory/external inventory/internal 10 |
| domain_country | mail_external | No | projects/all |
| domain_locality | mail_external | No | projects/all |
| domain_name | dns dynamic_dns mail_certificates mail_external reverse_proxy wordpress_apache wordpress_nginx |
Yes | projects/all |
| domain_organisation | mail_external wordpress |
Yes | projects/all |
| domain_organisation_unit | mail_external | No | nowhere |
| domain_smarthost_username | mail_external | No | nowhere 11 |
| domain_smarthost_userpass | mail_external | No | nowhere 11 |
| domain_state | mail_external | No | projects/all |
| domain_users | mail_external mail_internal |
Yes | projects/all |
| dynamic_dns_crontab_stride | dynamic_dns | No | default |
| dynamic_dns_records_dir | dynamic_dns | No | default |
| home_domain | backup_director backup_storage dns dns_client mail_external mail_internal mta |
Yes | inventory/all |
| host_enabled_for_ssl | reverse_proxy | No | inventory/internal inventory/host(s) 12 |
| hosts_to_roles_map | backup_director domain.yml |
Yes | inventory/all |
| mail_uses_ca | mail_certificates mail_external |
No | default 13 |
| mta_smarthost_hostname | mta | Yes | |
| mta_smarthost_port | mta | Yes | |
| mta_smarthost_username | mta | Yes | |
| mta_smarthost_userpass | mta | Yes | |
| office_subnet | mail_internal | Yes | inventory/all |
| playbook_subdomains | wordpress | No | playbook |
| project_dynamic_dns_records | dynamic_dns | Yes | projects/all |
| run_subdomains | wordpress | No | extra |
| subdomains_filter | wordpress | No | playbook |
| unsafe_writes | dns_client | No | my-roles |
| wordpress_expose_externally | wordpress_apache | No | inventory/all 4 |
| wordpress_site_admin_email | wordpress | No | default 14 |
| wordpress_site_admin_password | wordpress | Yes | projects/host(s) |
| wordpress_site_admin_user | wordpress | No | inventory/all |
| wordpress_site_client_max_body_size | wordpress_nginx | No | default |
| wordpress_site_database_host | database wordpress |
No | inventory/external inventory/internal 4 |
| wordpress_site_database_password | database wordpress |
Yes | projects/host(s) |
| wordpress_site_dns_host | dns | No | inventory/external inventory/internal |
| wordpress_site_expose_externally | wordpress_apache | No | |
| wordpress_site_plugins | wordpress | No | |
| wordpress_site_reverse_proxy_host | dns wordpress_apache |
No | inventory/external inventory/internal playbook 4 15 |
| wordpress_site_reverse_proxy_pass_port | reverse_proxy wordpress_apache |
Yes | projects/all |
| wordpress_site_subdomain | dns reverse_proxy wordpress wordpress_apache wordpress_nginx |
Yes | |
| wordpress_site_uses_ssl | reverse_proxy wordpress_nginx |
No |
These are notes for the Where Set entries above. Where there is more than one Where Set for a variable, the notes apply collectively to them all.
1 Variables set here are not necessarily used by all hosts in the test environment. I operate the principle that if a single value applies wherever the variable is used, then that value is set in the all group. Since I apply that principle throughout I do not repeat this note on other entries.
2 The values set are unique to each host that is to be backed up.
3 I use the same Dropbox account for live use and for testing using Services - Docker. In live, I let the role default value for backup_copy_folder apply and so must override that default in test to keep live and test separate.
4 Only set for the distributed test environment where services are not co-hosted and so they must be configured with the other host(s) that they must connect to over the network.
5 The role's default credentials are insecure and so in a live environment it is recommended to set more secure values.
6 The role default is that backup schedules are active, but I make them inactive in test environments because I want to execute backups manually there and not have them run automatically.
7 Since integration with third-party Cloud services that require accounts with services providers are disabled by default in the test environments.
8 The DNS servers on the internal and external networks in the test environments are exceptions from the values that are applied to all other hosts on each of those networks.
9 The role's default value applies to the hosts on the internal network in test environments.
10 Though the variable is only actually used by the DNS servers on each network in the test environment; see also 1.
11 These must be set to integrate the mail_external role with a Cloud email relay provider, we use Mailgun. This is disabled by default in the test environments but is strongly recommended for live use.
12 In the test environments and in the live environment, I choose to not use SSL for websites on the internal network. A single host on the internal network has the value overriden back to true. This is the host for websites that are exposed externally from the internal network.
13 The test environments use self-signed certificates so that they're not reliant on Let's Encrypt integration. In live use, it is recommended to use certification authority certificates.
14 Defaults to the value set for admin_user_email.
15 The playbook entries
A description of each of the variables in the table above now follows.
The operating system user login for the main admin user who supports the Varilink services. Of course this is always a user in the home_domain.
The email address for the admin_user. This is not simply admin_user@home_domain since we use first names only for our office network logins but we use fname.lname for our email addresses.
The directory that the backup storage daemon uses to store archive media in. This defaults to /var/local/bacula unless an alternative value is provided via the playbook or inventory.
The password that the backup director must use to connect to a backup client. For good security, this should be unique to each backup client and meet length and complexity standards.
The password that the backup monitor must use to connect to a backup client. For good security, this should be unique to each backup client and meet length and complexity standards. Unlike the backup director, the backup monitor is a desktop application and so there is no role in this library corresponding to it.
The top-level folder within Dropbox for off-site copies of backup files. This defaults to bacula unless and alternative value if provided via the playbook or inventory.
The host of the database that's used to store the backup catalogue. This can be omitted in which case the backup director will assume that the backup database is co-located on the same host as itself and use a local socket connection to the database.
The password that the backup director uses to connect to the backup database. If this is omitted it will default to "bacula". A more secure value should be provided.
The user that the backup director uses to connect to the backup database. If this is omitted it will default to "bacula". A more secure value should be provided.
The password that the backup console must use to connect to the backup director. The backup console is a desktop application and so there is no role in this library corresponding to it.
The host of the backup director. This is used when creating the backup user account in the backup database. If it is omitted then it will be assumed that the backup director is co-located with the host of the backup database.
The password that the backup monitor must use to connect to the backup director. For good security, this should meet length and complexity standards. The backup monitor is a desktop application and so there is no role in this library corresponding to it.
The name by which the backup director identifies itself to backup clients and the backup storage daemon.
Whether the backup schedules are active or not. By default this is set to the boolean true value. It only needs to be set in a playbook or inventory if a value that Jinja evaluates to false is required in order to disable automatic backup job scheduling. This can be useful during testing of backup jobs when it's convenient to run them manually instead.
The name by which the backup monitor identifies itself to backup clients, the backup director and the backup storage daemon.
The password that the backup director must use to connect to the backup storage daemon. For good security, this should meet length and complexity standards.
The host of the storage daemon that the backup director must connect to.
The password that the backup monitor must use to connect to the backup storage daemon. For good security, this should meet length and complexity standards.
The name by which the backup storage daemon identifies itself.
Whether to expose the database service on a database host to the external network interface or not.
If this isn't set then it defaults to the boolean value false, meaning that the database service is not exposed to the external network interface. This is fine so long as services that use that database are on the same host. If that's the case then obviously for security reasons the database service should not be exposed externally.
If services external to the database host use its database service then this should be set to a value that Jinja understands to be true.
The IP addresses of DNS nameservers that a DNS client should use. These are used in the /etc/resolv.conf file for each host.
Options to be set in the /etc/resolv.conf file for each host. If this is provided then it must be an array of strings, each of which will be added after option in a line within /etc/resolv.conf. This variable can be omitted if there are no options to set.
A list of patterns for targeting inventory hosts; see Patterns: targeting hosts and groups. These are used by the dns role to determine the hosts that a DNS server will provide resolution services for. Each member of the array must be a dictionary object with two attributes, string (the pattern itself) and description (of the pattern).
The personal access token used to access the Linode DNS API service. This is self-evidently highly sensitive data.
The IP addresses of upstream nameservers to configure in the DNS service. As the name suggests, these are the nameservers that Dnsmasq passes requests to that it is not configured to answer directly itself.
The name of a domain corresponding to either our own internal services (varilink.co.uk) or those of a customer (e.g. bennerleyviaduct.org.uk).
The name of a domain's organisation for either our own internal services ("Varilink Computing Ltd") or those of a customer (e.g. "The Friends of Bennerley Viaduct").
The username to use when connecting to our email gateway provider to send emails externally for a domain.
The password to use when connecting to our email gateway provider to send emails externally for a domain.
An array of users for either our own internal services domain (varilink.co.uk) or a customer domain (e.g. bennerleyviaduct.org.uk). Each entry in the domain can contain the following attributes:
- username
- passwd
- fname
- lname
How many minutes within an hour between updates to dynamic DNS records. If this isn't set by a playbook or inventory then it takes the role's default value, which is fifteen minutes.
The directory that holds dynamic DNS entries for each supported domain. If this isn't set by a playbook or inventory then it takes the role's default value, which is /usr/local/etc/dynamic-dns-domains.
The home domain for any inventory as opposed to any customer domains that are served. In our case we set this to varilink.co.uk when we use this roles library.
This variable determines whether or not the capability to enable SSL for WordPress sites is enabled when the reverse_proxy role is deployed to a host. We serve all our WordPress sites from behind a reverse proxy, with the reverse proxy handling SSL if it is required for the site.
By default this is set to yes, which YAML recognises as boolean truth. It can be overridden to no on hosts on the internal network that will never serve WordPress sites externally and having so few staff that's what we do.
This is a dictionary object, the keys of which are the names of each host in the inventory. Each host entry should have its value set to the list of roles that are deployed to that host by your playbooks.
Whether to use a Certification Authority or not (self-signed) for mail certificates. By default this is set to the boolean true, i.e. we do use a Certification Authority.
It's possible to override this to a value that Jinja evaluates as false in order to use self-signed certificates instead. This is sometimes useful during testing to avoid repeated requests to Let's Encrypt that might breach the threshold allowed for. The override can be applied at inventory level or for selected domains.
The hostname of the smarthost that a host uses to relay emails. In our chosen topography for email services the mapping of hosts to smarthosts is as follows:
-
All hosts on the internal office network with the exception of our internal mail server use our internal mail server as a smarthost.
-
Our internal mail server uses our external mail servers as a smart host.
-
All hosts on the Internet, external to our internal office network, with the exception of our external mail server use our external mail server as a smarthost.
-
Our external mail server uses our email gateway service provider's smarthost.
The port that a host uses when connecting to a smarthost to relay emails.
The username that a host uses when connecting to a smarthost to relay emails.
The password that a host uses when connecting to a smarthost to relay emails.
The IP address mask for the office network. The internal mail server relays email unconditionally for clients on this network.
See Controlling the WordPress Sites Impacted by Project Playbooks below.
See Controlling the WordPress Sites Impacted by Project Playbooks below.
See Controlling the WordPress Sites Impacted by Project Playbooks below.
If set to a true value, this enables the dns_client role to write to /etc/hosts and /etc/resolv.conf in an unsafe manner. This is necessary only in a Docker container environment because of the way that Docker mounts a copy of the host's /etc/resolv.conf file within containers. Hence this variable defaults to a false value, which is the value it should have in all other scenarios.
Whether to expose an Apache based WordPress service on the external network interface or not.
When we use Apache for WordPress sites we do so behind an Nginx reverse proxy, usually with both on the same host. Where this is the case, the Apache service should listen on the local network interface only, since it is only the reverse proxy on the same host that accesses it. For this reason a default value of false is set for this variable.
If a host for Apache WordPress sites is paired with an Nginx reverse proxy on another host, then this variable should be set to true, so that the Apache service listens on external interfaces and thus is available to the Nginx service.
Whatever is set for this variable on a host, it can be countermanded at a WordPress site level using the wordpress_site_expose_externally variable.
When each WordPress site is created so is an initial administrator user account. This variable sets the email address for that account. It can be omitted, in which case the value of the admin_user_email variable will be used instead.
The name of the administrator user account referred to in the description of the wordpress_site_admin_email variable. This can not be omitted.
The name of the administrator user account referred to in the description of the wordpress_site_admin_email variable. This can also be omitted, in which case the value of the admin_user variable will be used instead.
If this variable is set then it dictates the maximum size for file uploads in WordPress in the web server(s). The value must still be adjusted in WordPress itself. If it isn't set then the default values apply.
The host that a WordPress site uses for its database. If this is defined then it will be used by the wordpress role to set the value of dbhost when it creates the configuration file for a WordPress site. If it isn't defined then the wordpress role will set dbhost to localhost, i.e. it will assume that the database is co-hosted with the WordPress site.
The password that a WordPress site should use to connect to its database.
Whether an Apache based WordPress site is exposed on the external network interface - see wordpress_expose_externally. If this is omitted then the value of wordpress_expose_externally will apply.
If this variable is defined then it is used by roles as follows:
- database - to associate a host when it creates the user for a WordPress site to connect to that its database.
- reverse_proxy - to establish the IP address that requests for a WordPress site should be passed through to.
If it is not defined then both roles assume that the WordPress site is co-hosted with them.
If this is defined it should be a dictionary object, the keys of which are the names of plugins to be installed and activated for a WordPress site. Each of these may optionally have a version attribute set, which will of course dictate the version of the plugin to be installed. Note that any plugins that are present that are not listed in a provided wordpress_site_plugins variable will be deactivated if necessary and uninstalled.
The port associated with a WordPress site that uses Apache. We implement our Apache WordPress service behind and Nginx reverse proxy, so this is the port that the reverse proxy will pass requests to for that WordPress site.
The subdomain of a WordPress site. There can be multiple WordPress sites for a domain, each distinguished by a separate subdomain; for example 'www', 'test', etc.
This variable controls whether a WordPress site uses SSL or not. By default it is set to the same value as the variable host_enabled_for_ssl, so if a reverse proxy host is enabled for SSL then by default all the WordPress sites that it serves use SSL and if it isn't then by default all the WordPress sites that it serves don't use SSL.
If a reverse proxy host is enabled for SSL then its possible to override the default value of wordpress_site_uses_ssl when deploying WordPress sites to it. If you set the variable to no then the deployed WordPress site will not use SSL. You might do this for a reverse proxy host that serves some WordPress sites that are exposed externally and others that are only exposed internally.
Under List of Roles above there are six roles that support the site deployment level:
- database
- dns
- reverse_proxy
- wordpress
- wordpress_apache
- wordpress_nginx
To manage WordPress sites these roles should be used in projects that typically manage sites that correspond to one or more subdomains of a project domain; for example dev, test and www subdomains for the domain example.com, which therefore corresponds to the WordPress sites dev.example.com, test.example.com and www.example.com. Using these roles, you can act on multiple WordPress sites for a project domain in a single playbook run.
Between them, three of the variables listed under Variable Descriptions above control the WordPress sites for a project domain that a playbook run will act upon in coordination with the variables whose names start wordpress_site_ that are defined within the project's inventory. Those three variables are:
playbook_subdomainsrun_subdomainssubdomains_filter
When set, each of these variables takes as its value a comma separated list of domains; for example "www", "dev,test", etc. Use these variables as follows:
playbook_subdomains
Set this in the playbook at playbook level to make settingrun_subdomains(see below) optional. This is purely a convenience when testing ahead of go-live. For live WordPress sites it is recommended not to define this variable so that on each playbook run a conscious choice must be made of the subdomains to act upon so that you don't inadvertently impact live sites.
run_subdomains
Set this via--extra-varswhen running a playbook. This should be made mandatory by not definingplaybook_subdomains(see above) for playbooks that might impact live sites. The subdomains scope of a playbook run is either the value ofplaybook_subdomains(ifrun_subdomainsis not defined) orrun_subdomains(ifplaybook_subdomainsis not defined) or the intersection of the two if both are defined. When both are defined,run_subdomainsprovides a means to filter down the subdomains scope of a playbook defined byplaybook_subdomains.
subdomains_filter
Set this at play or task level within playbooks to further filter down the subdomains scope of the playbook for specific tasks only a subset of that scope applies.
A good way to understand how to use these variables is to examine the playbooks in the following folders in my Services - Docker repository:
envs/distributed/playbooks/customer/envs/now/playbooks/customer/envs/to-be/playbooks/customer/