initial commit of existing documentation

applications/drupal.md

@@ -0,0 +1,28 @@
+# Installing Drupal
+
+Different versions of Drupal can be installed by scripts that are available on the box.
+
+To install Drupal 7 you need to run the /var/www/drupal7_install.sh script. This will download the latest version of Drupal 7 and install it into the MySQL database available on Vlad using the "Standard" installation profile. The Overlay module is also uninstalled automatically.
+
+To install Drupal 8 you need to run the /var/www/drupal8_install.sh script. This will pull the latest version of Drupal 8 from the Drupal git repository and install it into the MySQL database available on Vlad.
+
+User 1's login details for each of these Drupal install scripts is as follows:
+
+Username: admin
+Password: password
+
+NOTE: Both of these scripts will remove anything already in the /var/www/sites/docroot directory (or whatever name you have selected for it) so be careful.
+
+# Drush
+
+Vlad comes with both Drush 6 (current) and Drush 7 (dev) versions. This means you can run Drush commands against a Drupal 8 install.
+
+To run the current version of Drush just using the drush command as you normally would.
+
+    drush status
+
+To run the dev version of Drush you need to use either the `drush-master` or `drush7` alias in the same way as you would normally run Drush.
+
+    drush-master status
+
+    drush7 status

applications/index.md

@@ -0,0 +1,24 @@
+**Vlad Installed Applications**
+
+Vlad can install the following technologies:
+
+- [MySQL](mysql.md)
+- Apache2
+- PHP
+- Varnish
+- Git
+- [Drush](drupal.md) (with the 'site audit' and 'hacked!' modules)
+- [Munin](munin.md)
+- [Xdebug](xdebug.md)
+- Ruby (via RVM)
+- Sendmail
+- Mailcatcher
+- Memcached
+- Redis
+- Adminer
+- [XHProf](xhprof.md)
+- Solr (Version 4)
+- Node.js (including npm)
+- ImageMagick
+- PimpMyLog
+- [Drupal Install Scripts](drupal.md)

applications/munin.md

@@ -0,0 +1,3 @@
+# Munin
+
+Munin doesn't actually do anything on it's own, you have to connect a Munin server to it. You'll need to connect the Munin server to the virtual machine via port 4949.

applications/mysql.md

@@ -0,0 +1,30 @@
+# Setting Up Local MySQL Applications
+
+Below is a list of basic guides to setting up MySQL applications on your host box to communicate with databases located in your guest VMs.
+
+## Sequel Pro (OS X)
+
+Choose connection type "SSH" and complete the connection details as follows:
+
+**Name:** Whatever you'd like to label this connection.
+
+**MySQL Host:** "127.0.0.1" *(equivalent of "localhost" on the guest box)*
+
+**Username:** "root"
+
+**Password:** value of ```mysql_root_password``` in settings.yml
+
+**Database:** value of ```dbname``` in settings.yml *(optional)*
+
+**Port:** value of ```mysql_port``` in settings.yml
+
+**SSH Host:** value of ```boxipaddress``` in settings.yml
+
+**SSH User:** "vagrant"
+
+**SSH Key:** "~/.vagrant.d/insecure_private_key" *(browse to this file by clicking the key icon)*
+
+## MySQL Workbench (OS X)
+As above - the values go in the following dialog:
+
+![Vlad MySQL Workbench Settings](img/mysql-workbench-settings.png)

applications/xdebug.md

@@ -0,0 +1,17 @@
+# Xdebug
+
+The following lines detail the options that Vlad sets as the Xdegub setups.
+
+    xdebug.remote_enable=1
+    xdebug.remote_port=9000
+    xdebug.remote_handler="dbgp"
+    xdebug.remote_connect_back = 1
+
+    xdebug.profiler_enable=0
+    xdebug.profiler_output_dir=/tmp/xdebug_profiles
+    xdebug.profiler_enable_trigger=1
+    xdebug.profiler_output_name=cachegrind.out.%p
+
+This allows for both interactive debugging and profiling using Xdebug.
+
+The Xdebug profiler needs to be activated by passing the XDEBUG_PROFILE variable as a GET or POST parameter. When passed during a page load this will generate a file starting with _cachegrind.out._ in the /tmp/xdebug_profiles directory. Open these files with a program like KCachegrind to see data on how your application is performing.

