Auto site Setup

Tom J Nowell edited this page Feb 4, 2018 · 21 revisions

VVV 2

Note: These are old instructions for VVV 1, and will not work in VVV 2+. For the latest documentation see here


VVV has a method by which sites can be setup during provisioning, so you can automate site setups within the VVV development environment. There are three elements to VVV's auto site setup:

  • Running a script you provide to do some setup tasks, like loading data, installing WordPress, checking out code from version control, etc
  • Adding a config you provide to VVV's Nginx
  • Allowing you to specify development domains for your site, which can be setup in your host machine and virtual machine /etc/hosts file

With these three elements, you can have VVV setup pretty much any kind of site in a wide variety of ways, whether it's a series of WP CLI commands, a composer.json file, a Git or SVN repo, or pretty much anything else you can think of.

You do not have to use all three elements, but you very often will.

The setup script

The setup script is at the heart of VVV's auto site setup system. VVV will find and run any script called vvv-init.sh within the www directory, as long as it's no deeper than 5 folders deep. You can have anything in this script, allowing you to have your site setup in any way. If you don't like bashscripts, you can have your vvv-init.sh simply call a Ruby or PHP script, or whatever you feel more comfortable with.

Note that you can have your vvv-init.sh create the Nginx configuration required for the next step, allowing you to have this dynamically created to, for example, read domains for the server_name from the database or extrapolate it from a folder name.

Here's an example of a simple vvv-init.sh script which just checks out WordPress trunk SVN:

#!/bin/bash

# Init script for WordPress trunk site

echo "Commencing WordPress trunk Setup"

# Make a database, if we don't already have one
echo "Creating database (if it's not already there)"
mysql -u root --password=root -e "CREATE DATABASE IF NOT EXISTS wordpress_trunk_auto"
mysql -u root --password=root -e "GRANT ALL PRIVILEGES ON wordpress_trunk_auto.* TO wp@localhost IDENTIFIED BY 'wp';"

# Check for the presence of a `htdocs` folder.
if [ ! -d htdocs ]
then
	echo "Checking out WordPress SVN"
	# If `htdocs` folder doesn't exist, check out WordPress
	# as that folder
	svn checkout http://svn.automattic.com/wordpress/trunk/ htdocs
	# Change into the `htdocs` folder we've checked SVN out into
	cd htdocs
	# Use WP CLI to create a `wp-config.php` file
	wp core config --dbname="wordpress_trunk_auto" --dbuser=wp --dbpass=wp --dbhost="localhost" --allow-root
	# Use WP CLI to install WordPress
	wp core install --url=wordpress-trunk-auto.test --title="WordPress Trunk Auto" --admin_user=admin --admin_password=password --admin_email=demo@example.com --allow-root
	# Change folder to the parent folder of `htdocs`
	cd ..
else
	echo "Updating WordPress SVN"
	# If the `htdocs` folder exists, then run SVN update
	svn up htdocs
fi

# The Vagrant site setup script will restart Nginx for us

# Let the user know the good news
echo "WordPress trunk site now installed";

Nginx config

In order to have a site served from VVV's Nginx, you will need a config file called vvv-nginx.conf. VVV will find any file named vvv-nginx.conf up to 5 folders deep inside the www directory and copy it to the VVV Nginx config directory when VVV is provisioned. VVV takes care of clearing up after itself, and effectively removes this file from the Nginx configuration when the site is removed.

Your Nginx config file might look similar to this:

server {
    # Listen at port 80 for HTTP requests
    listen			80;
    # Listen at port 443 for secure HTTPS requests
    listen			443 ssl;
    # The domain name(s) that the site should answer
    # for. You can use a wildcard here, e.g. 
    # *.example.com for a subdomain multisite.
    server_name		example.com;

    # The folder containing your site files.
    # The {vvv_path_to_folder} token gets replaced 
    # with the folder containing this, e.g. if this
    # folder is /srv/www/foo/ and you have a root
    # value of `{vvv_path_to_folder}/htdocs` this 
    # will be auto-magically transformed to
    # `/srv/www/foo/htdocs`.
    root			{vvv_path_to_folder}/htdocs;

    # A handy set of common Nginx configuration commands
    # for WordPress, maintained by the VVV project.
    include			/etc/nginx/nginx-wp-common.conf;
}

The domains for your site

This feature relies on you having the Vagrant Hosts Updater plugin installed. It is not essential.

Very often, development sites do not use domains which are backed up by real DNS, e.g. VVV's local.wordpress.test. Commonly this is achieved by editing your /etc/hosts file both on your host (real) machine and the Vagrant virtual machine. VVV's auto site setup has a method to automate this for you.

VVV will find and run any script called vvv-hosts within the www directory, as long as it's no deeper than 5 folders deep. Reloading the virtual machine will insert the hostnames on your host machine, provisioning the virtual machine will insert the hostnames on the virtual machine. The file should contain space separated domains which are used for the site. You can add line comments by prefixing a #, as in bashscripts. Note that wildcards do not work in vvv-hosts. Here's an example file:

# The main site domain
example.test
# Some subdomains
stuff.example.test
things.example.test

Examples of VVV auto site setups

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.