Working with WordPress Locally with the Roots Stack

Okay, so it’s been a while since last time I wrote about Roots (shoutout to Rob for pointing it out). The last time I wrote about the Roots Stack, things were more or less the same. But I felt compelled to write this guide ever since Sage got a version bump.

Secondly, no one enjoys spending precious hours configuring their local setup using a MAMP GUI or fucking up your machine’s hosts file or deliberating on how to fix the dreaded error establishing a database connection. What I love most about Roots is the priority on convention over configuration. 

It’s literally a playbook taken from Rails. The net gain of this philosophy is twofold:

1. Lowered barrier to entry for beginners
2. Productivity bonus, spend more time hacking and less time crying

The Roots framework has huge benefits for beginners, and even bigger returns for WordPress veterans. Mainly because you’ll no longer have to FTP your deployments like a goddamn barbarian. But I’ll go into more detail on remote server setup in my next post.

Before I get side-tracked, let’s just dive right in shall we?

Requirements

Let’s talk about requirements and assumptions. I’m assuming you’re using Sublime Text 3 (all other versions make sure you have this enabled) and you understand how to use your terminal. Follow the links below and install the following software.

• OS X or MacOS (Windows users read here)
• Latest LTS Node.js >= 6.11.4
• Composer
• Homebrew
• Bower
• Virtualbox >= 4.3.10
• Vagrant >= 1.8.5

Installation

Below is what we want our project too roughly look like:

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

Create a Sites folder if you haven’t already. I typically put all of my web projects in a Sites folder in my home directory on my Mac. To get started, we’re going to make a directory called example.com — you can name yours whatever project name you’d like:

cd ~/Sites && mkdir example.com && cd example.com

You should be inside the example.com directory at this point. Next we’re going to clone Trellis:

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

Then we’re going to clone Bedrock (which contains WP Core and our web app, etc.):

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

At this point, our example.com directory should look like this:

example.com/      # → Root folder for the project
├── trellis/      # → You'ver clone of Trellis
└── site/         # → A Bedrock-based WordPress site (cloned as well)

You’ve’re doing great!

Trellis vars

Now let’s get into something a bit more challenging. We’re going into the Trellis directory and need to edit some variables to bring this local WordPress installation to life. I’m assuming you have Sublime Text 3 installed and you’re still in the root of example.com

Edit the wordpress_sites.yml file first:

subl trellis/group_vars/development/wordpress_sites.yml

Then just make sure it looks like this. Replace example.com with the name of the project you have chosen. This is pretty important at this point, as we start getting into the nitty-gritty.

# Make sure your file looks like this
wordpress_sites:
  example.com:
    site_hosts:
      - canonical: example.test
        redirects:
          - www.example.test
    local_path: ../site # path targeting local Bedrock site directory (relative to Ansible root)
    admin_email: admin@example.test
    multisite:
      enabled: false
    ssl:
      enabled: false
      provider: self-signed
    cache:
      enabled: false

Now go ahead and edit the vault.yml file as well:

subl trellis/group_vars/development/vault.yml

# Make sure the site name (`example.com`) must match up with the site name
# in the file we previously edited: `group_vars/development/wordpress_sites.yml`
# By default Trellis will provision a user `admin` too, below you can set a different
# password if you'd like
vault_wordpress_sites:
  example.com:
    admin_password: admin
    env:
      db_password: example_dbpassword

Don’t worry about the other .yml files in the development folder for now.

Vagrant

Vagrant is our savior. It sits between us and the VirtualBox, and does most of the talking. To get our machine running our new local setup we configured (in the wordpress_sites.yml and vault.yml files), we have to go down into our trellis directory and get vagrant running:

cd trellis && vagrant up

By now you should see this a few commands trickling in. At some point vagrant will ask for your sudo password because it needs root permissions.

Enter your password and vagrant will begin installing, provisioning and start running tasks your virtual-machine.

At this point, take a break and chill. The total installation/provision time varies from machine to machine, but it takes around 10-15 minutes on a mid-2015 13″ MacBook Pro. Once the provisioner is done (provided that no errors stopped the installation), you can open your browser and navigate to example.test and you should see this:

Getting started with theme development with Sage

Now that we have a local development environment setup and running, we can move onto creating our first theme! The Roots team put together an awesome starter-theme to speed up development.

Remember our project structure? We’re going to cd our way into the themes directory:

example.com/      # → Root folder for the project
├── trellis/      # → Trellis
└── site/         # → A Bedrock-based WordPress site
    └── web/
        ├── app/  # → WordPress content directory (themes, plugins, etc.)
        |   ├── mu-plugins/  # Must-use plugins live here
        |   ├── plugins/     # Plugins live here, managed by composer.json in the `site` folder
        |   ├── themes/      # We're going to create our theme HERE.
        |   └── uploads/     # WordPress will put uploads here (I wouldn't mess with these)
        |
        └── wp/   # → WordPress core (don't touch! Like ever!)

Once we’re in the themes directory, we’re going to run a composer command:

composer create-project roots/sage example-theme 8.5.3

Basically, the previous command says:

1. create a composer project with the the roots/sage package
2. name the theme, “example-theme”
3. choose the 8.5.3 version of the roots/sage package

As of October 17, 2017 the LTS Sage version is at 8.5.3 which is why I chose that version. You should see composer downloading the packages (be patient, sometimes composer can be slow)

Sage requires Node.js to function. Make sure you are up-to-date.

npm install -g npm@latest

We’re going to use Gulp to build assets (styles, scripts, etc) and Bower will handle any front-end packages such as Bootstrap or Flickity. To get started, cd inside our new theme example-theme. We’re going to install Gulp and Bower globally (if you haven’t already)

npm install -g gulp bower

Now, were’ going to install all the dependencies listed in the package.json

npm install && bower install

Next, let’s open our manifest.json in Sublime Text and configure BrowserSync to proxy our dev URL

subl assets/manifest.json

Make sure the devURL reflects the canonical hostname we wrote in wordpress_sites.yml earlier since our vagrant machine will be listening for traffic at that URL.

...
  "config": {
    "devUrl": "http://example.test"
  }
...

At this point, we can go to example.test/wp-admin, and login. From the dashboard, choose Appearance > Themes. Pick your Sage Theme and Visit Site. Everything will look broken now, as no styles exist 🙁

But don’t fret! Next, we go back to the terminal (make sure you’re still in the new theme directory), and run gulp watch. A new tab should open on your browser. That’s BrowserSync loading style changes in real-time (no more ⌘R in Chrome). Save any of the SCSS files in the assets/styles directory and your webpage should reload with the changes. Also watch your terminal 👀

Gulp literally watches all PHP, SCSS and JS files changes. And BrowserSync will reload your browser window. Pretty nifty. Assuming you didn’t get any errors, your homepage should load with basic styles thanks to Normalizer and Bootstrap.

From here on out, the world is your oyster!

Sage doesn’t give you everything you need for WordPress development but it’s speedy, it’s git-friendly, and it’s modern. I’m not kidding when I say this… the Roots Stack is literally my favorite way to interface with WordPress. Any other way just feels primitive and old.

It gets even better with deployments and remote provisioning which I will cover in my next post. 

Further Reading:

• Dav Kiss’ Develop WordPress Sites like a Goddamn Champion
• Roots Docs

Next: Remote Server Setup with Trellis