Note: Primary Vagrant 3.0 is a major upgrade from earlier versions. If you would like to use an older version please clone the 2.x branch instead.
Primary Vagrant is intended for WordPress plugin, theme, and core development, as well as general PHP development, and can be used as a replacement for local development stacks such as MAMP, XAMPP, and others.
Although Varying Vagrant Vagrants is great (and I still use it for some work), I wanted a few major changes. First, I wanted Apache instead of NGINX and, second, I wanted to use a more comprehensive provisioning tool like Puppet instead of Bash. Using VVV and Puppet as a base, this repository attempts to address these requirements for my own work with a Vagrant configuration that is ready to go for WordPress plugin or theme development.
The repository contains a Vagrant configuration with Puppet modules that will configure the following goodies:
- Ubuntu 16.04 LTS
- Apache
- PHP 7.0
- MySQL
- Xdebug
- PHP_CodeSniffer
- WordPress Coding Standards for PHP_CodeSniffer
- PHPUnit
- Postfix
- wp-cli
- phpMyAdmin
- WordPress (Last, Stable, Trunk and Dev)
- Various debugging plugins for WordPress
- Search Replace DB
- webgrind
- oh-my-zsh
- MailHog
- Test data from WP Test
- Composer
- node.js
- Git
- Subversion
- Memcached
- Redis
If you find any issues, please don't hesitate to submit a pull request.
- pv - Default menu
- phpmyadmin.pv - phpMyAdmin
- replacedb.pv - Search Replace DB
- core.wordpress.pv - WordPress development (for core dev)
- legacy.wordpress.pv - Last version of WordPress (currently 4.4.x)
- stable.wordpress.pv - Latest WordPress stable (currently 4.5.x)
- trunk.wordpress.pv - WordPress trunk
- webgrind.pv - webgrind
Install Vagrant, VirtualBox, and the VirtualBox extensions for your environment.
Once Vagrant is installed you'll want three plugins to update your local hosts and update the VirtualBox Guest additions in the Ubuntu install as well as for handling various tasks like backing up your databases when you're done for the day.
vagrant plugin install vagrant-vbguest
vagrant plugin install vagrant-ghost
vagrant plugin install vagrant-triggers
-
Clone this repo (and it's submodules) onto your local machine:
$ git clone --recursive https://github.com/ChrisWiegman/Primary-Vagrant.git PV
*Note: If you download it with the GitHub links you will not get the submodules and you'll wind up with a provisioning error.
-
Change into the new directory with
cd PV
-
Start the Vagrant environment with
vagrant up
- Be patient as the magic happens. This could take a while on the first run as your local machine downloads the required files.
- Pay attention during execution as an administrator or
su
password may be required to properly modify the hosts file on your local machine.
The following websites come pre-configured in the system:
- Default menu
- WordPress (last major release) at http://legacy.wordpress.pv
- WordPress (latest stable release) at http://stable.wordpress.pv
- WordPress Trunk at http://trunk.wordpress.pv
- WordPress Core Development at http://core.wordpress.pv
- Search Replace DB https://replacedb.pv
- phpMyAdmin http://phpmyadmin.pv
- WebGrind http://webgrind.pv
- MailHog http://pv:8025
*Note: WordPress Core dev is taken from git://develop.git.wordpress.org/. Only the src folder is mapped. You can manually set up a build site if desired.
php project.php --create-site
You will be prompted for a project name. This will be the name of the folder in your Primary Vagrant Sites folder and will be mapped to a related domain whereas all non-domain characters, such as space, etc, will be replaces with a "-" (dash). For example:
Project name My Project
will be reachable at: http://my-project
php project.php --delete-site
You will be prompted for a project name. This will be the name of the folder in your Primary Vagrant Sites folder and will be mapped to a related domain whereas all non-domain characters, such as space, etc, will be replaces with a "-" (dash). For example:
Project name My Project
will delete the Primary Vagrant project files in the folder my-project
__Note: Deleting a project will NOT delete the database nor the files. You may delete the database manually if you desire and files in the sites folder can be deleted with the --deletefiles
option.
php project.php --create-plugin
You will be prompted for a project name. This will be the name of the folder in your Primary Vagrant Sites folder and will be mapped to a related domain whereas all non-domain characters, such as space, etc, will be replaces with a "-" (dash).
Plugins will be available on trunk.wordpress.pv, stable.wordpress.pv and legacy.wordpress.pv.
php project.php --delete-plugin
You will be prompted for a project name. This will be the name of the folder in your Primary Vagrant Sites folder and will be mapped to a related domain whereas all non-domain characters, such as space, etc, will be replaces with a "-" (dash).
php project.php --create-theme
You will be prompted for a project name. This will be the name of the folder in your Primary Vagrant Sites folder and will be mapped to a related domain whereas all non-domain characters, such as space, etc, will be replaces with a "-" (dash).
Themes will be available on trunk.wordpress.pv, stable.wordpress.pv and legacy.wordpress.pv.
php project.php --delete-theme
You will be prompted for a project name. This will be the name of the folder in your Primary Vagrant Sites folder and will be mapped to a related domain whereas all non-domain characters, such as space, etc, will be replaces with a "-" (dash).
There are a number of advanced options you can use to customize your project there are as follows:
norpovision
Prevents vagrant from reloading and reprovisioning upon project creation/deletion.name
Specify the project name without a promptroot
A directory to map as the project root to keep the project files outside of Primary Vagrant. A folder with the project name will still be created in Primary Vagrant's sites folder but it will only hold files necessary for the project to be recognized in Primary Vagrant.deletefiles
Use this to force file deletion upon project deletion. Without this only the Primary Vagrant files will be removed and the sites folder will remain. Does not apply to root folders outside of the Primary Vagrant structure.domain
Specify the domain to use for a site. Will override the domain name generation from the project name.database
by default sites will get a database of the same name as the domain name. Use this option to override the database name.alias
Specify a domain alias for apache. Multiple aliases can be specified by calling this option multiple times.apacheroot
Specify a subfolder of the project root to be used as the apache root folder. Useful for projects like the Laravel where you may want to map one folder but have Apache only serve part of it.nodatabase
Don't create a database for a site project.
__Note: all options must be specified as --option=value (complete with the equal sign).
First, create a file called pv-mappings
in the user-data directory. This will map any sites you create to the appropriate folder on PV.
Example Mapping:
config.vm.synced_folder "user-data/sites/my-site/htdocs", "/var/www/my-site.pv", :owner => "www-data", :mount_options => [ "dmode=775", "fmode=774"]
*Note that if you're working on a WordPress plugin or theme I would recommend to simply map it to the three pre-installed WordPress sites. This will make it easy for you to test it on multiple versions of WordPress.
Example:
config.vm.synced_folder "user-data/sites/my-awesome-plugin", "/var/www/default-sites/wordpress/content/plugins/my-awesome-plugin", :owner => "www-data", :mount_options => [ "dmode=775", "fmode=774"]
Next Edit user-data/vhosts/``[your-site-domain].pp. This is where you define virtualhosts and databases. Copy what is below and ask me if you have any questions. Of course these aren't the only configuration options you have either. You can find a full list of Apache configuration options here and a full list of mysql configuration options here.
Example:
apache::vhost { 'mysite.pv':
docroot => '/var/www/mysite.pv',
directory => '/var/www/mysite.pv',
directory_allow_override => 'All',
ssl => true,
template => '/vagrant/provision/lib/conf/vhost.conf.erb'
}
mysql_database { 'mysite.pv':
ensure => 'present',
charset => 'utf8',
collate => 'utf8_general_ci',
require => Class['mysql::server'],
}
*Note: I've provided a top-level wildcard SSL certificate. No further SSL certificate should be needed.
Finally, and you can do this two ways...
- If you've created your site inside of the Primary Vagrant
user-data/sites/
folder, just add a file calledpv-hosts
to it that includes the domain name(s) (one per line) for your project. - If your site is outside of the Primary Vagrant folder I would recommend creating
user-data/pv-hosts
to hold the domain names. This will make sure you can access your sites by whatever domain names you need.
After the configuration above has been added, simply run vagrant halt && vagrant up
to trigger the changes and host file updates.
The default installation configuration is found in provision/init/. While you could edit these files if you like I would, instead, recommend adding any additional configuration to your virtualhosts file such as user-data/vhosts/custom.pp
You can access the database via ssh tunnel into the machine using the ouroboros hostname, the username vagrant, the password vagrant for ssh, and the username username with the password password for MySQL.
Postfix is configured and set to use your host computer as a mail relay. To receive messages you can use the built in MailHog installation (this will prevent your real SMTP mail server and mailbox from getting too much abuse).
The latest stable node.js version is installed, if you want to pre-install packages just add them to your sites virtualhost config such as user-data/vhosts/nodejs.pp.
Example:
package { 'ungit':
provider => npm,
require => Class['nodejs']
}
Ouroboros comes pre-configured with two awesome tools for helping debug your code. The first is Xdebug and the second is PHP_Codesniffer (which comes complete with the WordPress coding standards already pre-configured). While configuration is dependant on the code editor you use here are some notes that might help you get started with them.
- Xdebug uses VAGRANT_DEBUG as its IDE key
- Many modern tools will let you access both of these tools easily with just a bit of configuration. For example, here's a great post on using remote debugging in PHPStorm.
- PHPStorm configuration suggestions are in the wiki.
You can now also turn xdebug on or off completely with the commands xon
and xoff
. This should help speed up complex composer or other operations.
For debugging APIs or any other situation where sending a cookie with your request isn't ideal you can turn on auto-listening for xdebug in which case it will try to connect automatically, even without a cookie. To do this simply use the commands xlon
and xloff
to enable or disable auto-remote. Note that this is disabled by default.
Contributions are more than welcome. Please read our current guidelines for contributing to this repository. Many thanks in advance!
This server configuration is designed for development use only. Please don't put it on a production server as some of these settings would cause serious security issues.