Deploying a Roots Sage theme to WPEngine, with a bonus debugging tool
I love the Sage starter theme and I love WPEngine, but WPEngine doesn't seem to love Sage v9+. Once you've got your Sage theme running in WPE, chances are it will run pretty great, but it takes a little effort to pull off your first deploy.
Here's how I approach my Sage + WPE workflow:
- Build on a Gitlab runner. Sage needs to be installed in a complete, functioning WordPress install before the Blade templates can be compiled. Gitlab runners are an easy way to get access to a MySQL server so it's possible to spin up a functional WP install.
- Vendor files are required. You can't run a theme, even after it's compiled, without the vendor files generated by Composer. Make sure these files are included in your built push to WPE.
- Move the Blade template dir. WPE doesn't allow php files outside the theme or plugin dir. I place my compiled templates in a
mu-plugindir. - Always Use Production "Sites". WPE offers multiple site installs (Dev, Stage, Prod) inside a top-level site container. Confusingly, they also allow you to have both a regular production environment and a "legacy staging" environment for all of those site sites... for a total of six environments. This is both overkill and misleading, because the legacy staging server config is not the same as a production config. Always use production sites to avoid disappointment when you deploy the live site.
- Test Your Pipeline Locally. Running the entire Gitlab script as you test your pipeline is tedious. I created a Docker config along with basic build deploy / scripts to make it possible to step through the deployment process interactively.
- Ask WPE support to set a caching exemption WPE has aggressive object-caching that can interfere with your Blade templates. Ask their support team to exempt your compiled templates from their internal caching.
Depending on the exact version of Sage that you're running, and the Composer packages that you're using, it might be necessary to tweak these files, but here's what I use in my live Gitlab runner:
Good luck! If all goes well, here's what you'll see:
Lead photo: Clever Sparkle