#WPLib Box
The EASIEST way to get a local WordPress development environment, using Vagrant.
CLICK HERE for quick help via wplib.slack.com#box.
CLICK HERE for troubleshooting and other FAQs.
- Why Use WPLib Box?
- Services & Software Included
- Required Hardware
- Required Software
- Quickstart
- Setting the Domain Name
- Changing the Local IP Address
- Default PHP Version for the Web
- Switching PHP Versions
- Logging into the WordPress Admin
- The WordPress Database Credentials
- The MySQL Credentials
- Connecting to MySQL in Terminal
- The SSH Credentials
- Logging into SSH as root
- Debugging PHP with XDEBUG and PhpStorm
- Internet Sharing
- Troubleshooting
- How are we the Best?
- 3rd Party WPLib Box Projects
- Status of Issues
- Future Plans
Why Use WPLib Box for WordPress local development instead of one of the other Vagrant boxes for WordPress such as VVV, VIP QuickStart, Trellis or one of the others?
Our GOAL is to be:
- The Easiest Box to Get Working Initially,
- The Fastest Box to
vagrant up - The Least Problematic Box in Day-to-Day Usage; especially when re-provisioning, which you rarely need to do with WPLib Box.
And one more goal we achieved is that our box supports PhpStorm+XDEBUG debugging with the least effort required on your part.
We think that once you try WPLib Box you will agree that we have succeeded. Want to know how we did it?
| Service/Software | Version |
|---|---|
| PHP/PHP-FPM | 7.0.18 & 5.6.30 |
| MySQL | 5.7.17 |
| MariaDB | 10.1.22 |
| Nginx | 1.11.0 |
| Apache | 2.4.25 |
| XDEBUG | 2.5.1 |
| Redis | 3.0.7 |
| WP CLI | 1.1.0 |
| Nodejs | 7.8.0 |
| localtunnel.me |
This box was developed using Mac OS/X and tested using Linux and Windows with git-bash. Thus we believe it currently works with:
| O/S | Notes |
|---|---|
| Mac OS X | Latest 3 releases of OS X, at least |
| Linux | Most (all?) distros of Linux |
| Windows 7 thru 10 | With PowerShell or git-bash |
We assume this will work on all these platforms but we have not tested it thoroughly yet so we welcome your bug reports if you have issues with it.
Since WPLib Box is distributed as a virtual machine image of a 64-bit distribution of Ubuntu Linux, a 64-bit Intel or AMD CPU is required, along with support for either Intel or AMD virtualization technologies: VT-x or AMD-v. You will need to enable VT-x/AMD-v in the host PC BIOS.
To run WPLib Box requires the following software be installed:
- Install VirtualBox
- Install Vagrant
- Install the Vagrant Hosts Updater plugin by running
vagrant plugin install vagrant-hostsupdater - Install the Vagrant Triggers plugin by running
vagrant plugin install vagrant-triggers
- Install everything from the Mac & Linux Users list above
- Ensure that no other VM platform is running (either VMware or Hyper-V) as they will prevent VirtualBox from operating.
- Install Git version 2 or greater OR download the
.ZIPfile and unzip instead.
##Quickstart After making sure you have the necessary software, run the following commands
###For Mac or Linux users:
# cd ~/Sites, or cd into whichever directory you store your website projects in
cd ~/Sites
git clone https://github.com/wplib/wplib-box.git
cd wplib-box
vagrant up
open "http://wplib.box"
###For Windows users:
# cd into whichever directory you store your website projects in.
# For example, your user profile: C:\Users\{current user}\Sites
c:
cd %userprofile%\Sites
#
# You can run the next command, or just download from the web and unzip into the wplib-box directory
#
git clone https://github.com/wplib/wplib-box.git
cd wplib-box
vagrant up
explorer "http://wplib.box"
After this you should have a running WPLib Box via Vagrant and VirtualBox and a website loaded at the local wplib.box domain.
To use WPLib Box for a local domain name other than wplib.box edit the HOSTNAME file (with no extension)
and replace the text "wplib.box" with your preferred local domain name (we recommend "your-production-2nd-level-domain.dev" e.g. if google.com then use google.dev):
In other words, change the entire contents of the HOSTNAME file from this:
wplib.box
To (something like) this:
example.dev
Save the changes to HOSTNAME and then run the following commands to reload the Vagrant configuration, and then open in your browser. (Be sure you replaced the domain name in the 2nd command with your own local domain name):
vagrant reload
open "http://example.dev"
The default local IP address used by this box is 10.10.10.{octet} where {octet} is a number between 10 to 250.
If you need to change that for any reason simply edit the file named just IP (with no extension) found in the project root. It is created during vagrant up and a random {octet} is generated. Just edit this file and change the IP address it contains.
The default version fot the web is 7.0.x. Instructions to switch to PHP 5.6 are on our FAQ.
The box has both PHP-FPM 5.6 and 7.0 running concurrently. They are implemented as separate processes with individual sockets. Instructions on how to select which version to use can be found in the FAQ.
To login to wplib.box/wp-admin/ use the following credentials:
| Credential | Value |
|---|---|
| Username: | admin |
| Password: | password |
We will probably change to using different username and password in the future.
If you want to access the database using a tool such as Sequel Pro the MySQL database name, username and password are all wordpress.
In other words:
define( 'DB_NAME', 'wordpress' );
define( 'DB_USER', 'wordpress' );
define( 'DB_PASSWORD', 'wordpress' );
We may change to using different MySQL credentials in the future.
Here are the credentials you can use for accessing the MySQL database using a GUI such as Sequel Pro, Navicat, et al:
| Credential | Value |
|---|---|
| Host Name | wplib.box (or example.dev) |
| Port | 3306 |
| Username | wordpress |
| Password | wordpress |
The MySQL server listens on all interfaces on port 3306. If you have the MySQL command-line client installed on your host machine, you can simply mysql --host wplib.box -u wordpress -pwordpress (assuming you are using the wplib.box hostname).
Here are the credentials you can use for the SSH tunnel:
| Credential | Value |
|---|---|
| Host Name | wplib.box (or example.dev) |
| Port | 22 |
| Authentication Method | Password |
| Username | vagrant |
| Password | vagrant |
There is no root user per-se in WPLib Box, only the vagrant user. You have to use either sudo for one-off commands, or you can use the following command to switch to root:
sudo -s
See instructions here.
Internet sharing is implemented with localtunnel.me, which is pre-installed in the box image.
If you are having trouble with WPLib Box please check out our Troubleshooting section of our FAQ and/or you can also reach out to our support team for quick help on Slack and via other channels.
How have we been able to make WPLib Box the:
- Easiest,
- Fastest and
- Least Problematic Vagrant box for local WordPress development
- Plus No-Fuss PhpStorm+XDEBUG Debugging?
Because we took the blinders off. We ignored the lead of everyone else who has created a Vagrant box for WordPress development and we rethought how a Vagrant box should be designed, using a blank canvas.
Instead of starting with a standard Linux distribution image as a base box — such as provided by Ubuntu — and then using Puppet, Chef or Ansible to provision the box on your computer while running inside of your Vagrantfile we provision and test the box IN ADVANCE.
Our Provision-in-Advance approach practically eliminates all the hair-pulling and infuriatingly unproductive time you frequently have to spend to solve an obscure provisioning issue in a script that you did not develop and thus know almost nothing about when you use one of the other boxes for local WordPress development. WPLib Box bypasses all those headaches for you and saves you tons of time!
What this means for you is that the only thing your Vagrantfile must do is:
- Specify our base box,
- Set your local domain name and local IP address,
- Mount your source code directory into the VM, and
- Extract WordPress core files from a ZIP file (but we only run this step on (re-)provisioning.)
Badda-bing, badda-bang; as Steve Jobs would say: It Just Works!
Give it a try and see if you don't agree.
- WPLib Box Maker from ArtOfWP: Generates a custom WPLib Box setup using Yeoman.
##Status of Issues We are using Waffle.io to help us manage our GitHub issue queue:
We have many plans for the WPLib platform. This is just a start. Watch this repo to keep up to date.