Adding a new site is as simple as adding it under the sites section of config.yml
then reprovisioning. If config/config.yml
does not exist, run vagrant status
and it will be created for you.
A VVV site in config.yml
will have a name, a provisioner repo:
that tells VVV how to install software such as WordPress, and hosts
that tell it the top level domains to serve the site on. We use the .test
TLD as it’s protected by RFCs and designed for local development ( .local
has more restrictions and is used by Bonjour/Zeroconf ).
Examples
Here are several examples of sites that can be added to config/config.yml
in the sites:
section:
WordPress Site WordPress Sub-directory Multisite WordPress Sub-domain Multisite WordPress Core Dev Environment WordPress.org Meta Environment WordPress Nightly Site Empty Custom Site A site with a wp-content git repo Drupal CraftCMS VIP Go Adding An Existing Site
Always Reprovision on Changes
Modifying a sites provisioner files, orconfig/config.yml
, requires a reprovision to take effect. To do this run: vagrant up --provision
WordPress Site
sites:
example:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- example.test
This creates a site named example
with a WordPress install at http://example.test
in the www/example/public_html
folder.
The repo
parameter tells VVV we want a WordPress site and downloads install instructions. The hosts
parameter tells VVV the domain to use for the site.
Then, save config/config.yml
and run vagrant up --provision
to update VVV with the new site. Be sure to indent correctly as whitespace matters in YAML files, VVV prefers to indent using 2 spaces.
Always Reprovision on Changes
Modifying a sites provisioner files, orconfig/config.yml
, requires a reprovision to take effect. To do this run: vagrant up --provision
Once vagrant up --provision
finishes, you will have a brand new WordPress install! We can now visit http://example.test to view the site, or open the www/example
folder in an editor to start making changes to our site. To log in, use admin
and password
.
WordPress Sub-directory Multisite
sites:
multisite-subdir:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- multisite.test
custom:
wp_type: subdirectory
This creates a subdirectory based multisite named multisite-subdir
at http://multisite.test
in the www/multisite-subdir/public_html
folder.
WordPress Sub-domain Multisite
sites:
multisite-subdomain:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- subdomainmultisite.test
- one.subdomainmultisite.test
- two.subdomainmultisite.test
custom:
wp_type: subdomain
This creates a subdomain multisite named multisite-subdomain
at http://subdomainmultisite.test
in the www/multisite-subdomain/public_html
folder. You will need to update the hosts
section and reprovision when adding new subdomains to the multisite. We recommend doing this in advance.
WordPress Core Dev Environment
sites:
wordpress-trunk:
description: "An svn based WP Core trunk dev setup, useful for contributor days, Trac tickets, patches"
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template-develop.git
hosts:
- trunk.wordpress.test
This creates a WordPress core dev site named wordpress-trunk
at http://trunk.wordpress.test
in the www/wordpress-trunk/public_html
folder.
This is useful for contributing to new WordPress releases, testing patches, or making fixes. This is not optimal for client work on plugins and themes.
WordPress.org Meta Environment
sites:
wordpress-meta-environment:
description: "An environment useful for contributions to the WordPress meta team."
repo: https://github.com/WordPress/meta-environment.git
hosts:
- wp-meta.test
custom:
provision_site:
"buddypressorg.test": true
"jobs.wordpressnet.test": true
"wordcamp.test": true
"wordpressorg.test": true
"wordpresstv.test": true
This creates a collection of sites for working on WordPress.org named wordpress-meta-environment
at http://wp-meta.test
in the www/wordpress-meta-environment/public_html
folder.
Provisioning this site takes a longer time, so be patient. It can be used to work on WordPress TV, WordCamps, and other .org sites.
WordPress Nightly Site
sites:
nightly:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- wpnightly.test
custom:
wp_type: nightly
This creates a WP Nightly site named nightly
at http://wpnightly.test
in the www/nightly/public_html
folder. This is useful for testing themes and plugins with unreleased versions of WordPress.
Empty Custom Site
sites:
foobar:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- mysite.test
custom:
wp_type: none
This creates a site named foobar
with an empty public_html
folder to put a static site or PHP application at http://mysite.test
in the www/foobar/public_html
folder.
You might do this if you have an existing site, or want to manually install WordPress or competing software.
A Site With a wp-content Git Repo
sites:
acmecorp:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- acme.test
folders:
public_html/wp-content/:
git:
repo: "repo to clone..."
overwrite_on_clone: true
This creates a WP site named acmecorp
at http://acme.test
in the www/acmecorp/public_html
folder. The specified git repo will be cloned to public_html/wp-content
, and the existing folder will be deleted and replaced with the git repo if cloning has not happened yet.
Click here for more information about custom git checkouts and folders.
Drupal
This creates a Drupal site named drupal-site
at http://drupal.test
in the www/drupal-site/public_html
folder.
sites:
drupal-site:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- drupal.test
folders:
public_html:
composer:
create-project: drupal/recommended-project
custom:
wp_type: none
public_dir: public_html/web
You will need to create a database using PHPMyAdmin for this site, and you might need to create custom Nginx rules. The example also assumes a public_html/web
subfolder is the webroot based on Drupal recommendations at the time of writing.
CraftCMS
This should set up a copy of Craft CMS in the public_html
folder, and tells VVV to serve the public_html/web
subfolder as the root, you may need to adjust the Nginx configuration of this site, or decide to change the folder configuration:
sites:
craft:
repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template.git
hosts:
- craft.test
folders:
public_html:
composer:
create-project: craftcms/craft
custom:
wp_type: none
public_dir: public_html/web
This creates a Craft CMS site named craft
at http://craft.test
in the www/craft/public_html
folder. Set up a database/user for Craft to use then head to https://craft.test/index.php?p=admin/install
to continue the installation.
After provisioning, you will need to complete setup by following the official Craft CMS install instructions.
Note that while this will install Craft for you via composer, nothing prevents setting wp_type: none;
and manually installing Craft by hand.
Additional Configuration Options
The custom site template supports options such as changing the version of WordPress, database names, site titles, and more. For a full list of what the official site template supports, check the readme on Github.
Migrating from VVV 1.x
If you’re migrating a site from VVV 1, read this page, then visit the migration page for further details.
Default Sites
VVV provides a number of default sites, and some that are disabled by default. If you can repurpose these then no config modification is necessary.
You may also find that the default sites created by VVV are enough for what you need. Read about the default sites here.
Importing a Production Database
At this point, mysql or phpMyAdmin can be used to upload a database for content, and the plugins/themes/uploads folders can be copied. The installation of WP will be in www/example/public_html
.
PHP Error Logs
PHP error logs are located in the main VVV folder in logs/php/
. Note that if your site specified WP_DEBUG_LOG
then WordPress will redirect PHP error logs to wp-content/debug.log
by default.
Official Site Templates
The site templates officially supported by VVV project are:
- https://github.com/Varying-Vagrant-Vagrants/custom-site-template - For when you just need a simple dev site
- https://github.com/Varying-Vagrant-Vagrants/custom-site-template-develop - For working with WP Core development
These can also be forked for custom provisioners. If you want to fork the site template, be sure to change the repo
value to point to your new location.
Always Reprovision on Changes
Modifying a sites provisioner files, orconfig/config.yml
, requires a reprovision to take effect. To do this run: vagrant up --provision