Announcing WPDistillery – Dead-Simple WordPress for Scotch Box

Setting up WordPress on Scotch Box with WP Distillery in 5 minutes.

Today, I'm proud to announce "WPDistillery" - the easiest way to WordPress and Scotch Box together. Scotch Box is an amazing tool for setting up a local environment on WordPress. It's super easy and dead-simple to use. WPDistillery follows these same principles.

In this tutorial, we will go through the process of setting up a new WordPress site within Scotch Box. WPDistillery uses WP-CLI and a bash script to set your individual WordPress configuration up while you're getting yourself a coffee.

This post will cover:

  • Why is WPDistillery so awesome?
  • Installation
  • The setup
  • Installation & Setup Video
  • The configuration file file explained in detail
  • About

Why is WPDistillery so awesome?

It's a huge time saver! And it allows you to use similar configurations for all of your WordPress projects.

The first steps when creating a new WordPress project are almost always the same:

  • Download WordPress
  • Setup the database
  • Download and install a starter theme
  • Add your favorite plugins
  • Configure your preferred options
  • So on, etc.

WPDistillery does all this for you and even more. There's even a cleanup option that remove the default themes, posts, comments, and README files.

All your settings (preferred language, plugin list, core language, starter theme, user, WordPress settings etc.) are stored in a simple config.yml which determinates how WPDistillery will be installing and configuring WordPress for you.

WPDistillery is designed for Scotch Box. So there won't be any additional requirements. If you're using Scotch Box as your VM, just add WPDistillery and you're good to go!

It will take you no longer than two minutes to do all of this. And with your very own configuration file, you can re-use your settings for the following projects as well.

Installation

To setup a new project running Scotch Box and WordPress simply follow these steps:

Run the following command inside your project root to install Scotch Box & WPDistillery or clone/download Scotch Box and WPDistillery.

git clone https://github.com/scotch-io/scotch-box.git && mv scotch-box/public public && mv scotch-box/Vagrantfile Vagrantfile && rm -rf scotch-box && git clone --depth 1 git@github.com:flurinduerst/WPDistillery.git && mv WPDistillery/config.yml config.yml && mv WPDistillery/setup.sh setup.sh && rm -rf WPDistillery

Your project folder should look like this:

folders and files

The setup

  1. Now to the heart of WPDistillery: the configuration file. Open config.yml and define your settings. Choose things like your preferred WordPress language, your user name, the domain, title or rewrite structure and add the starter theme you want to use. You can even give WPDistillery a list of plugins to download, install and (optionally) activate. A detailed guide to the configuration file can be found further down this tutorial.
  2. Start your virtual machine by running vagrant up and access the Scotch Box with vagrant ssh
  3. Make sure WP-CLI is up to date: sudo wp cli update --allow-root
  4. Execute the setup.sh cd ../../var/www/ && bash setup.sh
  5. Get yourself a coffee or watch how WPDistillery does the work for you. The setup process should look something like this:

Setup Process in Console

Installation & Setup Video

Just watch the following video to see how easy it is to install and setup:

The configuration file in detail

In this section, we will go through the config.yml step by step as I will explain the options available.

Setup settings

In wpfolder you define the folder containing WordPress. Within the current version of Scotch Box this is public by default. With wplocale you can select what language to download and install for WordPress. Use language codes like en_US or en_GB. admin defines the default admin user. Set your preferred username, password and email. db contains the access data to connect WordPress to the database on the virtual machine. By default no changes are needed here.

# SETUP SETTINGS
#################################################################

# WordPress folder
wpfolder: public

# core language
wplocale: en_US

# admin user settings
admin:
  user: admin
  password: admin
  email: mail@domain.tld

# scotch box db access
db:
  name: scotchbox
  user: root
  pass: root
  prefix: wp_

WordPress Settings

In wpsettings you can define WordPress options like the URL, title and the permalink structure. Note: To edit the URL you use to access the website in your browser, edit config.vm.hostname in the Vagrantfile from Scotch Box.

# WORDPRESS SETTINGS
#################################################################

wpsettings:
  url: wpsetup.dev
  title: WP Setup
  rewrite_structure: /%postname%/

Theme

Now you can install a (starter-)theme if you want to. Simply add the theme's name and download URL. WPDistillery will then download, unarchive and install the theme. The optional rename will rename the previously installed theme for you.

# THEME
#################################################################

# theme to install, choose new name in 'rename' or leave empty
theme:
  name: WPSeed
  rename: ""
  url: https://github.com/flurinduerst/WPSeed/archive/master.zip

Plugins

You can select what plugins you want WPDistillery to install for you. Split into two sections, you can define which plugins to download and install, and which ones to activate. By default this section contains a few recommendations.

# PLUGINS
#################################################################

# plugins to install & activate
plugins_active:
  - disable-comments
  - duplicate-post
  - enable-media-replace
  - favicon-by-realfavicongenerator
  - regenerate-thumbnails
  - simple-page-ordering
  - user-switching
  - google-sitemap-generator

# plugins to install
plugins_inactive:
  #development
  - custom-post-type-ui
  - search-and-replace
  - capability-manager-enhanced
  #administration
  - adminimize
  - admin-menu-editor
  - admin-menu-reorder
  - wordpress-seo
  #security/backup
  - wp-security-audit-log
  - backwpup

If you want to install custom or premium plugins you can simply write down the download URL instead of the name. Make sure to add quotes:

plugins_active:
  - "https://example.com/plugins/awesome_plugin.zip&key=31071988"

Setup Options

Maybe you don't want WPDistillery to install a theme? Or you prefer keeping the default posts and files it comes with? Within the setup options at the bottom of the file you can tell WPDistillery which tasks it should perform. Simply set those you want to skip to false.

  • wp: install WordPress core
  • theme: install and activate the theme defined above
  • plugins: install the plugins listed
  • cleanup: delete WordPress defaults as followed
  • comment: the default comment
  • posts: the default post
  • files: readme.html, license.txt
  • themes: the twentyfourteen, twentyfifteen and twentysixteen theme
# SETUP OPTIONS
####################################################################
# if you don't want the setup to run all tasks, set them to false

installation:
  wp: true
  theme: true
  plugins: true
  cleanup: true
    comment: true
    posts: false
    files: true
    themes: true

Questions/Comments

Feel free to drop me a few lines on Twitter or head over to the GitHub repository to add issues or pull requests!

Special Thanks

Thanks to scotch.io for collaborating and supporting WPDistillery.

Special thanks to @scherii for being a great mentor and supporter over the past few years.

Flurin Dürst

Web Developer living in Switzerland. Founder of WPDistillery and WPSeed