#WPLib Box
A pre-packaged virtual machine for local WordPress development.
##Why Use WPLib Box?
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,
And one more goal is that our box will support 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/PHP5-FPM | 5.6.20 |
MySQL | 5.5 |
nginx | 1.4 |
XDEBUG | 2.3.3 |
Redis | 2.8.4 |
WP CLI | 0.23.0 |
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 throughly yet so we welcome your bug reports if you have issues with it.
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 Composer
##Quickstart After making sure you have the necessary software, run the following commands:
# cd ~/Sites, or cd into whichever directory you store your website projects in
cd ~/Sites
git clone git@github.com:wplib/wplib-box.git
cd wplib-box
composer install
vagrant up
open "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.
##Setting the Domain Name
To use WPLib Box for a local domain name other than wplib.box
edit the Vagrantfile
and replace the text "wplib.box"
with your preferred local domain name (we recommend "dev.your-production-domain.tld"
):
In other words, change this:
config.vm.hostname = "wplib.box"
To (something like) this:
config.vm.hostname = "dev.example.com"
Save the changes to Vagantfile
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://dev.example.com"
The default local IP address used by this box is 192.168.33.10
.
If you need to change that for any reason simply edit the Vagrantfile
; change the following:
config.vm.network "private_network", ip: "192.168.33.10"
To something else that is compatible with your network, i.e. maybe:
config.vm.network "private_network", ip: "10.10.10.10"
We will probably change to a different default IP address in the future.
To login to wplib.box/wp-admin/ use the following credentials:
Credential | Value |
---|---|
Username: | admin |
Password: | admin |
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.
You must use an SSH Tunnel to connect into the VM when using an MySQL Client running on your host machine.
What this means is you will generally need to have two sets of credentials:
- The Database Credentials
- The SSH Tunnel Credentials
Here are the credentials you can use for MySQL database:
Credential | Value |
---|---|
IP Address or Host Name | 192.1688.33.10 or wplib.box (or dev.example.com ) |
Port | 3306 |
Username | wordpress |
Password | wordpress |
Here are the credentials you can use for the SSH tunnel:
Credential | Value |
---|---|
IP Address or Host Name | 192.1688.33.10 or wplib.box (or dev.example.com ) |
Port | 22 |
Authentication Method | Password |
Username | vagrant |
Password | vagrant |
Using these two sets of credentials with your SQL client you should be able to access and run SQL commands on the WordPress database.
##Debugging PHP with XDEBUG and PhpStorm
Instructions to come...
##How?
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.
##Status of Issues We are using Waffle.io to help us manage our GitHub issue queue:
##Future
We have many plans for the WPLib platform. This is just a start. Watch this repo to keep up to date.