[docs] Improved local-installation documentation #51

Closes #51

README.md

@@ -54,8 +54,7 @@ Install ansible
 Install ansible (version 2.4 or higher) **on your local machine** (not the production server!) if
 you haven't done already.
 
-To **install ansible** we suggest to follow the official
-[ansible installation guide](http://docs.ansible.com/ansible/latest/intro_installation.html).
+To **install ansible** we suggest you follow the official [ansible installation guide](http://docs.ansible.com/ansible/latest/intro_installation.html).
 
 After having installed ansible, **you need to install git** (example for linux debian/ubuntu systems):
 
@@ -68,6 +67,9 @@ For the sake of simplicity, the easiest thing is to install this role **on your
 via `ansible-galaxy` (which was installed when installing ansible), therefore run:
 
     ansible-galaxy install openwisp.openwisp2
+
+If you want to install the latest version of **OpenWISP 2** instead, run:
+`ansible-galaxy install git+https://github.com/openwisp/ansible-openwsip2.git openwisp.openwisp2`
 
 Choose a working directory
 --------------------------
@@ -140,7 +142,13 @@ You can remove `-k`, `--become` and `-K` if your public SSH key is installed on
 **Tips**:
 
 - If you have an error like `Authentication or permission failure` then try to use *root* user `ansible-playbook -i hosts playbook.yml -u root -k`
-- If you have an error about adding the host's fingerprint to the `known_hosts` file, you can simply connect to the host via SSH and then answering yes when prompted, and then try running `ansible-playbook` again.
+- If you have an error about adding the host's fingerprint to the `known_hosts` file, you can simply connect to the host via SSH and then answering yes when prompted, and then try running `ansible-playbook` again. 
+
+Alternatively, you can also disable `host_key_checking`. Just create a new file in the working directory named `ansible.cfg` and place the following contents within it:
+```yml
+[defaults]
+host_key_checking=False
+```
 
 When the playbook is done running, if you got no errors you can login at:
 
@@ -160,48 +168,75 @@ Now proceed with the following steps:
 Now you are ready to start configuring your network! **If you need help** you can ask questions
 on one of the official [OpenWISP Support Channels](http://openwisp.org/support.html).
 
-Install OpenWISP2 locally (laptop, desktop PC)
+Install OpenWISP2 in a VirtualBox VM
 ----------------------------------------------
 
-If you are trying to install *OpenWISP 2* on your laptop or desktop PC for testing purposes,
-you can run ``ansible-playbook`` with the ``--connection=local`` flag.
+If you want to check out **OpenWISP 2** on your own laptop, PC, you can simply do so. This section covers the steps involved to achieve the above stated task. The following steps have been written assuming you've already set-up your VM. The OS recommended for doing this is Ubuntu Server.
 
 **Step 1**: [Install ansible](#install-ansible)
 
-**Step 2**: [Install this role](#install-this-role)
+Install the latest ansible release as by referring to the ansible documentation.
+
+**Step 2**: [Install the OpenWISP2 role for Ansible](#install-this-role)
+
+Install the latest version of **OpenWISP2**
+
+`ansible-galaxy install git+https://github.com/openwisp/ansible-openwisp2.git openwisp.openwisp2`
 
-**Step 3**: Create `hosts` file:
+**Step 3**: [Set up a working directory](#choose-a-working-directory)
 
+**Step 4: Creating the `hosts` file**
+
+We are going to store the details of our production server in a separate file named `hosts`. Therefore create an empty file named `hosts` **in the working directory** and paste the below contents within it using a text editor.
 ```
 [openwisp2]
-<IP ADDRESS>
+localhost:3022
+##3022 is just a random port. Only using it for port-forwarding.
 ```
 
-Replace `<IP ADDRESS>` with your computer's IP address.
-
-**Step 4**: Create ``playbook.yml``:
+**Step 5: Setting up the Ansible Playbook**
 
+Create an empty file named `playbook.yml` and paste the contents below within it.
 ```yaml
-- hosts: <IP ADDRESS>
-  roles: [openwisp.openwisp2]
-  vars:
-    postfix_myhostname: "localhost"
+- hosts: openwisp2
+  roles:
+    - ansible-openwisp2
 ```
+**Step 6: Modifying the Ubuntu Server VM**
 
-Replace `<IP ADDRESS>` with the IP address specified in Step 3.
+Ansible requires `openssh-server` and likewise, OpenWISP2 requires `python` to be installed on the **production server** so that it can pass commands to it remotely. Install `openssh-server` by running this command **on the production server**(or simply the booted up VM):
 
-**Step 5**: become root and launch ``ansible-playbook`` locally:
+`sudo apt-get install openssh-server`
 
-    sudo -s  # become root, needs sudo password
-    ansible-playbook -i hosts --connection=local playbook.yml
+`sudo apt-get install python`
 
-When the playbook is done running and you got no errors, you can login at:
+Now we're going to set up port forwarding for `3022`, the port we used earlier in the `hosts` file. To do this, do the following:
+- Open your VM `Settings`.
+- Locate the `Network` section.
+- Set `Adapter 1` as `NAT`, click on the `Advanced` option and then open `Port Forwarding` settings.
+- We're going to add **two port-forwarding rules**, one for SSH communication, and the other one for forwarding the website requests from the local machine to the our virtual machine. They are as follows:
 
-    https://localhost/admin
-    username: admin
-    password: admin
+--**Name**:SSH, **Protocol**:TCP, **Host Port**:3022, **Guest Port**:22
+
+--**Name**:HTTPS, **Protocol**:TCP, **Host Port:**:8000, **Guest Port**:443
+
+--(Leave the others blank)
+
+That's all for the VM modification.
 
-**Note**: do not use this method in a production system.
+**Step 7**: [Running the Playbook](#run-the-playbook)
+
+Everything is set up now for ansible to go ahead and do its job, that is **install OpenWISP2**. When asked for **SSH Password**, enter the password of your VM user.
+
+**Step 8: Using OpenWISP2**
+
+If your playbook finished running without any sort of error, you may now begin using OpenWISP2. To access the site being hosted by your VM, visit and log-in at:
+
+```yml
+https://localhost:8000/admin      ##8000 port being forwarded to VM's port 443
+username:admin
+password:admin
+```
 
 Enabling the network topology module
 ------------------------------------