roots/trellis: Ansible playbooks for a WordPress LEMP stack

The problem Trellis solves: server state as versioned playbooks

Most WordPress hosting advice ends with a control panel and a set of clicks. Trellis takes the opposite position. The repository is a collection of Ansible playbooks, and the server configuration lives in files you commit: group_vars/, hosts/, roles/, server.yml, deploy.yml, dev.yml. The README describes the project as "Ansible-powered LEMP stack for WordPress" and lists what that stack gives you: a local development environment with Lima VMs, production servers, zero-downtime deploys for Bedrock-based sites, and trellis-cli for management. The audience is narrow on purpose. You need a WordPress site built on Bedrock, which restructures the install so that the web root holds only public files. You need SSH access to a server you control. And you need to be comfortable treating provisioning as code, because that is the only interface Trellis offers. If your site is a stock WordPress install with plugins uploaded through the admin, Trellis is not a drop-in replacement for your host. It is a different way of owning the machine.

How the Ansible playbooks, roles and hosts files fit together

The repository layout tells most of the story. server.yml provisions a remote machine; deploy.yml ships a release; rollback.yml reverses one; dev.yml builds the local environment; xdebug-tunnel.yml opens a debugging tunnel. Shared variables sit in group_vars/, inventory in hosts/, and the actual work in roles/. The top level also carries ansible.cfg, galaxy.yml, requirements.txt and a VERSION file, which is the shape of an Ansible project rather than a WordPress plugin. requirements.txt pins the toolchain to a single line, ansible>=2.10.0, so the playbooks run against a modern Ansible rather than a vendored copy. The data flow is conventional Ansible: you run a playbook against a host from the inventory, roles apply tasks in order, and the resulting state is the server. Deploys are separate from provisioning, which is why zero-downtime is possible at all: the release lands in a new directory and the symlink moves. The README does not document the internal release directory layout, so treat the playbook files as the source of truth rather than any summary. One detail worth noting for anyone reading the code: the primary language listed for the repository is Jinja, which is the templating layer Ansible uses. That is a fair description of where the interesting logic lives.

Installing Trellis and running a first deploy

The README does not contain install steps. It says, plainly, "See the Trellis installation documentation" and links to https://roots.io/trellis/docs/installation/. That page is where the real procedure lives, and it is the only place the project documents it. What the repository does give you is the dependency constraint. The requirements.txt file contains one requirement, which tells you the minimum Ansible version the playbooks expect.

ansible>=2.10.0

Beyond that constraint, the repository names its entry points rather than documenting how to invoke them. server.yml provisions a remote machine, deploy.yml ships a release, rollback.yml reverses one, and dev.yml builds the local environment. The README does not show the commands that run them, so the exact invocation is something to take from the installation documentation at roots.io/trellis/docs/installation/ rather than from this page. What you should expect from a provisioning or deploy run is Ansible walking through the roles in order and reporting changed or ok for each task. For local work, dev.yml is the entry point, and the README states the local environment uses Lima VMs. The project also points to trellis-cli as a wrapper for easier management, which is the route most people take once they are past the first run.

Where Trellis is the wrong tool

Trellis assumes Bedrock. That is not a preference, it is the architecture: zero-downtime deploys depend on the Bedrock directory structure, where the web root is a subdirectory and dependencies are managed outside it. Point Trellis at a conventional WordPress install and the deploy playbook has nothing coherent to ship. The same applies to shared hosting. Trellis expects SSH and sudo on a machine you provision, which rules out the cheap end of the hosting market entirely. There is a second constraint that is easy to miss: the README documents no rollback procedure beyond the existence of rollback.yml. The file is there, but what it restores and how far back it can go is not described in the README, and that is exactly the kind of thing you want to know before you need it. Treat rollback as something to test deliberately on a staging environment rather than something to discover during an incident. Finally, the maintenance model is worth stating plainly. The last push to the repository was on 2026-09-18, and the most recent release listed is v1.31.1 from 2026-04-15. That is a project that ships, but it ships on its own schedule, and the changelog between releases is where breaking changes to playbook variables would appear.

Trellis compared with a managed WordPress host

The honest alternative for most people evaluating Trellis is a managed WordPress host, and the difference is not speed or features. It is who holds the server definition. With a managed host, the platform owns the LEMP stack, the PHP version, the TLS certificates and the deploy mechanism. You get a dashboard and a support channel, and you give up the ability to change anything below the application. Trellis inverts that: you own the stack, you own the upgrades, and the playbooks in this repository are the interface. The trade shows up in two places. First, PHP version bumps, which a managed host rolls out for you, become a change to a variable in group_vars/ that you test and deploy. Second, the failure mode changes. A managed host failing is a support ticket. A Trellis deploy failing is a playbook run you have to read. Teams that already run Ansible for other services will find the second model cheaper. Teams without that background will find the first one cheaper, and that is a legitimate answer, not a cop-out.

Licence and the cost of staying current

Trellis is MIT licensed, and LICENSE.md sits at the repository root. That is permissive: you can use it commercially, modify the playbooks, and keep your changes private. The practical implication for a team is that forking is a supported option, and some teams will fork to pin server configuration they do not want upstream changing underneath them. The cost of that choice is that you then own the merge. Upgrades arrive as releases, the most recent listed being v1.31.1 on 2026-04-15, and applying one means reviewing the diff against your fork or your overrides in group_vars/ before running the playbooks again. The repository ships a variable-check.yml playbook, which suggests the project takes variable drift seriously enough to provide a check for it. Ansible itself is the other ongoing cost: requirements.txt asks for ansible>=2.10.0 with no upper bound, so a major Ansible release can change behaviour under playbooks that were not written against it. Pinning Ansible in your own environment is the ordinary mitigation, and it is worth doing before an unattended upgrade surprises you mid-deploy. Nothing here is legal advice; read LICENSE.md for the terms that actually apply.

Editorial conclusion

Adopt Trellis if your WordPress site is Bedrock-based and your team is willing to keep server state in Ansible playbooks rather than a hosting control panel. Do not adopt it if you expect a single WordPress install with a wp-config.php in the web root, or if nobody on the team wants to read a playbook before a deploy. Before committing, verify that your host allows the SSH user and sudo access Trellis assumes, and read the installation documentation at roots.io/trellis/docs/installation/ end to end, since the README itself only points there.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. roots/trellis on GitHub