README.md

# isochrone-vm
This repository contains the isochrone backend system.
It is supported by vagrant (http://www.vagrantup.com) and uses virtualbox to
provide a virtual machine containing a database filled with some test data.

## Preparations
In order to work with isochrone-vm the host system has to install two
dependencies:
 - vagrant
 - virtualbox

### Installing vagrant
Vagrant can be installed by downloading the installation package (for your
operating system) from http://vagrantup.com.

In addition to the vagrant's core system, three additional vagrant plugins have
to be installed on the system. Although this is not a dependency of the
isochrone-vm system itself, it is a mandatory step. This has been implemented
since it solves some of the most common problems that occurred with the vagrant
system when used with isochrone-vm.

The first vagrant plugin that has to be installed is **vagrant-cachier**. After
activating this plugin it will cache some packages that have to be downloaded
from the internet (f.e. the postgresql rpm package). Install the plugin by
executing the following code snippet on your host system. Be sure to do that
using **the user that will start the isochrone-vm** afterwards. Note that this
should not be the root user.
```shell
vagrant plugin install vagrant-cachier
```

The second vagrant plugin needed by isochrone-vm is **vagrant-vbguest**. This
plugin will check on startup of the virtualized machine if the virtual guest
additions (provided by oracle) match the host's virtualbox version to deliver
best performance. Type the following to install this vagrant plugin (as above -
use the user which will start the isochrone-vm afterwards).
```shell
vagrant plugin install vagrant-vbguest
```

The third (and last) vagrant plugin needed by isochrone-vm is **vagrant-triggers**.
This plugin will delete temporary folder when destroying the virtual machine, so
that no temporary files remain on the host system:
```shell
vagrant plugin install vagrant-triggers
```

### Installing virtualbox
Virtualbox can be downloaded from the oracle homepage using the URL
http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html

Be sure to install the version matching your host system regarding architecture
and operating system. Also install the **Oracle VM VirtualBox Extension Pack**

Since isochrone-vm utilizes a 64bit client OS it is important to check for two
things:
 - You'll need a 64bit CPU that supports VT-x/AMD-V hardware acceleration.
   If you are either using a 32bit CPU or a CPU which does not support VT-x or
   AMD-V isochrone-vm can not be used.
 - You need to check that VT-x/AMD-V is enabled in your BIOS settings. For some
   reason this is not the default setting for most systems, so be sure to check
   your settings and to enable VT-x/AMD-V.

## Working with isochrone-vm
Using isochrone-vm is pretty easy. All you have to do (after your system has
been prepared as described in the section "Preparations") is to clone this git
repository and to use vagrant afterwards.

This will download a shell script used for system preparation (called
bootstrap.sh) along with a Vagrantfile describing the virtualized system (which
operating system is used, how much RAM, how many CPU cores, ...). In addition
this repository also contains the gradle wrapper and a gradle build script.
Gradle can be used to control vagrant, but since in most of the cases it is a
better idea to use vagrant directly, this won't be described in detail here.

### Starting the first time
Before starting the first time, double check that at your host these three
ports are available:
 - 5432 (postgresql)
 - 8000 (apache httpd; used for phpPgAdmin)
 - 8080 (for the webfrontends; only for server mode)
If one of them is already occupied by something then everything will use some
other port and will only print a warning (but will still start without an
error).

Starting isochrone-vm the first time is done using vagrant. The first time will
take quite some time (depending on your hardware and your connection speed to 
the internet). This is caused by a process called provisioning, which will be
performed only on very first startup (or after calling `vagrant destroy`)
that handles system configuration and software installation. For me it takes
about half an hour (with a powerful Lenovo T440s from 2014 and with a huge
bandwith at university), so be sure to grab some coffee :-)

Their are two different modes that come with isochrone-vm:
 - local mode
 - server mode

#### Local mode startup
The local mode is the "smaller" version of the two different modes. It has been
implemented for development purpose and as a result of that it only hosts some
test data and a database needed when working with isochrones.

