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.
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
- On macOS, open Terminal app (though we prefer and use iTerm)
- Run
git
and follow prompts - Configure your Github account on your machine
- 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
- Set domain to
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.