Trellis

Ansible playbooks for setting up a LEMP stack for WordPress.

• Local development environment with Vagrant
• High-performance production servers
• Zero-downtime deploys for your Bedrock-based WordPress sites
• trellis-cli for easier management

What's included

Trellis will configure a server with the following and more:

• Ubuntu 18.04 Bionic LTS
• Nginx (with optional FastCGI micro-caching)
• PHP 7.4
• MariaDB (a drop-in MySQL replacement)
• SSL support (scores an A+ on the Qualys SSL Labs Test)
• Let's Encrypt for free SSL certificates
• HTTP/2 support (requires SSL)
• Composer
• WP-CLI
• sSMTP (mail delivery)
• MailHog
• Memcached
• Fail2ban and ferm

Documentation

Full documentation is available at https://roots.io/trellis/docs/.

Requirements

Make sure all dependencies have been installed before moving on:

• Virtualbox >= 4.3.10
• Vagrant >= 2.1.0
• Recommended: trellis-cli

Windows user? Read the Windows getting started docs for slightly different installation instructions.

Installation

Using trellis-cli

Create a new project:

$ trellis new example.com

Manual

The recommended directory structure for a Trellis project looks like:

example.com/      # → Root folder for the project
├── trellis/      # → Your clone of this repository
└── site/         # → A Bedrock-based WordPress site
    └── web/
        ├── app/  # → WordPress content directory (themes, plugins, etc.)
        └── wp/   # → WordPress core (don't touch!)

See a complete working example in the roots-example-project.com repo.

1. Create a new project directory:

$ mkdir example.com && cd example.com

2. Install Trellis:

$ git clone --depth=1 git@github.com:roots/trellis.git && rm -rf trellis/.git

3. Install Bedrock into the site directory:

$ composer create-project roots/bedrock site

Local development setup

Using trellis-cli

1. Review the automatically created site in group_vars/development/wordpress_sites.yml
2. Customize settings if necessary

Start the Vagrant virtual machine:

$ trellis up

Manual

1. Configure your WordPress sites in group_vars/development/wordpress_sites.yml and in group_vars/development/vault.yml
2. Ensure you're in the trellis directory: cd trellis
3. Run vagrant up

Read the local development docs for more information.

Remote server setup (staging/production)

A base Ubuntu 18.04 (Bionic) server is required for setting up remote servers.

1. Configure your WordPress sites in group_vars/<environment>/wordpress_sites.yml and in group_vars/<environment>/vault.yml (see the Vault docs for how to encrypt files containing passwords)
2. Add your server IP/hostnames to hosts/<environment>
3. Specify public SSH keys for users in group_vars/all/users.yml (see the SSH Keys docs)

Using trellis-cli

Initialize Trellis (Virtualenv) environment:

$ trellis init

Provision the server:

$ trellis provision production

Or take advantage of its Digital Ocean support to create a Droplet and provision it in a single command:

$ trellis droplet create production

Manual

For remote servers, installing Ansible locally is an additional requirement. See the docs for more information.

Provision the server:

$ ansible-playbook server.yml -e env=<environment>

Read the remote server docs for more information.

Deploying to remote servers

1. Add the repo (Git URL) of your Bedrock WordPress project in the corresponding group_vars/<environment>/wordpress_sites.yml file
2. Set the branch you want to deploy (defaults to master)

Using trellis-cli

Deploy a site:

$ trellis deploy <environment> <site>

Rollback a deploy:

$ trellis rollback <environment> <site>

Manual

Deploy a site:

$ ./bin/deploy.sh <environment> <site>

Rollback a deploy:

$ ansible-playbook rollback.yml -e "site=<site> env=<environment>"

Read the deploys docs for more information.

Contributing

Contributions are welcome from everyone. We have contributing guidelines to help you get started.

Trellis sponsors

Help support our open-source development efforts by becoming a patron.

Community

Keep track of development and community news.

• Participate on the Roots Discourse
• Follow @rootswp on Twitter
• Read and subscribe to the Roots Blog
• Subscribe to the Roots Newsletter
• Listen to the Roots Radio podcast