Skip to content

Latest commit

 

History

History
137 lines (101 loc) · 7.74 KB

README.md

File metadata and controls

137 lines (101 loc) · 7.74 KB

Trellis

Build Status

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

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. Add SSH keys to users in group_vars/all. See the SSH Keys wiki.
  4. 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)
    • 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. Configure credentials in group_vars/all. See the Mail wiki.

SSL

Full SSL support is available for your WordPress sites. 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.

Security

The secure-root.yml playbook improves SSH security on your remote servers. See the Security wiki.