How to Set Up Your Mac with WordPress to Develop a News Site Like We Do

This post is inspired by the wonderfully written How to Set Up Your Mac to Develop News Applications Like We Do by the News Apps team at NPR.

At Rest of World, every developer (and anyone on the Product team if they choose to) runs a local copy of Rest of World on their Apple laptop for day-to-day development.

This covers how to get up and running with a basic setup in a relatively short amount of time.

Our internal documents also cover how to include real content from our live site, sample posts for reference and feature-testing a subset of actual WordPress users, and media assets. We don’t cover that here since it’s very specific to our use.

After these steps, a person should be able to access the local website at:

https://restofworld.test

Since this is us, you will see a lot of RoW-specific placeholders. Adjust as necessary.

Chapter 1: Prerequisites

Are you an administrator?

You will run into issues if you are not an administrator of your computer. We’re Mac users, so adjust as necessary for your operating system of choice.

Start with System Preferences > Users & Groups

If you don’t see “Admin” next to your account then you’ll need to resolve that before going any further.

git and Xcode

You’ll need to install git if you don’t have it already. It will be part of Xcode though there are alternatives to that.

• git (if you decide not to rely on Xcode)
• Xcode

Local

Local is an application that addresses much of the heavy lifting of creating a local WordPress site. Before it came along we had a much more difficult setup using VirtualBox and virtual images.

You should download the latest version of Local from here:

Configure git

1. On macOS, open Terminal app (though we prefer and use iTerm)
2. Run git and follow prompts
3. Configure your Github account on your machine
4. Set your username and password

git config --global user.name "Kathleen Booth"
git config --global user.email kbooth@assembly.tld

Our policy at Rest of World is that if 2FA is offered as an option on any service we use, we are required to enable it.

If you have 2FA set up for Github, follow the steps here to generate a new SSH key, add it to the ssh-agent, and add it to your Github account.

Chapter 2: Setup

Install Local

If your laptop uses Apple Silicon, Rosetta 2 is required for Local’s Apple Silicon build due to the nginx and MySQL Lighting Services compiled on the Intel architecture.

This is a tutorial for installing it is here.

Setup your site

The Local app will prompt you through the setup process. The only step to do ahead of time is to create the directory you’d like it to use.

For us we go with:

mkdir -p ~/Development/localwp

While the setup process does push you to create an account with Local, you do not need one to install and run WordPress locally.

• Click the Add Local Site (+) button
  • Site Name: ‘Rest of World’
  • Advanced Options
    • Set domain to restofworld.test
    • Designate a folder for all this to live in. For this guide we will assume that the folder is:
      ~/Development/localwp

There should now be a new directory called localwp. This is where all the WordPress files live:

wp-local > app > public > wp-public

This contains WordPress themes and plugins—and later will be where we add our projects services folders.

Whether you select Preferred or Custom, as of writing, these are the current settings:

PHP: Version 8.1.9
Web Server: nginx
MySQL: 8.0.16

Generally, go with the latest versions unless you have reasons.

• Click Continue
• Add a username and password
• Multisite: No
• Click Add site
• In the Dashboard, toggle One-click Admin to On

There are other steps that we don’t cover here as they may vary based on your needs. 

For example; we manually setup Menus and other fields in WordPress to match our Production site. We also have a limited set of posts, tags, authors, and other custom posts – along with associated images in the Media Library that we import. 

Chapter 3: Version control

We use Github to manage our code, code review, and deployments. We recommend separate repositories for the themes and plugins folders in WordPress.

Rest of World uses three separate repositories:

• themes for all core site code
• projects for bespoke code for individual projects, and
• plugins for WordPress plugins we built or forked

Themes

Our custom theme, orbis, encapsulates the design, layout, and workflow of the core site. It includes customizations that should probably have been custom plugins. No one is perfect.

Projects

Our code for article-specific and project-based development is separate from themes. Whenever we customize an article and add unique elements, or over-ride the standard visual treatments, that code is goes here.

Plugins

We do not commit plugins to the plugins directory unless we built them in-house. It is always best to enable Auto-Updates within WordPress, and you do not want deployments to stomp over the most recent versions.

Troubleshooting

When working with a repository for the first time you might get this warning regarding the pull.rebase configuration. The probable solution is this:

git config pull.rebase false  # merge (default strategy)

Further reading:

Chapter 4: Final configuration

SSL Certificate on macOS

Local supports a one-click solution for trusting a site’s SSL certificate but this has never gone as planned for us. There is a documented work-around here.

Conclusion

You should be good to go.

At this point we’d be adding our standard plugins like ACF Pro, Query Monitor (development environment only), and Co-Authors Plus. You do you.