applications/xhprof.md

@@ -0,0 +1,13 @@
+# Getting started with XHProf
+
+XHProf is an extension for PHP that allows performance statistics to be recorded. Vlad includes the XHGUI application that allows the statistics found to be used and interpreted. You can access the XHGUI via URL [http://xhprof.drupal.local/](http://xhprof.drupal.local/).
+
+When first loaded XHGUI will contain no data. You'll need to kick off XHProf on your site using "?_profile=1" at the end of the URL. If you have installed a Varnish/Apache setup (which is the default setup with Vlad) then you'll need to bypass Varnish using port 8080. The default URL to start XHProf is therefore:
+
+    http://www.drupal.local:8080/?_profile=1
+
+This will continue to record statistics until you tell it not to. This can be done by sending the _profile parameter to be 0. Like this:
+
+    http://www.drupal.local:8080/?_profile=0
+
+XHGUI is available at https://github.com/preinheimer/xhprof

contributing/contributing.md

@@ -0,0 +1,15 @@
+# Contributing
+
+If you find a bug or want to improve Vlad in some way then open up an [issue](https://github.com/hashbangcode/vlad/issues).
+
+Pull requests to the project are welcome but should not be done to the master branch.
+
+In order to ensure that things run correctly all software installed should have at least one test.
+
+## Standards
+
+The following is a list of standards that should be adhered to when contributing to Vlad.
+
+[Name Convention](Ansible%20Name%20Convention)
+
+[Task Order Of Options Convention](Task%20Order%20Of%20Options%20Convention)

contributing/naming_convention.md

@@ -0,0 +1,21 @@
+To keep things consistent we need to have a standard way of naming tasks within the system. Each task should have a name attribute that should describe what it is that the task is doing in simple terms. 
+
+If possible, this name should not exceed 80 characters. 
+
+The task name should follow the following rules:
+
+1. If the task filename shares the same name as the role it's in use:
+
+    - name: task description
+
+This will produce the following output (e.g. Adminer role):
+
+    TASK: [adminer | copy adminer stylesheet] ***************************
+
+2. If the task filename differs from the role it's in use:
+
+    - name: task filename (lowercase) | task description
+
+This will produce the following output (e.g. PEAR task within PHP role):
+
+    TASK: [php | pear | force upgrade of pear] ************************************

contributing/order_convention.md

@@ -0,0 +1,36 @@
+In order to make the Ansible tasks in Vlad easy to read they should follow the following order of attributes:
+
+1. name - should also follow the name convention
+2. module - followed by attributes (e.g. command: ls -la)
+3. with_items - used to supply a list of options to the task
+4. sudo - used if the task needs sudo access
+5. when - used to run a check before running the task
+6. tags - roles may have their own tags so these should only be added to tasks in certain circumstances
+7. any other option pertinent to the operation of the task (like changed_when, failed_when etc)
+8. notify - needed if the task changes something that needs to restart a service
+
+The notify option should always appear at the end of the task block.
+
+Examples:
+
+```
+#!yaml
+
+- name: add varnish vcl
+  template: src=varnish_defaultvcl.j2 dest=/etc/varnish/default.vcl
+  sudo: true
+  notify:
+   - restart varnish
+```
+
+```
+#!yaml
+- name: install MailCatcher prerequisite packages
+  apt: pkg={{ item }} state=installed
+  with_items:
+    - rubygems
+    - libsqlite3-dev
+    - ruby-dev
+  sudo: true
+
+```

contributing/testing.md

@@ -0,0 +1,17 @@
+# Testing
+
+Vlad runs some low level testing to give you peace of mind that everything is installed and that any changes made to the playbooks doesn't break the box.
+
+## Pre Testing
+
+Before running Vlad does a couple of checks to make sure that it has the settings it needs to run the rest of the install process. If any of the settings created don't work then provisioning of the box will fail.
+
+## Post Testing
+
+Once Ansible has set up the box a testing task is run. This checks to ensure that everything that was selected to be installed has been installed.
+
+These tests were added partly to give confidence that the box has been setup correctly and to aid future development work generally.
+
+It is possible to run the tests manually by using the 'test' tag like this:
+
+    ansible-playbook -i vlad/host.ini -t test vlad/playbooks/site.yml

index.md

@@ -0,0 +1,30 @@
+# Vlad
+
+Vlad stands for <u>V</u>agrant <u>L</u>AMP with <u>A</u>nsible and <u>D</u>rupal and is a development environment 
+that is easy to setup and has a number of features that make it useful for Drupal projects.
+
+This includes the following technologies:
+
+- MySQL
+- Apache2
+- PHP
+- Varnish
+- Git
+- Drush
+- Drush extensions: Site Audit, Hacked! & Registry Rebuild
+- Munin
+- Xdebug
+- Ruby
+- rbenv
+- Sendmail
+- Mailcatcher
+- Memcached
+- Redis
+- Adminer
+- XHProf
+- Solr (Version 4)
+- Node.js
+- ImageMagick
+- PimpMyLog
+
+Many of these items can be turned on and off via a settings file.

mkdocs.yml

@@ -0,0 +1,39 @@
+site_name: Vlad
+
+repo_url: https://github.com/hashbangcode/vlad
+site_description: 'Vlad: Vagrant LAMP with Ansible and Drupal.'
+docs_dir: .
+site_dir: ../docs_site
+theme: readthedocs
+
+pages:
+- ['index.md', 'Home']
+
+- ['usage/installation.md', 'Usage', 'Installation']
+- ['usage/getting_started.md', 'Usage', 'Getting Started']
+- ['usage/ansible.md', 'Usage', 'Ansible']
+- ['usage/custom_roles.md', 'Usage', 'Custom Roles']
+- ['usage/example_vlad_output.md', 'Usage', 'Example Vlad Output']
+- ['usage/project_structure.md', 'Usage', 'Project Structure']
+- ['usage/documentation.md', 'Usage', 'Documentation']
+- ['usage/vagrant_share.md', 'Usage', 'Vagrant Share']
+- ['usage/variables.md', 'Usage', 'Variables']
+
+- ['applications/index.md', 'Applications', 'Applications']
+- ['applications/mysql.md', 'Applications', 'MySQL']
+- ['applications/drupal.md', 'Applications', 'Drupal']
+- ['applications/xhprof.md', 'Applications', 'XHProf']
+- ['applications/xdebug.md', 'Applications', 'Xdebug']
+- ['applications/munin.md', 'Applications', 'Munin']
+
+- ['contributing/contributing.md', 'Contributing']
+- ['contributing/naming_convention.md', 'Contributing', 'Naming Convention']
+- ['contributing/order_convention.md', 'Contributing', 'Task Order Convention']
+- ['contributing/testing.md', 'Contributing', 'Testing']
+
+- ['project/faq.md', 'Project', 'FAQ']
+- ['project/roadmap.md', 'Project', 'Roadmap']
+- ['project/about.md', 'Project', 'About']
+- ['project/thanks.md', 'Project', 'Thanks']
+- ['project/changelog.md', 'Project', 'Change Log']
+- ['project/licence.md', 'Project', 'Licence']

project/about.md

@@ -0,0 +1,21 @@
+# About Vlad
+
+Vlad stands for <u>V</u>agrant <u>L</u>AMP with <u>A</u>nsible and <u>D</u>rupal and is a development environment 
+that is easy to setup and has a number of features that make it useful for Drupal projects.
+
+This box was originally developed by Phil Norton ([@philipnorton42](http://www.twitter.com/philipnorton42)) for use 
+when developing the site [#! code](http://www.hashbangcode.com/).
+
+Feel free to use this project in your own Drupal builds.
+
+All feedback and support very much appreciated :)
+
+    #  ______
+    # < Vlad >
+    #  ------
+    #         \   ^__^
+    #          \  (oo)\_______
+    #             (__)\       )\/\
+    #                 ||----w |
+    #                 ||     ||
+    #