Skip to Content
Wordpress / PHPSpin Up

Project Spin Up Instructions

The purpose of this document is to provide a guide of spinning up a new WordPress project at Integrity. These are defaults that we use for the majority of WP projects. We’ll continue and encourage team members to review, add, and edit this doc as our process grows and changes over time.

Tools Needed:

Integrity Starter Theme - Option 1 for Starter Theme

We have an in-house starter theme for WordPress projects that can be accessed here . Underscores starter theme is used but modified for easier use.

  1. Go to GitHub and create a new repository under the integritystl organization.
  2. Click on the “Use this template” button and pick the starter theme mentioned above. Repo name will be based on project.
  3. Pull this new repo locally to your own environment using your choice of Git client or terminal.
  4. In the theme directory, run “npm install” to download node modules.

New Repository with new Underscores - Option 2 for Starter Theme

  1. Create a Private Repo under the Integrity Organization. Repo name is based on project
  2. Pull this new repo locally to your own environment
  3. If you don’t have it already, go to Integrity WP Starter Site  and pull it locally
  4. Create a ReadMe.md file in your new project repo and copy/paste the content from ReadMe.md from WP Starter Site into your new file. Edit the file with relevant information
  5. Install latest WP Core. By default we host on WP Engine. We don’t track WP core files outside of wp-content because WP Engine updates those for us
  6. If this site is hosted elsewhere, make sure WP core files aren’t in gitignore.
  7. Spin up a fresh Underscores starter theme  with the project’s name
  8. Expand advanced options, and be sure to check “_sassify!” to add Sass.
  9. Screenshot the design and save it as screenshot.png in the theme
  10. Add a theme_infrastructure folder at the theme directory. This will house our ACF PHP data
  11. Push your previous changes (Readme and theme) to your repo
  12. Create a develop branch off of master in Github
  13. In the Settings, make the develop branch the Default Branch
  14. Under Collaborators & Teams, give everyone Write access. To prevent having blockers on your Project, add your Dev Support buddy to the Repo as an Admin.

Add in Base Sass files

  1. Restructure the Sass directory. We do this because Underscores adds a lot of extra Sass files that we don’t always need.
  2. Create a new directory in ‘sass’ called ‘underscores’
  3. The items we wanna grab are:
    • Mixins folder
    • Modules folder (specifically, accessibility.scss and alignments)
    • Media folder (WP galleries, captions, etc)
    • For the Captions functionality - go to ‘variables-site/columns.scss’ and just paste that mofo into the galleries.scss file. It’s the only place we’ll be using it.
  4. In the root sass directory:
  5. Create style.scss. This is the primary Sass file that imports our others
  6. Copy over the Theme info from the style.css
  7. Pull out the normalize styles and create a new _normalize.scss file in the root so we can import it instead: @import “normalize”;
  8. Import the Underscores items we’re using
  9. Take out any instances of Underscores variables and replace with ones from ‘base’ or the values from Underscores’.
  10. Import the Bitters and its Bourbon dependency by @import “bourbon”;
  11. Note: We include ‘bourbon’ in as an NPM package, so you’ll be doing this step after you’ve finished the Setup Tasks/Tooling section. @import “base/base”
  12. Create a new directory named after your theme and import files from it. You’ll gradually add files to this list as the site grows.

Note: Bitters  has been in used past projects but doesn’t seem to be used in our latest projects. Will be keeping a mention of this tool in case we need to go back on older projects.

SetUp Tasks/Tooling

Note we are currently migrating from Gulp to Webpack. Please check with the team on the latest process until this is updated.

We typically use Gulp and NPM to do the following:

  • Typical Gulp 4 Dependencies
    • Autoprefixer (will have a few vulnerabilities but that is more gulp 4 being picky and looked into already, safe to update to latest)
    • Uglify
    • Rename
    • Concat
    • Notify
    • BrowserSync
    • CleanCSS
    • Postcss and Postcss Assets
    • Sourcemaps

These are the default tasks, but depending on the site there could be more:

  1. Including/watching React and compiling its files into a final JS file to use on the site
  2. Compile and minify JS files that have a specific purpose on certain templates

During the course of the project, you might add other tasks as needed. We’ve also used Webpack before. The learning curve on this is different from Gulp, so if your project doesn’t have to use it, you don’t have to.

