:doctype: article
:blank: pass:[ +]

:sectnums!:

= SEIS 665 Week 3 Project: Virtualization
Jason Baker <bake2352@stthomas.edu>
1.0, 2/10/2018

== Overview
Setup a virtualization environment on your local workstation and build a basic web server using Vagrant.

== Requirements

  * Install VirtualBox software on your workstation:
    - https://www.virtualbox.org/
    - Note: If you already have VirtualBox on your system, make sure it is up to date.
  * Install Vagrant software on your workstation:
    - https://www.vagrantup.com/

[WARNING]
====
VirtualBox will not run on a UST lab workstation. It must be installed on a personal PC or Mac system. If you do not have a personal laptop, partner with someone else in the class who does.
====

[NOTE]
====
If you are using a Windows workstation, you may need to run Powershell as the Administrator while exercising Vagrant commands.
====

[NOTE]
====
Some laptops (typically Windows machines) have virtualization extensions disabled in their BIOS which prevents VirtualBox from running properly. You will see an error message like `VT-x is not available` when trying to launch a VM. The solution is to access your laptop's BIOS settings and enable virtualization support.
====

== The project

Let's get started!

=== Create git repository

Create a git repository (`git init`) in a local directory on your workstation. You can select whatever name and location for the directory you like.


=== Create a Vagrantfile

You can create a Vagrantfile in the directory using the `vagrant init` command. After running this command, you will see a file named `Vagrantfile` in your directory. This text file contains code which defines how to build a virtual machine. The code is based on the Ruby programming language.

Your goal in this project is to modify the Vagrantfile to create a virtual machine running Alpine Linux and an Nginx web server. Here are some hints to get you started:

  * Vagrant allows you to launch VMs from a "box". This is basically a pre-configured virtual machine template which has already been tested with Vagrant. You should use the box `generic/alpine36` for this project.
    ** Check out the `config.vm.box` setting to see how to configure a box in the Vagrantfile: https://www.vagrantup.com/docs/vagrantfile/machine_settings.html
  * The default Vagrantfile configuration sets up a VM with a limited network connection between the guest OS and host OS. We want to setup a web server on the VM and be able to access that server from a web browser on our host. Setup network port forwarding to forward port 80 running in the guest OS to port 8081 running on the host OS. You can find documentation on how to setup this network forwarding in the Vagrantfile here:
    ** https://www.vagrantup.com/docs/networking/basic_usage.html
  * The base Alpine Linux box does not come with Nginx software installed, so you should modify the Vagrantfile to install it. One of the easiest ways to do that is to add a shell provisioner (https://www.vagrantup.com/docs/provisioning/shell.html).
    ** Alpine Linux uses the `apk` package management tool which is similar to `yum`. A couple of the other commands on Alpine are also slightly different than those on Amazon Linux. Here are the shell commands that Vagrant will need to run on the VM to install and start an Nginx server:
    *** apk add --upgrade apk-tools@edge
    *** apk update
    *** apk add nginx
    *** rc-service nginx start

=== Test your work

Once your VM is running, you should be able to open up a web browser on your workstation and browse to the site: http://localhost:8081

The nginx webserver will respond with a 404 error message if it was setup properly. Why is it displaying a 404 error message? Because that's its default configuration -- don't display any webpages. Let's go ahead and fix that.

First, log into the VM from the command line by running the command: `vagrant ssh`. This will automatically setup an ssh connection to the VM and log you in as the `vagrant` user. The vagrant user is able to become root on the Linux server.

Next, change to the `/etc/nginx/conf.d` directory and modify the text file `default.conf`. Note, this base installation of Alpine Linux only has the `vi` editor installed. If you would like to use the `nano` editor, you should run this command to install it first: `apk add nano`

Modify the `default.conf` text file by commenting out the following line with a hash character (`#`):

  # return 404;

Next, you need to restart the nginx web server so that it can read the next configuration change. Restart the server by running the following command: `rc-service nginx restart`

Finally, go back to the web browser on your desktop and try to access the web server again on port 8081 (you may need to refresh your browser). You should see a `Welcome to nginx!` website.

Congratulations! You have automated the installation of an Nginx web server on a virtual machine using Vagrant.

=== Extra super fun task (optional)

Automate the configuration of Nginx in the Vagrantfile so that a person does not need to perform the manual steps above to view the `Welcome to nginx!` website.

=== Commit your work

Add and commit your Vagrantfile to your local git repository. You are not required to push this repository up to GitHub, but you are welcome to create a repository in your personal GitHub account and push this repo to GitHub for practice.

=== Show me your work

Please show me your Vagrantfile once your Vagrant web server is successfully running.

=== Terminate server

You can terminate your virtual machine by running this command in the same directory as your Vagrantfile: `vagrant destroy`.
