WordPress at MIT Libraries

WordPress is one of several content management systems used at the MIT Libraries, and forms the majority of libraries.mit.edu.

Deployments

Local deployments

WordPress is used on EC2 instance VMs that are administered by the Enterprise Services team. The Wordpress installation can be found at the Apache site root, which is:

/var/www/html/htdocs/

Other applications can also be found under htdocs/, including a number of static HTML files. Full documentation of the structure of the site can be found on the UX/WS wiki.

Cloud deployments

The Libraries have been experimenting with the Pantheon cloud platform, and have set up an agency account to coordinate this work. In order to join the account, first sign up for a free Pantheon account and then contact Matt Bernhardt to be added to the agency.

Upgrading

Updates to the WordPress core, and community-contributed themes and plugins, are largely performed using the standard process in the administrative UI. For security purposes, however, the WordPress application is kept in a “locked” state that prevents self-modification.

Scripts to lock and unlock the Wordpress network can be found on MIT’s GitHub. Running these scripts requires terminal access to each server. Questions about this process should be directed to the Enterprise Systems team.

  1. Unlock WordPress

  2. Apply updates via administrative UI

  3. Lock WordPress

Database migrations

At times it is necessary to move database content between tiers. For example, we copy production content down to the staging site in order to evaluate a significant site redesign. As part of this process, it is necessary to run a search-and-replace tool in order to change the site address throughout the database.

The WordPress CLI has a search-replace command to accomplish this goal. The specific flags that we use include network, path, and url:

/usr/local/bin/wp --network --path=/var/www/html/htdocs --url=http://old.website.url search-replace old.website.url new.website.url

Locally Developed Code

While much of what we do with WordPress involves working with code that is written elsewhere, there are times where we need to write a plugin or theme locally.

Style and Coding Conventions

The WordPress community has adopted a set of coding standards to which all the projects we develop should adhere. This includes standards for PHP, HTML, CSS, and JavaScript.

For local development, we recommend using PHP_CodeSniffer from Squiz Labs as a linter before pushing code to GitHub. The WordPress Coding Standards have been implemented for PHPCS on GitHub.

GitHub offers integrations with Travis-CI and CodeClimate, both of which can be used to run PHPCS and similar code analysis tools.

Test Frameworks

Because most local development at the MIT Libraries focuses on the theme layer, testing is frequently not practical beyond linting and static code analysis (see above).

Project Documentation

Documentation for a specific theme or plugin should be contained in markdown files, inside a docs/ directory in each repository. Where documentation is simple enough, it can be contained only within the readme.md file.

Upgrading Local Projects

You will need terminal access to the server, and your account should have git and node available. We recommend creating a deploy/ directory under your account, and using the deploy scripts for plugins and themes that we have written.

The steps to upgrade a locally-written project look like this:

  1. Check out the project/branch you are upgrading into ~/deploy/$project-name

git clone git@github.com:MITLibraries/wp-plugin-template.git ~/deploy/wp-plugin-template

  1. If needed, install/run grunt to build

cd ~/deploy/wp-plugin-template
scl enable rh-nodejs8 /bin/bash
npm install
grunt

  1. Run the relevant deploy script, passing the project name as arguments. If you have not placed the deploy script into your deploy directory already, you can symlink it from /usr/local/scripts/.

cd ~/deploy/
./deploy-plugin.sh wp-plugin-template wp-plugin-template

Template projects

We have created a reference project that includes the recommended tooling integrations and code standards:

Plugin Template

Integrations

Integrations between Wordpress and external systems are needed for some functionality. Some of these integrations are covered elsewhere in this documentation (exception monitoring and centralized logging, for example).

Other integrations that are more specific to WordPress are detailed below.

Zapier / Airtable and webforms

Web forms on libraries.mit.edu should be built and maintained using the Contact Forms 7 (CF7) plugin. Documentation for this can be found on the UX wiki. By design, this system keeps no record of submissions within WordPress. The forms send emails, and the receiving system is responsible for tracking the submission.

A small number of forms, however, do not work via email. Those forms instead send submissions via webhook to Zapier, which in turn sends them to Airtable for processing.

The Zapier account which stores this workflow is controlled by UX, with some assistance from EngX. Some details are stored within the WordPress form UI, while the Zapier UI controls the crosswalk between the form and Airtable.

The Airtable bases are constructed and maintained by each form owner. As of this writing, Distinctive Collections is the only area of the Libraries which uses this setup.