WordPress local development with Trellis

In a previously posted article, WPTipsters introduced Trellis, the modern WordPress development stack. Now, it is time to learn how to setup a WordPress development environment with Trellis that uses Vagrant for local development. If you are new to the subject, view the previous article about Trellis.

Get the repository

Since the Roots team moves very fast in development and new versions are being published very often, I have decided to store a version that I like to use for WordPress projects and feel comfortable with. I would recommend you to do so as well. While constant learning is important, it is also important to get properly familiar with something before going forward.

I’ve shared the code in GitHub. Download the code from there, or just go ahead and clone the repository.

git clone https://github.com/MikaKujapelto/wpTemplate wpstack

Overview of the repository

The repository is basically divided into two. Under the site folder, you will have all the info concerning your WordPress site. Under this folder you will will define the plugins, themes etc. This repository uses the Sage Starter Theme, version 8.4.1. On the other folder, Trellis, you will have the information about the environments and deploys.

Themes & Plugins

If you wish to use another theme, go ahead and delete the sage theme folder (/site/web/app/themes/sage/). Then add the theme you want to use in the same path (/site/web/app/themes/your-theme/). If you change the theme or theme name, change the default theme from /site/config/application.php as currently Sage is set to default.

/* Sage as the default theme */
define('WP_DEFAULT_THEME', 'sage');

Plugins are installed by Composer, which is PHP dependency management tool. Since the composer will be installed while building the local environment, you don’t have to install it manually on your computer. You can define the plugins to use, in the composer.json file (/site/composer.json). Add the plugins you want to use, from WordPress Packagist.

Configuring the local environment

Before we can start the local environment, you need to configure the environment. Rename the domain for the one that you are using. Quick way to get rid of the example.com, the default domain in the repo, is to use the replace tool.

Install replace:

npm install replace -g

Navigate to /trellis and replace the example.com domain with your domain.

replace 'example.com' 'your-domain.com'

Then open /trellis/group_vars/development/wordpress_sites.yml and change the site_hosts. For example for WPTipster, the file looks as following:

      - canonical: wptipster.dev
          - www.wptipster.dev
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: admin@example.dev
      enabled: false
      enabled: false
      provider: self-signed
      enabled: false

Install requirements

Now we have configured the local environment, but before firing up the development server, we need to install the following requirements.

  • Ansible >= 2.2 – Can be installed with Homebrew (brew install ansible)
  • Virtualbox >= 4.3.10 – Download and run installer
  • Vagrant >= 1.8.5 – Download and run installer
  • vagrant-bindfs >= 0.3.1 – Install with:

    vagrant plugin install vagrant-bindfs
  • vagrant-hostmanager – Install with:

    vagrant plugin install vagrant-hostmanager

Start the server

To start the server, navigate to the trellis folder and run:

vagrant up

This may take a while, but after the setup is complete, you should be seeing your WordPress site in the address that you have defined in the wordpress_sites.yml file.