Merge branch 'dev' of github.com:hashbangcode/vlad-docs into dev

README.md

@@ -0,0 +1,5 @@
+[![Documentation Status](https://readthedocs.org/projects/vlad-docs/badge/?version=latest)](https://readthedocs.org/projects/vlad-docs/?badge=latest)
+
+# Documentation repository for Vlad
+
+Contribute to this project to improve the documentation for [Vlad](https://github.com/hashbangcode/vlad).

applications/drupal.md

@@ -1,4 +1,4 @@
-# Installing Drupal
+<h1>Installing Drupal</h1>
 
 Different versions of Drupal can be installed by scripts that are available on the box.
 
@@ -13,7 +13,7 @@ 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
+## 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.
 

applications/index.md

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

applications/munin.md

@@ -1,3 +1,3 @@
-# Munin
+<h1>Munin</h1>
 
-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.
+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

@@ -1,4 +1,4 @@
-# Setting Up Local MySQL Applications
+<h1>Setting up local MySQL applications</h1>
 
 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.
 
@@ -8,23 +8,23 @@ 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)*
+**MySQL Host:** value of ```boxipaddress``` in settings file
 
 **Username:** "root"
 
-**Password:** value of ```mysql_root_password``` in settings.yml
+**Password:** value of ```mysql_root_password``` in settings file
 
-**Database:** value of ```dbname``` in settings.yml *(optional)*
+**Database:** value of ```dbname``` in settings file *(optional)*
 
-**Port:** value of ```mysql_port``` in settings.yml
+**Port:** value of ```mysql_port``` in settings file
 
-**SSH Host:** value of ```boxipaddress``` in settings.yml
+**SSH Host:** value of ```boxipaddress``` in settings file
 
 **SSH User:** "vagrant"
 
 **SSH Key:** "~/.vagrant.d/insecure_private_key" *(browse to this file by clicking the key icon)*
 
-## MySQL Workbench (OS X)
+## MySQL Workbench
 As above - the values go in the following dialog:
 
 ![Vlad MySQL Workbench Settings](img/mysql-workbench-settings.png)

applications/php.md

@@ -0,0 +1,17 @@
+<h1>PHP</h1>
+
+## PHP Versions
+
+Different versions of PHP can be installed, but this depends on the operating system selected.
+
+The following table shows a breakdown of the different versions of PHP that can be installed onto the different operating systems available in Vlad. 
+
+PHP Version | Ubuntu 12 | Ubuntu 14| Centos 6.6
+------------ | ------------- | ---------------- | ----------
+5.3|X||X
+5.4|X||X
+5.5||X|X
+5.6||X|X
+
+<p>&nbsp;</p>
+

applications/varnish.md

@@ -1,8 +1,8 @@
-# Varnish
+<h1>Varnish</h1>
 
 A reverse proxy server that is used as a cache mechanism for Apache page requests. Varnish listens on port 80, but it can be bypassed by directly accessing Apache on port 8080.
 
 The Varnish secret key for the box is 04788b22-e179-4579-aac7-f3541fb40391, you will need this when using the Varnish modules in Drupal.
 Also you will need to select 3.x as your Varnish version and set the Varnish Control Terminal to be 127.0.0.1:6082.
 
-This module can be found at [https://www.drupal.org/project/varnish/](https://www.drupal.org/project/varnish/)
+This module can be found at [https://www.drupal.org/project/varnish/](https://www.drupal.org/project/varnish/).

applications/xdebug.md

@@ -1,6 +1,6 @@
-# Xdebug
+<h1>Xdebug</h1>
 
-The following lines detail the options that Vlad sets as the Xdegub setups.
+The following lines detail the options that Vlad sets as the Xdebug setup.
 
     xdebug.remote_enable=1
     xdebug.remote_port=9000
@@ -14,4 +14,4 @@ The following lines detail the options that Vlad sets as the Xdegub setups.
 
 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.
+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

@@ -1,4 +1,4 @@
-# Getting started with XHProf
+<h1>Getting started with XHProf</h1>
 
 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/).
 
@@ -10,4 +10,6 @@ This will continue to record statistics until you tell it not to. This can be do
 
     http://www.drupal.local:8080/?_profile=0
 
-XHGUI is available at https://github.com/preinheimer/xhprof
+XHGUI is available at https://github.com/preinheimer/xhprof
+
+Note that when enabled, XHProf injects "Profiler output" links at the bottom of each page on the site. This can cause errors or unexpected behavior with Ajax callback pages, such as Drupal's autocomplete form fields and others.

contributing/contributing.md

@@ -1,4 +1,4 @@
-# Contributing
+<h1>Contributing</h1>
 
 If you find a bug or want to improve Vlad in some way then open up an [issue](https://github.com/hashbangcode/vlad/issues).
 
@@ -10,6 +10,6 @@ In order to ensure that things run correctly all software installed should have
 
 The following is a list of standards that should be adhered to when contributing to Vlad.
 
-[Name Convention](Ansible%20Name%20Convention)
+- [Task naming convention](naming_convention.md)
 
-[Task Order Of Options Convention](Task%20Order%20Of%20Options%20Convention)
+- [Task attribute order convention](order_convention.md)

contributing/naming_convention.md

@@ -1,3 +1,5 @@
+<h1>Task naming convention</h1>
+
 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. 

contributing/order_convention.md

@@ -1,36 +1,28 @@
-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
+<h1>Task attribute order convention</h1>
 
-The notify option should always appear at the end of the task block.
-
-Examples:
+In order to make the Ansible tasks in Vlad easy to read they should follow the following order of attributes:
 
-```
-#!yaml
+1. `name` - should also follow the [name convention](naming_convention.md).
+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 will generally 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 (e.g. `changed_when`, `failed_when` etc).
+8. `notify` - needed if the task changes something that needs to restart a service. This should always appear at the end of the task block.
 
-- name: add varnish vcl
-  template: src=varnish_defaultvcl.j2 dest=/etc/varnish/default.vcl
-  sudo: true
-  notify:
-   - restart varnish
-```
+## Examples
 
-```
-#!yaml
-- name: install MailCatcher prerequisite packages
-  apt: pkg={{ item }} state=installed
-  with_items:
-    - rubygems
-    - libsqlite3-dev
-    - ruby-dev
-  sudo: true
+    - name: add varnish vcl
+      template: src=varnish_defaultvcl.j2 dest=/etc/varnish/default.vcl
+      sudo: true
+      notify:
+       - restart varnish
 
-```
+    - name: install MailCatcher prerequisite packages
+      apt: pkg={{ item }} state=installed
+      with_items:
+        - rubygems
+        - libsqlite3-dev
+        - ruby-dev
+      sudo: true

contributing/submitting_issues.md

@@ -0,0 +1,18 @@
+<h1>Submitting issues</h1>
+
+If you find a problem with Vlad then we would love to hear from you on the issue queue. Due to the dependent nature of the applications involved it really saves time if you ensure that you are up to date with the Vagrant, VirtualBox, and Ansible software. This helps to eliminate them from the list of problems.
+
+What also really helps is if you can give us a quick snapshot of what you currently have installed. This can be done by running the following command.
+
+    echo "VirtualBox `VBoxManage --version`"; vagrant --version; ansible --version; vagrant plugin list
+
+This produces output similar to the following:
+
+    VirtualBox 4.3.14r95030
+    Vagrant 1.6.3
+    ansible 1.8.4
+      configured module search path = None
+    vagrant-cachier (0.9.0)
+    vagrant-login (1.0.1, system)
+    vagrant-share (1.1.1, system)
+    vagrant-triggers (0.4.1)

contributing/testing.md

@@ -1,4 +1,4 @@
-# Testing
+<h1>Testing</h1>
 
 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.
 
@@ -14,4 +14,4 @@ These tests were added partly to give confidence that the box has been setup cor
 
 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
+    ansible-playbook vlad/playbooks/site.yml -t test