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.

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).

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:

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:

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:

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

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

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:

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:

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 :-)

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)