Trellis

Trellis is a set of Ansible playbooks to automatically configure servers and deploy WordPress sites. It easily creates development environments with Vagrant to help achieve development & production parity.

Configure complete Bedrock-based WordPress ready servers with a single command:

	Command
Development	vagrant up
Staging/Production	ansible-playbook -i hosts/production server.yml
Deploying	./deploy.sh production <site name>

What's included

Trellis will configure a server with the following and more:

• Ubuntu 14.04 Trusty LTS
• Nginx (with optional FastCGI micro-caching)
• PHP 5.6 (or HHVM)
• MariaDB as a drop-in MySQL replacement (but better)
• SSL support (A+ on https://www.ssllabs.com/ssltest/)
• Composer
• WP-CLI
• sSMTP (mail delivery)
• Memcached
• Fail2ban
• ferm

Requirements

• Ansible >= 1.9.2 - Install • Docs • Windows wiki
• Virtualbox >= 4.3.10 - Install
• Vagrant >= 1.5.4 - Install • Docs
• vagrant-bindfs >= 0.3.1 - Install • Docs (Windows users may skip this)
• vagrant-hostsupdater - Install • Docs

Installation

1. Download/fork/clone this repo to your local machine.
2. Run ansible-galaxy install -r requirements.yml inside your Trellis directory to install external Ansible roles/packages.
3. Download/fork/clone Bedrock or have an existing Bedrock-based site ready.

You should now have the following directories at the same level somewhere:

example.com/    - Primary folder for the project
├── ansible/    - Your version of this repo (renamed to just `ansible`)
└── site/       - A Bedrock-based site (suggested to name this the generic `site` since your project name is already at the top level)

• You do not need a configured .env file. Trellis will automatically create and configure one.
• The full paths to these directories must not contain spaces or else Ansible will fail.
• See a complete working example in the roots-example-project.com repo.

Development setup

1. Configure your WordPress sites in group_vars/development
2. Run vagrant up

Remote server setup (staging/production)

For remote servers you'll need to have a base Ubuntu 14.04 server already created.

1. Configure your WordPress sites in group_vars/<environment>. Also see the Passwords wiki.
2. Add your server IP/hostnames to hosts/<environment>.
3. Specify public SSH keys for users in group_vars/all. See the SSH Keys wiki.
4. Consider setting sshd_permit_root_login: "no" in group_vars/all. See the Security wiki.
5. Run ansible-playbook -i hosts/<environment> server.yml

Deploying to remote servers

1. Add the repo (Git url) of your Bedrock WordPress project in the corresponding group_vars/<environment> file.
2. Set the branch you want to deploy.
3. Run ./deploy.sh <environment> <site name>
4. To rollback a deploy, run ansible-playbook -i hosts/<environment> rollback.yml --extra-vars="site=<site name>"

Configuration

HHVM

HHVM can be used instead of PHP 5.6 by setting hhvm: true in group_vars/all.

WordPress Sites

Before using Trellis, you must configure your WordPress sites. The group_vars directory contains one configuration file per environment (development, staging, and production in YAML format). For example: configure the sites on your Vagrant development VM by editing group_vars/development.

wordpress_sites is the top level dictionary used to define the WordPress sites, databases, Nginx vhosts, etc that will be created. Each site's variables are nested under a site "key" (e.g., example.com). This key is just a descriptive name and serves as the default value for some variables. See our example project for a complete working example.

• site_hosts - array of hosts that Nginx will listen on (required, include main domain at least)
• local_path - path targeting Bedrock-based site directory (required for development)
• repo - URL of the Git repo of your Bedrock project (required, used when deploying)
• branch - the branch name, tag name, or commit SHA1 you want to deploy (default: master)
• ssl - enable SSL and set paths
  • enabled - true or false (required, set to false. Set to true without the key and cert options to generate a self-signed certificate )
  • key - local relative path to private key
  • cert - local relative path to certificate
• site_install - whether to install WordPress or not (development only, required)
• site_title - WP site title (development only, default: project name)
• db_create - whether to auto create a database or not (default: true)
• db_import - Path to local sql dump file which will be imported (optional)
• system_cron - Disable WP cron and use system's (default: true)
• admin_user - WP admin user name (development only, required)
• admin_email - WP admin email address (development only, required)
• admin_password - WP admin user password (development only, required)
• multisite - hash of multisite options. See the Multisite wiki.
  • enabled - Multisite enabled flag (required, set to false)
  • subdomains - subdomains option
  • base_path - base path/current site path
• cache - hash of cache options
  • enabled - Cache enabled flag (required, set to false)
  • duration - Duration of the cache (default: 30s)
• env - environment variables
  • wp_home - WP_HOME constant (required)
  • wp_siteurl - WP_SITEURL constant (required)
  • wp_env - environment (required, matches group name: development, staging, production)
  • db_name - database name (required)
  • db_user - database username (required)
  • db_password - database password (required)
  • db_host - database hostname (default: localhost)
  • domain_current_site (required if multisite.enabled is true)

Mail

Outgoing mail is handled by sSMTP. For the development environment, emails are sent to MailHog, where you can inspect them. To access MailHog interface, go to http://yourdevelopmentdomain.dev:8025. For staging and production, configure credentials in group_vars/all. See the Mail wiki.

SSL

Full SSL support is available for your WordPress sites. Trellis will also auto-generate self-signed certificates for development purposes. Our HTTPS implementation has all the best practices for performance and security. (Note: default configuration is HTTPS only.) See the SSL wiki.

Caching

You can enable FastCGI caching on a per site basis. The cache is a low duration, "micro-cache" type setup. See the FastCGI micro-caching wiki for configuration options.