What actually happens at first startup in local mode is the following:
 - Grabbing a virtual machine from the internet (the so called vagrant base box)
 - Installing some additional repositories for the system (postgresql repo, ...)
 - Deactivating SELinux and the guest firewall (for ease of use)
   So be sure to handle security issues elsewhere!
 - Installing apache's httpd server
 - Installing an oracle jdk that supports at least java 8
 - Installing postgresql
 - Installing the postgis extension into postgresql
 - Installing phpPgAdmin
 - Downloading test data and importing it into a newly created database table
 - Starting the database and phpPgAdmin

After all this has been done one can connect to the postgresql database using
port 5432 and localhost. The reason why "localhost" is used, is simply that the
virtual machine works with port forwarding. In addition to that phpPgAdmin is
usable under the URL "http://localhost:8000/phpPgAdmin". For login information,
for postgresql and for phpPgAdmin check the credentials set in the Vagrantfile.

The **default credentials** are:
 - username = niko
 - secret = secretPhdPassword#2014! (as it is printed here -> very secret :-))

To start the virtual machine in local mode type the following:
```shell
vagrant up
```

To really do something with the data provided by the isochrone-vm and it's
database be sure to check for either the isochrone-web or the isochrone
project (or maybe - depending on your needs - even both of them) and the
documentation there.

#### Server mode startup
The server mode basically does all the things that are done in local mode. In
addition to this mode the following things are also done:
 - Installation of apache's servlet container "tomcat"
 - Downloading of the latest stable version of isochrone-web
 - Downloading of the latest unstable version of isochrone-web
 - Deploying the stable version under http://localhost:8080/isochrone/
 - Deploying the unstable version under http://localhost:8080/testing/
 - Starting tomcat

As a result this can be used as a test-system (for example by a CI-server)
very easily. In most of the cases this is also a great mode for a (live-)demo.

To start the virtual machine in server mode type the following:
```shell
TOMCAT_INIT="true" vagrant up
```

#### Various settings
Besides the two modes mentioned above their are much more options to configure.
However, they haven't aren't supported officially, so they are not described
here. Just one more information: Their are some global variables in the
provisioning script "bootsrap.sh" (which is located in the repository root).
And of course this script can also be extended to your needs. 

If something has to be adjusted it can also be done directly in the virtualized
machine. You can use
```shell
vagrant ssh
```
to access the guest system. Please not that changes in this system should be
added to the bootstrap.sh file, since otherwise they are lost if the system is
used on another host or after destroying the client using "vagrant destroy".

#### Stopping the machine
After your work is finished the virtualbox can be stopped using two different
ways. If disk space is rare on your system i'd suggest that you use
```shell
vagrant halt
```
This completely shuts down the isochrone-vm backend system. In fact this is
very similar to just press the power button on a physical machine. However,
this comes with the cost that on calling `vagrant up` the next time, it can
take some time (much less than on first vagrant up, since no more installations
have to be performed... only services need to be started after the fist
startup).

If disk space is not that much of a problem for you an even better option is to
call vagrant with the following option: 
```shell
vagrant suspend
```
This will save the virtual machine and it's state (RAM) on your hard-drive. This
leads to a faster startup time, but - as already said - need a bit more disk
space.

A last note on stopping the isochrone-vm. Be sure to shutdown the test backend
correctly by calling one of the commands above. Although it should not lead to
big problems when just shutting down the host machine, it is not guaranteed to
work (I never had problems with it so far, but who knows?).

#### Starting the machine (the next workday :-))
After stopping your machine for some reason (because you left work), all that
has to be done to use is again is to call `vagrant up` again by typing:
```shell
vagrant up (or TOMCAT_INIT="true" vagrant up)
```

The great thing about this vagrant is that it won't do provisioning again and
as a result is much faster (less than 1min for my system)

#### Something went south? - what to do
If something didn't work out as expected or if you messed things up yourself
then things can be easily fixed.
Just destroy your backend by typing the following (don't be afraid :-)
```shell
vagrant destroy
```
This will delete your virtual machine and it's state. The good news is that you
can get back to work after starting the virtual machine again as it was done
the first time (see section "Starting the first time" for this... and grab some
coffee to wait while the system is provisioning)