Updated README.md and created new index.md

README.md

@@ -3,37 +3,102 @@
 
 ## Introduction
 
-The is an Ansible playbook for Islandora CLAW. It also has a vagrant file to bring up a development
-environment virtual machine for Islandora CLAW.
+This is the development environment virtual machine (vm) for running Islandora 7.x-2.x (a.k.a. [Islandora CLAW](https://github.com/Islandora-CLAW/CLAW)). 
 
-This virtual machine **should not** be used in production **yet**.
+_This virtual machine **should not** be used in production **yet**._
+
+* It should work on any operating system that supports Ansible, Git, VirtualBox and Vagrant. 
+
+* It uses a suite of [Ansible](https://www.ansible.com/how-ansible-works) playbooks called within the Vagrantfile's provisioners section to install [Islandora CLAW](https://github.com/Islandora-CLAW/CLAW), its dependencies, additional software, user roles and more.
+
+* The information listed below is to serve as a quick getting started guide. 
+  * For more detailed information please navigate to the Technical documentation [here](/docs/index.md)
+
+---
 
 ## Requirements
 
-1. [VirtualBox](https://www.virtualbox.org/)
-2. [Vagrant](http://www.vagrantup.com/) 1.8.5+
-3. [git](https://git-scm.com/)
-4. [ansible](https://www.ansible.com/community) 2.3+
+1. [VirtualBox](https://www.virtualbox.org/wiki/Downloads) 5.1+
+2. [Vagrant](https://www.vagrantup.com/downloads.html) 1.95+
+3. [git](https://git-scm.com/downloads) 2.1+
+4. [ansible](http://docs.ansible.com/ansible/latest/intro_installation.html) 2.3+
+
+## System Resources
 
-## Variables
+By default the virtual machine (guest) that is built uses 3GB of RAM. The host machine **will need to be able to support** the additional memory use. 
 
-### System Resources
+One can override the CPU and RAM allocation by creating `ISLANDORA_VAGRANT_CPUS` and `ISLANDORA_VAGRANT_MEMORY` environment variables and setting the values within the Vagrantfile. 
 
-By default the virtual machine that is built uses 3GB of RAM. Your host machine will need to be able to support the additional memory use. You can override the CPU and RAM allocation by creating `ISLANDORA_VAGRANT_CPUS` and `ISLANDORA_VAGRANT_MEMORY` environment variables and setting the values. For example, on an Ubuntu host you could add to `~/.bashrc`:
+**Example 1:** Within an Ubuntu host machine one could add these values to `~/.bashrc` to increase the CPU & Memory usage of the (guest).
 
 ```bash
 export ISLANDORA_VAGRANT_CPUS=4
 export ISLANDORA_VAGRANT_MEMORY=4096
 ```
 
-## Use
+**Example 2:** Within the Vagrant file, one could edit these values to increase the CPU & Memory usage prior to running `vagrant up` to launch the virtual environment (guest) with more resources allocated.
+
+````
+$cpus   = ENV.fetch("ISLANDORA_VAGRANT_CPUS", "4")
+$memory = ENV.fetch("ISLANDORA_VAGRANT_MEMORY", "4096")
+````
+
+## System Ports
+The following services and ports are mapped/exposed from the development environment virtual machine (guest) to the (host) laptop, workstation or server that runs Virtualbox.
+
+Please note that in the event of conflict, the port values for the **host ONLY** should be changed within the Vagrantfile. These values can be arbitrary. This can often occur when running more than one Vagrant server at time. 
+
+**Original Vagrant port settings**
+* `guest: 8000, host: 8000` # **Apache**
+* `guest: 8080, host: 1234` # **Tomcat**
+* `guest: 8181, host: 8181` # **Karaf**
+* `guest: 8282, host: 8282` # **Islandora Microservices**
+* `guest: 3306, host: 3306` # **MySQL**
+* `guest: 5432, host: 5432` # **PostgreSQL**
+* `guest: 8983, host: 8983` # **Solr**
 
-1. clone the repo
-2. `vagrant up`
+**Example Vagrant port settings change**
+
+`guest: 8080, host: 8081` # **Tomcat**
+
+## Installation
+
+1. Open up a terminal and clone this repository to the host system
+
+````
+git clone https://github.com/Islandora-Devops/claw-playbook.git
+````
+
+2. Navigate to the newly cloned repository directory
+
+````
+cd ~/claw-playbook
+````
+3. Start up the development environment virtual machine. 
+
+```
+vagrant up
+````
+This process will automatically provision all software, users etc upon the first launch using the Ansible playbook called `playbook.yml` found at the bottom of the Vagrantfile. 
+
+**Please note:** this process can take upwards to 1-2 hours depending on the speed of one's internet connection, speed of disk etc.
+
+To reprovision the server (reinstall software)
+
+````
+vagrant reload --provision
+````
+
+
+---
 
 ## Connect
 
-You can connect to the machine via the browser at [http://localhost:8000](http://localhost:8000).
+* One can connect to the guest vm via a webbrowser at [http://localhost:8000](http://localhost:8000).
+* One can also connect to the guest vm via ssh using one of two accounts: (_Both have sudoer's permissions_)
+
+  * `vagrant ssh`
+  * `ssh -p 2222 ubuntu@localhost`
 
 ### Drupal
 
@@ -58,27 +123,27 @@ Authentication is done via [Syn](https://github.com/Islandora-CLAW/Syn) using [J
   * username: islandora
   * password: islandora
 
-### SSH
-
-You can connect to the machine via ssh:
-
-  * `vagrant ssh`
-  * `ssh -p 2222 ubuntu@localhost`
-
 ### VM
 
-The default VM login details are:
+The default vm login details are:
 
   * username: ubuntu
   * password: ubuntu
-
+
+### **Key terms**
+  * **vm** = virtual machine running Ubuntu 16.04 LTS
+  * **guest** = the virtual machine running Islandora and services
+  * **host** = system running Virtualbox and its virtual machines a.k.a guests). Typically a laptop, workstation etc.
+
 ## Roadmap
 
 1. Get feature parity with [CLAW Vagrant](https://github.com/Islandora-CLAW/claw_vagrant)
 2. Break each role out into its own git repo, so they can be listed on galaxy
 3. Test install on multiple boxes
 4. Test with other operating systems (?)
+5. Document
 
 ## Maintainers
 
+* [Danny Lamb](https://github.com/dannylamb)
 * [Jonathan Green](https://github.com/jonathangreen)

docs/index.md

@@ -0,0 +1,120 @@
+# Index
+
+  * About - About this project
+  * Installation - Installing Islandora CLAW using Ansible
+  * Software - Islandora CLAW dependencies and their versions
+  * Vagrant - virtual machine information
+  * Usage - Using CLAW
+  * Contributing - How to contribute
+  * Documentation - How to build this documentation in mkdocs
+
+___
+
+## About CLAW Vagrant Islandora 7.x-2.x
+
+[Islandora](http://islandora.ca) is an open-source software framework designed to help institutions and organizations and their audiences collaboratively manage, and discover digital assets using a best-practices framework.  Islandora was originally developed by the University of Prince Edward Island's Robertson Library, but is now implemented and contributed to by an ever-growing international community.
+
+Islandora CLAW consists of:
+
+  * [Sync](camel/sync/README.md) - Event driven middleware based on Apache Camel that synchronizes a Fedora 4 JCR with a Drupal CMS.
+  * [Islandora](drupal/islandora/README.md) - Fedora 4 Repository module
+  * [Install](install/README.md) - The is a development environment virtual machine for the Islandora CLAW project. It should work on any operating system that supports Ansible, Git, VirtualBox and Vagrant.
+
+---
+
+## Installation 
+
+The [installation section](install/README.md) provides and overview on how to create a virtual development environment.
+
+## Using Ansible 
+
+* List of commands here
+
+## Ansible Playbook structure
+
+````
+├── LICENSE
+├── README.md
+├── Vagrantfile
+├── ansible.cfg
+├── bootstrap.yml
+├── database.yml
+├── docs
+│   └── index.md
+├── inventory
+│   └── vagrant
+│       ├── group_vars
+│       └── hosts
+├── karaf.yml
+├── playbook.yml
+├── requirements.yml
+├── roles
+│   ├── external
+│   │   ├── apache
+│   │   ├── composer
+│   │   ├── drupal
+│   │   ├── drupal-console
+│   │   ├── drush
+│   │   ├── geerlingguy.php
+│   │   ├── git
+│   │   ├── java
+│   │   ├── mysql
+│   │   ├── php
+│   │   ├── postgresql
+│   │   └── solr
+│   └── internal
+│       ├── blazegraph
+│       ├── cantaloupe
+│       ├── fcrepo
+│       ├── fcrepo-syn
+│       ├── fits
+│       ├── grok
+│       ├── karaf
+│       ├── openseadragon
+│       ├── tomcat8
+│       └── webserver-app
+├── solr.yml
+├── tomcat.yml
+└── webserver.yml
+````
+
+* playbook.yml
+* requirements.yml
+* solr.yml
+* tomcat.yml
+* webserver.yml
+
+
+* Ansible Galaxy Explained
+
+## Software
+
+* Ubuntu 16.04 LTS
+* MySQL 
+
+## Vagrant
+
+* Currently uses the Vagrant box ubuntu/xenial 
+
+## Usage
+
+The [usage section](install/README.md) provides and overview on how to run and connect to the virtual development environment.
+
+## Contributing
+
+If you would like to contribute, please get involved with the [Islandora DevOps Group](https://github.com/Islandora-Devops/claw-playbook), and check out the [contributing section](contributing/contributing.md). We love to hear from you!
+
+If you would like to contribute code to the project, you will need to be covered by an Islandora Foundation [Contributor License Agreement](http://islandora.ca/sites/default/files/islandora_cla.pdf) or [Corporate Contributor Licencse Agreement](http://islandora.ca/sites/default/files/islandora_ccla.pdf). Please see the [Contributors](http://islandora.ca/resources/contributors) page on Islandora.ca for more information.
+
+## Documentation
+The [How to build documentation](technical-documentation/docs-build.md) provides and overview on how the documentation is created, built, and deployed.
+
+## Sponsors
+
+## Maintainers
+
+* [Daniel Lamb](https://github.com/daniel-dgi/)
+
+## Licensing
+
+Islandora is licensed under the GNU General Public License, Version 3. See [LICENSE](https://github.com/Islandora-Labs/islandora/blob/7.x-2.x/LICENSE) for the full license text.