Vagrant Drupal Development (VDD) is a fully configured and ready to use development environment built on Linux (Ubuntu 12) with Vagrant, VirtualBox and Chef Solo provisioner. VDD is a virtualized environment, so your base system will not be changed and remain clean after installation. You can create and delete as many environments as you wish without any consequences.

Note: VDD works great with 6, 7 and 8 versions of Drupal.

The main goal of the project is to provide an easy to use fully functional and highly customizable Linux based environment for Drupal development.

Setup is very simple, fast and can be performed on Windows, Linux or Mac platforms. It's simple to clone an existing environment to your Laptop or home computer and then keep it synchronized.

If you are not familiar with Vagrant, please read about it. Documentation is very simple to read and understand. http://docs.vagrantup.com/v2/

To start VDD you don't need to write your Vagrantfile. All configuration can be done a inside simple JSON configuration file.

• Configured Linux, Apache, MySQL and PHP stack
• Drush with site aliases
• PhpMyAdmin
• Xdebug

TODO:

• Webgrind
• Xhprof
• Mailing system
• Other development tools and useful software

VDD uses Chef Solo provisioner. It means that your environment is built from the source code. All you need is to get base system, the latest code and build your environment.

1. Install VirtualBox https://www.virtualbox.org/wiki/Downloads

2. Install Vagrant http://docs.vagrantup.com/v2/installation/index.html

3. Install vagrant host updater plugin. Please note on this one that "plugin" is not available in some lower version of Vagrant. The solution so far is to upgrade to higher versions. $ vagrant plugin install vagrant-hostsupdater

4. Prepare VDD source code Download and unpack VDD source code and place it inside your local development folder. git clone CLONE_URL_OF_THIS_REPO

5. Adjust configuration | Copy config.example.json to config.json You can edit config.json file to adjust your settings. If you use VDD first time it's recommended to leave the original config as is.

6. Build your environment (Note : You might want to add your project before doing this step) To build your environment execute next command inside your VDD copy: $ vagrant up --provision

   Vagrant will start to build your environment. You'll see green status messages while Chef is configuring the system.

7. Visit 192.168.44.44 address OR the hostname specified in the config.json If you didn't change the default IP address in config.json file you'll see VDD's main page. Main page has links to configured sites, development tools and list of frequently asked questions. Follow instruction on how to quickly install Drupal

8. Configure Drupal Code sniffer with Coder module inside bin directory Reference : https://drupal.org/node/1419988

It's now time to add your default project inside the www folder.

Inside your VDD copy's directory you can find data directory. It's synchronized with virtual machine. You should place your application's files inside sub folders with the name of your project. You can edit your application's files on the host machine using your favorite editor or connect to virtual machine by SSH. VDD will never delete data from data directory, but you should backup it.

Vagrant's basic commands (should be executed inside VDD directory):

• $ vagrant ssh SSH into virtual machine.

• $ vagrant up Start virtual machine.

• $ vagrant halt Halt virtual machine.

• $ vagrant destroy Destroy you virtual machine. Source code and content of data directory will remain unchangeable. VirtualBox machine instance will be destroyed only. You can build your machine again with vagrant up command. The command is useful if you want to save disk space.

• $ vagrant provision Reconfigure virtual machine after source code change.

• $ vagrant reload Reload virtual machine. Useful when you need to change network or synced folder settings.

Official Vagrant site has beautiful documentation. http://docs.vagrantup.com/v2/

If your Host machine has Drush already you can use it to manage your VDD environment. All you need to do is create a file called vdd.aliases.drushrc.php in ~/.drush in your host machine. The file should contain the below script.

<?php
$aliases['vdd'] = array(
  'parent' => '@parent',
  'site' => 'vdd',
  'env' => 'local',
  'uri' => 'vdd/NAME_OF_FOLDER',
  'root' => '/var/www/NAME_OF_FOLDER/',
  'remote-host' => '192.168.44.44',
  'remote-user' => 'vagrant',
  'php' => '/usr/bin/php',
);

To be able to execute Drush commands against VDD, while on your host machine:

$ drush @vdd [DRUSH_COMMAND]

Examples:

$ drush @vdd cc all
$ drush @vdd en views -y
$ drush @vdd vset preprocess_css 1 -y
$ drush @vdd status

N.B. Make sure that you uploaded the host public key on Vagrant.

You should understand that every time you start virtual machine Vagrant will fire Chef provisioner. If you want to customize your VDD copy you should do it right way.

Templates override

If you want to change some configuration files, for example, php.ini you should override default VDD's template. All templates a located in cookbooks/core/vdd/templates/default

All you need is to copy template file into cookbooks/core/vdd/templates/ubuntu directory and edit it.

Writing custom role

If you want to make serious modifications you should write your custom role and add it in config.json file. Please, see vdd_example.json file inside roles directory.

config.json is the main configuration file. Data from config.json is used to configure virtual machine. After editing file make sure that your JSON syntax is valid. http://jsonlint.com/ can help to check it.

• hostname (string, required) URL of the machine automatically added to the /etc/hosts if you have vagrant host updater plugin (vagrant plugin install vagrant-hostsupdater)

• ip (string, required) Static IP address of virtual machine. It is up to the users to make sure that the static IP doesn't collide with any other machines on the same network. While you can choose any IP you'd like, you should use an IP from the reserved private address space.

• memory (string, required) RAM available to virtual machine. Minimum value is 1024.

• synced_folder (object of strings, required) Synced folder configuration.

  • host_path (string, required) A path to a directory on the host machine. If the path is relative, it is relative to VDD root.

  • guest_path (string, required) Must be an absolute path of where to share the folder within the guest machine.

• php (object of strings, required) PHP configuration.

  • version (string or false, required) Desired PHP version. Please, see http://www.php.net/releases for proper version numbers. If you would like to use standard Ubuntu package you should set number to "false". Example: "version": false.

• mysql (object of strings, required)_ MySQL configuration.

  • server_root_password (string, required) MySQL server root password.

• sites (object ob objects, required) List of sites (similar to virtual hosts) to configure. At least one site is required.

  • Key (string, required) Machine name of a site. Name should fit expression '[^a-z0-9_]+'. Will be used for creating subdirectory for site, Drush alias name, database name, etc.

    • account_name (string, required) Drupal administrator user name.

    • account_pass (string, required) Drupal administrator password.

    • account_mail (string, required) Drupal administrator email.

    • site_name (string, required) rupal site name.

    • site_mail (string, required) Drupal site email.

• xdebug (object of strings, optional) Xdebug configuration.

  • remote_host (string, required) Selects the host where the debug client is running.

• git (object of strings, optional) Git configuration.

• custom_roles (array, required) List of custom roles. Key is required, but can be empty array ([]).

If you find a problem, incorrect comment, obsolete or improper code or such, please let us know by creating a new issue at http://drupal.org/project/issues/vdd