Skip to content

Latest commit

 

History

History
137 lines (83 loc) · 7.93 KB

README.md

File metadata and controls

137 lines (83 loc) · 7.93 KB

Basic WordPress Vagrant Environment

Version: 0.4.1

An easy to use, fast to spin up WordPress Vagrant environment modeled after managed WordPress hosting platforms like WP Engine and Flywheel.

Advantages

From a "cold boot" your WordPress Vagrant environment should be ready to go in about a minute, if not faster. Other WordPress Vagrant projects take much, much longer.

Requirements

Vagrant and VirtualBox must be installed. Mac users should also install Ansible with Homebrew: brew install ansible. The vagrant-hostmanager plugin is highly recommended, but not required.

Complete first-time setup instructions are below.

Windows Support

This project now runs successfully on Windows 10 when launched as an administrator. Two workflow issues remain unresolved: (see #4)

  • Vagrant Hostmanager silently fails to write to etc/hosts.
  • Microsoft Edge will not load websites from local IP addresses. IE11, Chrome and Firefox all work correctly.

Instructions

  1. Download the zip archive or clone this repo
  2. Unzip and rename the directory to yoursite.dev
  3. Add your WordPress project to the site directory (or replace site with a clone of your WordPress repository)
  4. Optionally copy a MySQL dumpfile into the project directory
  5. Run vagrant up

When the Vagrant environment is provisioned a fresh install of WordPress will be applied to the site directory. Any changes to core files or default themes will be lost. Those files should really never be changed anyway, and this decision is deliberate and intentional.

To avoid being asked for a password on every vagrant up (when using the vagrant-hostmanager plugin), edit the sudoers file and add the lines from this gist.

WP Engine Specific Instructions

  1. Download the zip archive or clone this repo
  2. Unzip and rename the directory to yoursite.dev
  3. Download a backup snapshot from your WP Engine Dashboard.
  4. Decompress the zip archive and rename the resulting directory to site
  5. Copy site into yoursite.dev, replacing the existing site directory.
  6. Run vagrant up

Flywheel Specific Instructions

  1. Download the zip archive or clone this repo
  2. Unzip and rename the directory to yoursite.dev
  3. Download a backup snapshot from your Flywheel Dashboard. Flywheel backup archives contains a backup.sql database dumpfile and a files directory.
  4. Rename files to site
  5. Copy site and backup.sql into yoursite.dev, replacing the existing site directory.
  6. Run vagrant up

Other Uses

While this project's main goal is to provide a fast, standard WordPress development environment based on popular managed hosts, there are times where that just won't work. For sites installed in a subdirectory or using other custom file structure, there are options to help stage those as well.

The config.yml file includes wp_dir and wp_content settings which can be used to override the WordPress defaults.

Complete, One-Time Setup Instructions

Below are the complete steps necessary to use the Basic WordPress Vagrant Environment on a new Mac. These steps should only need to be done once, but it's useful to review if something isn't working correctly.

  1. Download the Vagrant installer from vagrantup.com and install Vagrant.
  2. Download the VirtualBox installer from virtualbox.org and install VirtualBox.
  3. In the terminal, run brew update. If Homebrew is not installed, the one-line installation command is at the top of Homebrew's website.
  4. Still in the terminal, run brew install ansible to install Ansible.
  5. Finally, install the Vagrant Host Manager plugin by running this command in the terminal:
    vagrant plugin install vagrant-hostmanager

That's everything, now just follow the Instructions to spin up your WordPress environment.

Upgrading

One of this project's goals is to promote disposability: Developers should be able to spin up and tear down local development sites quickly and dependably. An ideal managed WordPress site is just a database dumpfile and whatever code exists in the wp-content directory. Everything outside of that should be replaceable. The only exception would be site-specific configurations in config.yml.

Additional Settings and Customizations

Many custom options can be set in config.yml:

  • wp_download can be used to install specific WordPress versions.

  • install_plugins toggles automatic installation of missing plugins

  • wp_dir changes the install location of WordPress, use this to install WordPress into a subdirectory.

  • wp_content remaps the wp-content directory. Useful for working on roots.io style installations.

  • enable_xdebug toggles xDebug display

  • table_prefix maps directly to the WordPress Database Table prefix in wp-config.php

Extras

  • Missing plugins will be installed if they can be found in the WordPress Plugin Directory.

  • All settings for Debugging in WordPress are enabled.

  • Save vagrant-hostmanager-nopasswd to /etc/sudoers.d/ for password-free, host-managed vagrant up.

  • File permissions are handled by managed hosts and may differ between projects. To ignore permissions for sites managed with Git, run this in your local repo: git config core.filemode false

Additional Notes

An extensive .gitignore file will be added to the site directory if one doesn't already exist. This file excludes all WordPress core files from Git.

The Ansible provisioner will search for MySQL database dumpfiles in the top five levels of the project, ignoring WordPress core and common vendor directories. The top-most (first-found) database dumpfile will be imported.

A default theme can be set in config.yml. If no default is set, the Ansible provisioner will attempt to activate a theme whose name matches the project hostname (usually the containing directory). So a project spun up in xyzco will attempt to activate the theme in xyzco/site/wp-content/xyzco/. These settings help prevent white-screens when restoring a project which uses versioned theme directories.

Using Composer from vagrant ssh may require a GitHub OAuth token. More info: API rate limit and OAuth tokens.

For direct MySQL access, vagrant ssh, then mysql wordpress.

The base box was generated from the ideasonpurpose/basic-wordpress-box project.

About

iop_logo
This project is sponsored by and used in production at Ideas On Purpose.