cmoa-2016-readme.md

CMOA 2016

This project contains WordPress themes and a set of plugins for the Carnegie Museum of Art. The themes are based on the Sage starter theme.

Theme Development Requirements

Theme development requires node, Bower, Gulp, and WordPress premium plugins Advanced Custom Fields and WP Migrate DB Pro. These plugins and their license keys must be installed independently.

Local Development Requirements

This project also requires Docker. In this instance Docker, along with the provided Docker containers, will simplify local WordPress theme development by including the essential software for running this system on your local machine. This software includes Nginx, PHP, WordPress Core, and WP CLI.

While this project should run on any local system, the following instructions will assume you have installed Docker for Mac and Docker Toolbox. If you have not already installed Docker on your system you should do so before continuing.

Environment Setup

Review the contents of docker-compose.yml to get familiar with the configuration and settings including phpMyAdmin, Docker containers, and others.

1. Clone this repository into the local project folder.

2. Configure the local server with settings detailed in the sample config. Copy/paste contents of wp-config-sample.php to a new file wp-config.php.

3. Restart the Docker app on the local machine.

4. Pull down and run the Docker containers for this project:

   docker-compose up -d
   

Install Project Libraries and WordPress Plugins

About these libs... From the root project directory:

1. Install Composer.

2. Install Composer packages:

   php composer.phar install
   

3. A folder labeled vendor should be visible in the root project directory.

4. Install premium plugins, Advanced Custom Fields and WP Migrate DB Pro to wp-content/plugins/

Install Dev Tools & Dependencies

Node, npm, Bower, and Gulp are required for CMOA-2016 theme development. Each tool plays a roll in the development workflow. These tools are subject to change as better, simpler, tooling becomes available.

1. Update or install node and npm on the local machine.

2. Update or install Gulp and Bower globally:

   npm install -g Gulp-cli
   

   npm install -g bower
   

3. Install all other dependencies local to the project. From within the theme directory install:

   npm install
   

   bower install
   

Theme Development

Gulp automates the build process by running repetitive tasks from a few simple commands. The tasks are detailed in gulpfile.js at the root of each theme.

With Browsersync enabled, static assets will be recompiled/bundled when saved and your browser will automatically reload.

1. Compile assets. From within the theme directory run:

   gulp
   

Building Production Assets

These are the compiled assets that will be transferred from local development to staging or production.

1. Compile assets for production and update the asset manifest. From within the theme directory run:

   gulp production
   

First Run 🚀

1. Visit http://localhost in your browser and follow the steps to set up a new WordPress site. This setup is temporary and will be overwritten when the database is synced.
2. For Multi-site installs, follow the steps in the WordPress documentation to set up your network locally. Note, do not add the port number to the domain e.g. define('DOMAIN_CURRENT_SITE', 'localhost');.
3. Add license keys to Advanced Custom Fields and WP Migrate DB Pro plugins. Activate plugins.
4. Sync the production database to your local database with WP Migrate DB Pro plugin. Choose "Pull"...

Troubleshooting

Things happen. A step is missed and the whole workflow is not so much a “flow” but more like a wall. Here’s a list of common mistakes, and remedies, to help get that workflow flowing again.

1. Stuck in and endless WordPress install loop?
   • Was Composer installed correctly? After downloading Composer, be sure to run php composer.phar install.

To Do

• Plugins that need to be set up:
  • ElasticPress
  • Tenon API key
• Detail steps for Multi-site installation
• Update the Docker container to use Apachie over Nginx
  • More typical for WordPress installs and .htaccess readwrite rules