Vagrant: Added sample config for Vagrant::Hostsupdate; Updated README

README.md

@@ -6,17 +6,79 @@ Will bootstrap a [Ubuntu](https://ubuntu.com/) VM using [Vagrant](https://www.va
 
 To provide a lightweight experience, the VM uses [XFCE](https://xfce.org/) as a desktop environment.
 
+## Provided tools
+
+- Docker 19.03.5
+- Docker Compose 1.25.0
+- Ansible 2.9.4
+
 ## Prerequisites
 
-* Vagrant 2.2.x
-* Virtualbox 6.x
+- Vagrant 2.2.x
+- Virtualbox 6.x
+
+## Prerequisites
+
+- A server running Ubuntu or some other Debian-based distribution and working SSH access. (To try SATT in a local virtual machine, check out the Quickstart with Vagrant below)
+- Ansible on another Linux machine that will send SSH commands to the target server to provision it
 
 ## Quickstart
 
-The default user is `vagrant` with the password `vagrant` (auto-login by default).
+### Vagrant + Ansible on Windows 10 using Windows Subsystem for Linux
 
-## Provided tools
+1. [Download](https://www.virtualbox.org/wiki/Downloads) and install Virtualbox ([Documentation](https://www.virtualbox.org/wiki/End-user_documentation))
 
-* Docker 19.03.5
-* Docker Compose 1.25.0
-* Ansible 2.9.4
+2. Follow the [guide to install the Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10). This SATT guide assumes Ubuntu 18.04 LTS
+
+3. Open Ubuntu through the Windows Start Menu
+
+4. Inside the Ubuntu Terminal, continue the setup by following the next section.
+
+### Vagrant + Ansible on Linux
+
+1. Obtain Vagrant by [downloading the corresponding package](https://www.vagrantup.com/downloads.html) for your distribution, assuming Ubuntu in the next steps.
+
+2. Install the package by opening a Terminal and running:
+    
+    ```bash
+    user@vmhost: ~$ sudo dpkg install <vagrant-package-name>.deb
+    ```
+
+3. To check whether Vagrant was installed successfully, try running `vagrant --version` which must not return an error.
+
+4. Recommended: Install the [Vagrant::Hostsupdate](https://github.com/cogitatio/vagrant-hostsupdater) plugin that will automatically add the hostname of the virtual machine to the list of static hosts on your local machine (VM host). This allows you to later open e.g. `nextcloud.satt.local` in a browser from your local machine. Updates to the hosts file will require entering a sudo password:
+
+    ```bash
+    user@vmhost: ~$ vagrant plugin install vagrant-hostsupdater
+    ```
+
+    **Note for VM host Windows 10 with WSL:** This host update will currently have no effect outside of WSL, as the updated hosts file is only used within the WSL context, not Windows itself.
+
+5. Install Ansible:
+
+    ```bash
+    user@vmhost: ~$ sudo apt update && sudo apt upgrade
+    user@vmhost: ~$ sudo apt install python3 python3-pip
+    user@vmhost: ~$ pip3 install --user ansible
+    ```
+
+6. Test ansible by running `ansible --version`
+
+7. Clone the repo:
+
+    ```bash
+    user@vmhost: ~$ git clone https://git.jotbe.io/jotbe/ansible-devops-vm.git
+    ```
+
+8. Change to the local copy and try bootstrapping the VM (this will take a while and you might be asked for a sudo password):
+
+    ```bash
+    user@vmhost: ~$ cd ansible-devops-vm
+    user@vmhost: ~/ansible-devops-vm$ vagrant up
+    ```
+
+9. If everything went fine, you should be able to SSH into the machine by running `vagrant ssh` from within the same directory and services should be up and running.
+
+## Default user
+
+By default, a `vagrant` user will be provisioned (if not already available) and used throughout the provisioning. The default password is `vagrant`.

Vagrantfile

@@ -43,6 +43,15 @@ Vagrant.configure(2) do |config|
 
   config.vm.define "jbdev" do |dev|
     dev.vm.hostname = "jbdev.local"
+    
+    # If you have installed the Vagrant::Hostsupdate plugin, you can add additional domains
+    # that should be mapped to the VM.
+    #dev.hostsupdater.aliases = ["jenkins.jbdev.local", "grafana.jbdev.local"]
+
+    # An additional IP that allows you to access the VM and its services from the VM host.
+    # If you change this IP, you will have to modify the `ansible_host` in the inventory file correspondingly.
+    # More information about the various network modes:
+    # https://www.virtualbox.org/manual/ch06.html#network_nat_service
     dev.vm.network :private_network, ip: "192.168.6.65"
 
     dev.vm.provision :ansible do |ansible|