Twelve-Factor WordPress

WordPress, the Twelve-Factor way: fully managed using Composer and configured using environment variables.

General Concepts and Considerations

The WordPress installation is fully contained in top-level

wordpress

wp-content

composer install

wp-config.php

Locally bundled custom themes and plugins from top-level

themes

plugins

composer.json

wp-content

Automatic updates for WordPress or plugins, and theme editing, are disabled intentionally. What you deploy is what gets executed, which makes setups simple to deploy, and, most importantly, reproducible. See further below for information on how to update WordPress versions.

WP-CLI is used for easier (or automated) handling of tasks such as enabling plugins or storing configuration options. After a deploy, a set of pre-configured Composer scripts can run several administrative functions using WP-CLI, such as initially configuring the blog, and enabling plugins (this happens either automatically when using a Heroku button deploy, or manually). This means that the installation of plugins and their configuration can be part of your version controlled code, so you can easily re-create a blog installation without any manual steps that need separate documentation.

The configuration file is kept as generic as possible; on Heroku, add-ons JawsDB (for MySQL), Bucketeer (for S3 storage), and SendGrid (for E-Mails) are used.

The assumption is that this installation runs behind a load balancer whose

X-Forwarded-Proto

HTTPS is forced for Login and Admin functions.

WP_DEBUG

heroku logs

Quick Deploy

If you have a Heroku account, you may simply use the following button to deploy this application:

After the deploy, in Heroku's Dashboard under "Settings" for your deployed application, remove the

WORDPRESS_ADMIN_*

To set up WordPress' Cron Jobs using Heroku Scheduler, see further below.

Manual Deploy

Clone

Clone this repo (we're naming the Git remote "

upstream

origin

$ git clone -o upstream https://github.com/dzuelke/wordpress-12factor
$ cd wordpress-12factor

If you like, you can locally install dependencies with Composer:

$ composer install

Create Application and Add-Ons

Create a new app and add add-ons for MySQL, S3 and E-Mail:

$ heroku create
$ heroku addons:create jawsdb
$ heroku addons:create bucketeer
$ heroku addons:create sendgrid

Set WordPress Keys and Salts

This will use the WordPress secret keys service, parse out the values, and set them as config vars:

$ heroku config:set $(curl 'https://api.wordpress.org/secret-key/1.1/salt/' | sed -E -e "s/^define\('(.+)', *'(.+)'\);$/WORDPRESS_\1=\2/" -e 's/ //g')

You can also generate your own key and set all required variables yourself (see section further below).

Deploy

$ git push heroku master

Finalize Installation

This will create tables and set up an admin user:

$ heroku run 'composer wordpress-setup-core-install -- --title="WordPress on Heroku" --admin_user=admin --admin_password=admin [email protected] --url="http://example.herokuapp.com/"'

If you'd like to interactively provide info instead (use a format like "

http://example.herokuapp.com

$ heroku run 'vendor/bin/wp core install --prompt'

Finally, the following command will configure and enable plugins and set a reasonable structure for Permalinks:

$ heroku run 'composer wordpress-setup-finalize'

Visit Blog

Navigate to the application's URL, or open your browser the lazy way:

$ heroku open

Installing a new Plugin or Theme

1. Search for your plugin or theme on WordPress Packagist;
2. Click the latest version and check the version selector string in the text box that appears - it will look like

   "wpackagist-theme/hueman": "1.5.7"

   or

   "wpackagist-plugin/akismet": "3.1.7"

   ;
3. You don't want such an exact version, but instead a more lenient selector like (in the case above)

   ^1.5.7

   or at least

   ~1.5.7

   (see the Composer docs for details);

4. Run

   composer require wpackagist-$type/name:^$version

   , for example:

   composer require wpackagist-plugin/akismet:^3.1.7
   

   or

   composer require wpackagist-plugin/hueman:^1.5.7
   

5. Run

   git add composer.json composer.lock

   and

   git commit

   ;

6. git push heroku master

Activating a Plugin or Theme once

Run

heroku run 'vendor/bin/wp plugin activate

vendor/bin/wp theme activate

wp theme activate hueman

However, if you're working on an actual project, you will also want to ensure that this step can be run as part of the installation - see the next section for info.

Activating a Plugin or Theme, the repeatable way

See the

scripts

composer.json

wordpress-setup-enable-plugins

wp

After you adjusted the scripts section, run

composer update --lock

git add composer.json composer.lock

git commit

Bundling a Custom Theme or Plugin

It's likely you'll want to have a custom theme for your project, or use plugin code to customize the behavior of WordPress.

If you repeatedly use these same customizations across multiple projects, you should put them into their own (private or public) GitHub repository and reference them in the same way as explained above.

However, if the customizations you've made are specific to one project, then you should bundle them with the project code and pull them in as if they were an external theme or plugin.

You can put custom themes into the

themes/

composer.json

repositories

{
    "type": "path",
    "url": "themes/*/"
}

Each folder under

themes/

composer.json

{
    "type": "wordpress-theme",
    "name": "yourgithubname/yourthemename",
    "version": "1.0.0",
    "require": {
        "composer/installers": "~1.0"
    }
}

The

wordpress-theme

extra

installer-paths

composer.json

The same technique can be used for plugins; simply adjust the directory name and

repositories

wordpress-plugin

composer.json

Whenever you run

composer install

themes/

Updating WordPress and Plugins

To update all dependencies:

$ composer update

Alternatively, run

composer update johnpbloch/wordpress

composer update wpackagist-plugin/sendgrid-email-delivery-simplified

Afterwards, add, commit and push the changes:

$ git add composer.json composer.lock
$ git commit -m "new WordPress and Plugins"
$ git push heroku master

Web Servers

This project runs Apache by default, using the

apache2-wordpress.conf

wordpress/

To use Nginx instead, change

Procfile

web: vendor/bin/heroku-php-nginx -C nginx-wordpress.conf.php wordpress/

WordPress Cron

Instead of having WordPress check on each page load if Cron Jobs need to be run (thus potentially slowing down the site for some users), you can invoke Cron externally:

1. Run

   heroku config:set DISABLE_WP_CRON=true

   (or set it using the Heroku Dashboard) to disable built-in cron jobs;
2. Add Heroku Scheduler to your application;
3. Add a job that, every 30 minutes, runs

   vendor/bin/wp cron event run --all

   .

Environment Variables

wp-config.php

Database Connection

DATABASE_URL

JAWSDB_URL

CLEARDB_DATABASE_URL

mysql://user:[email protected]:port/dbname

AWS/S3

• AWS_ACCESS_KEY_ID

  or

  BUCKETEER_AWS_ACCESS_KEY_ID

  for the AWS Access Key ID;

• AWS_SECRET_ACCESS_KEY

  BUCKETEER_AWS_SECRET_ACCESS_KEY

  for the AWS Secret Access Key;

• S3_BUCKET

  or

  BUCKETEER_BUCKET_NAME

  for the name of the S3 bucket;

• S3_REGION

  for a non-default S3 region name.

SendGrid

SENDGRID_USERNAME

SENDGRID_PASSWORD

WordPress Secrets

WORDPRESS_AUTH_KEY

WORDPRESS_SECURE_AUTH_KEY

WORDPRESS_LOGGED_IN_KEY

WORDPRESS_NONCE_KEY

WORDPRESS_AUTH_SALT

WORDPRESS_SECURE_AUTH_SALT

WORDPRESS_LOGGED_IN_SALT

WORDPRESS_NONCE_SALT

Miscellaneous

DISABLE_WP_CRON