Your Gulpfile lives in the root of the project, along with the node_modules generated from your NPM packages.

  1. Make a file called package.json in the root. We have a set of tasks we’re usually using, so this file can be pulled from the WP Starter Pack repo
  2. Make a file called gulpfile.js in the root
  3. Add your tasks to gulpfile.js
  4. In the scripts part of package.json, point to gulpfile.js for your build
  5. Open Terminal and in the root of the project, run the command npm install to install all of those dependencies from package.json
  6. Run your default ‘gulp’ task. Typically, it’ll just be gulp in the root of the Project. If you add / edit a gulp task while gulp is running, you’ll have to stop and re-run for the new tasks to start working.

IMPORTANT! Once you’ve added some Gulp tasks, make sure to include any commands to run them in the project’s ReadMe file.

WP Engine Hosting Setup

Set Up a WP Engine install. Login with the Integrity WP Engine account .

  1. Create install
  2. Give it a name that’s not taken
  3. Check “Transferable Install”
  4. Once site is initiated, add a staging environment. This setup is identical to what the production site is. Try to use a URL with ‘stage’ or ‘dev’ in it if you can. There are strict naming rules so it could be a challenge
  5. Once install is set up, update password via PHPMyAdmin
  6. From WP Engine Dashboard, go to “phpMyadmin” in the sidebar
  7. Click the DB name from the site (should be wp_install name)
  8. Go to wp_users table
  9. Find the install name user and click “Edit”
  10. Update the password under user_pass and set the dropdown function to MD5
  11. Hit save
  12. Test logging in. Once it works, add credentials to Team Password
  13. Copy the ‘Production’ version of the new install down to a stage version

Deployment Setup

At this point, it’s time to do Git Push for WP Engine!

Example Deployment File (.github/workflows/develop.yml):

name: Deploy to WP Engine
on:
  push:
    branches:
      - develop
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      ACF_USERNAME: ${{ secrets.ACF_LICENSE_KEY }}
      WPMUDEV_USERNAME: ${{ secrets.WPMU_DEV_API_KEY }}
      WPMIGRATE_USERNAME: ${{ secrets.DELICIOUS_BRAINS_USERNAME }}
      WPMIGRATE_PASSWORD: ${{ secrets.DELICIOUS_BRAINS_PASSWORD }}
      COMPOSER_PAT: ${{ secrets.COMPOSER_PAT }}
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Set Composer authentication
        run: |
          composer config --global --auth http-basic.connect.advancedcustomfields.com $ACF_USERNAME https://operationshower.org
          composer config --global --auth http-basic.wpmudev.com $WPMUDEV_USERNAME ""
          composer config --global --auth http-basic.composer.deliciousbrains.com $WPMIGRATE_USERNAME $WPMIGRATE_PASSWORD
          composer config --global --auth github-oauth.github.com $COMPOSER_PAT
 
      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist --optimize-autoloader
 
      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "20"
 
      - name: Install Node.js dependencies
        run: npm ci
 
      - name: Build assets
        run: npm run build
 
      - name: GitHub Action Deploy to WP Engine
        uses: wpengine/github-action-wpe-site-deploy@v3
        with:
          WPE_SSHG_KEY_PRIVATE: ${{ secrets.WPE_SSHG_KEY_PRIVATE }}
          WPE_ENV: opshowerstage
          SRC_PATH: wp-content/
          REMOTE_PATH: wp-content/
          FLAGS: -azvr --inplace --delete --exclude='mu-plugins/' --exclude='uploads/' --exclude='languages/' --exclude='drop-ins/' --exclude='*.sql' --exclude='advanced-cache.php' --exclude='.*' --exclude='smush-webp/'

Test Deployment

THIS IS WHERE YOU CAN FINALLY TEST A DEPLOYMENT, HUZZAH!

  1. In your local repo, Feature branch from Develop.
    • Make some sort of change. It could be visible or only code based. Just so long as you can find it once it’s deployed (and it’s a trackable file in git)
  2. Push your feature branch to the repository
  3. Make a Pull Request from your Feature Branch into Develop
  4. Once your PR is merged in, flip to Github to see if a thing happened
    • If everything works, the deplyment action will turn green with a “SUCCEEDED” message.
  5. Visit the Staging site on WP Engine to see if your change is on the site.
  6. Make a PR from Develop into Master
  7. Check Codeship to see if a thing happened, but this time for Master
  8. Check the “Prod” site on WP Engine to see if your change is on the site

Add Base Content to WP Engine

To save yourself some time, add some of the base Content / Information Architecture to the WP Engine site.

  1. Add some default Pages for the site
  2. Set up the Primary Menu
  3. Copy the site to WP Engine Staging
  4. Edit the Migrate DB Pro settings to pull it locally
Last updated on
PluginsHome