Setting up a virtual machine

This page is a tutorial which explains how to build and configure a new virtual machine for running Gazelle tools.

Vagrant

The easiest way to create a new virtual machine is to use Vagrant.

Vagrant is a tool for building complete development environments. With an easy-to-use workflow and focus on automation, Vagrant lowers development environment setup time, increases development/production parity, and makes the "works on my machine" excuse a relic of the past.

First of all, you need to install vagrant on the machine which will host the virtual machine. For instance, if you are running Linux execute the command below, or browse the download repository of vagrant at http://downloads.vagrantup.com

  sudo apt-get install vagrant

Set up

Vagrant uses the concept of "boxes" which will allow you to easily and fastly get a running machine with the OS of your choice. You will find a lot of boxes on Vagrantboxes website for instance.

On ovh3 sever, we have installed Vagrant and creating a directory names /home/gazelle/virtual_machines. All the files created by Vagrant to configure the virtual machines will be stored there. For each virtual machine, we will create a new folder. For instance /home/gazelle/virtual_machines/XX for the virtual machine to provide to XX Healthcare.

Open your terminal and go to this folder (/home/gazelle/virtual_machines/XX in your example. Then execute:

vagrant box add gazelle-xx https://dl.dropboxusercontent.com/u/547671/thinkstack-raring64.box

Here we are creating a virtual machine named "gazelle-xx" running the latest version of Ubuntu server (13.04)

Then you need to initialize the virtual machine by running the command below. You will get a message saying that the Vagrantfile file has been created in your current directory.

vagrant init gazelle-xx

if you' d like to import an existing box into a vagrant folder you need to execute the 2 commands:

vagrant box add gazelle-xx gazelle-xx.box
vagran init gazelle-xx

Configure

Once the Vagrantfile file is created, edit it with your favorite text editor to update the properties of the virtual machine: networking, memory ...

Obviously, you may want to increase the memory and the number of CPUs allocated to your virtual machine; in Vagrantfile, search for the line "config.vm.provider :virtualbox do |vb|" and uncomment it. Then, look for the next occurrence of "end" and uncomment the line too.

You will then have to uncomment and modify the lines starting with vb.customize. You can line as many statements as you want. The list of general settings is available here. Keep in mind that --memory is used to allocate a certain amount of memory to the virtual machines and --cpus is used to allocate a certain number of CPUs to your virtual machine. Find below an example of configuration

 config.vm.provider :virtualbox do |vb|
  #   # Don't boot with headless mode
  #   vb.gui = true
  #
  # Use VBoxManage to customize the VM. For example to change memory:
     vb.customize ["modifyvm", :id, "--memory", "8192"]
     vb.customize ["modifyvm", :id, "--cpus", "4"]
  end

Start the VM

To start the virtual machine, open a terminal in the folder containing the Vagrantfile file and execute

 vagrant up

Access the VM

The first time you access the virtual machine, only the vagrant user exists. You can log on the machine using SSH with the command (still executed from your Vagrant folder)

 vagrant ssh

Install Jboss, postgreSQL ...

Logged on the virtual machine as vagrant user, download the installation script available here and run it as root. This will install Jboss5, postgreSQL 9 and install TestManagement application (you can then remove this tool if you do not need it).

Create user gazelle

If you rather want to use the gazelle user instead of vagrant, you can create an account for the gazelle user, execute the following commands to do so

sudo useradd --home /home/gazelle gazelle
sudo adduser gazelle sudo # it will add gazelle to the list of sudoers
sudo adduser gazelle jboss-admin # it will add gazelle to the jboss-admin group

Tips

copy

Copy a file from the host to the virtual machine (if you are using NAT)

 scp -P 2222 vagrant@localhost:/tmp

Default password for user vagrant is vagrant

Shared folder

Vagrant automatically mounts a shared folder. Everything you put on the host in the folder where the Vagrantfile is stored will be available on the virtual machine at /vagrant.

configure timezone

You may want to change the timezone of the virtual machine in order to match the time zone of the users, use the following command:

 sudo dpkg-reconfigure tzdata

change hostname

To change the hostname of the virtual machine, you will have to edit to files: /etc/hostname and /etc/hosts. The first one will only contain the hostname of the virtual machine and, in the second one, you should tell the machine that 127.0.0.1 is your hostname. The /etc/hosts file should look something like:

127.0.0.1       localhost
127.0.1.1       gazelle-vm

Then, run the following two commands

sudo service hostname restart
sudo service networking restart

To check that the changes have been taken into account you can log out from the virtual machine and logged on again. If your prompt display the name of the machine, it may have change to the new one.

configure an Apache server

It would be more convenient for the final users of the virtual machine to have a unique page they can start from. We usually install apache2 and create a fancy index.html page for welcoming users and giving them the pointers to the tools installed on the virtual machine.

Install apache2
```
 sudo apt-get install apache2 
```
If you want to configure redirections, edit /etc/apache2/sites-enabled/000-default
Restart apache2
```
 sudo service apache2 restart 
```
If you get an error saying: "Invalid command 'ProxyPass', perhaps misspelled or defined by a module not included in the server configuration", you may need to enable the proxy module, proceed as follows
```
 sudo a2enmod proxy*
```

Attached is a pattern for the index.html page; you will also need to download the following css files and images

Bootstrap theme: http://gazelle.ihe.net/css/bootstrap_3/bootstrap.min.css

Favicon:

Gazelle icon: http://gazelle.ihe.net/files/gazelle-2013-medium_0.png

Enable ProxyPreserveHost

The apache proxy changes the host header in the request to the proxy pass value.

Just set the ProxyPreserveHost variable to on, in a VirtualHost to fix the issue.

Example:

<VirtualHost gazelle.ihe-europe.net:80> 
  ServerName gazelle.ihe-europe.net 

  ProxyPreserveHost on 

  <Location /> 
    ProxyPass http://localhost:10080/ 
    ProxyPassReverse http://localhost:10080/ 
  </Location> 
   
</VirtualHost>

Script for database backup

We usually configure a cron to backup the databases once a day. A sample script is attached at the bottom of the page, remove the lines relative to the database you haven't created and add the instructions to backup the missing ones.

The pg_dump command uses gazelle username; you must ensure that postgreSQL is correctly configured, that means that the gazelle user is trusted. Otherwise, you will either be rejected (authentication failure) either ask to provide a password for each dump. Check /etc/postgresql/9.1/main/pg_hba.conf, you must see the following lines, if not, complete the file and restart your postgresql server (sudo service postgresql restart). You also need to ask postgreSQL to listen on all interfaces (not only loopback); edit /etc/postgresql/9.1/main/postgresql.conf file and uncomment the line listen_address = 'localhost' and replace localhost by '*'. Restart of postgresql is required.

# Database administrative login by Unix domain socket
local   all             postgres                                peer
local   all             gazelle                                 trust

Note also that the script copies the backups in a file named /opt/backupdb and stores the logs in /var/log/backupdb, as a consequence, make sure that the user running the script has the rights to write there.

Configure a cron

Edit the crontab of the gazelle user to configure a cron which will run the backup script daily

crontab -e

Then add the following line to the file (it will run the script daily at midnight) and save it

0 0 * * * /home/gazelle/scripts/backup.sh

Export the appliance

Vagrant allows you to package your virtual machines (vagrant package) but it will output a .box file which can be imported only using Vagrant.

vagrant package --output gazelle-tools.box --vagrantfile Vagrantfile

If you rather want to distribute the virtual machine in a standard format, you may choose to create an OVA (Open Virtual Appliance) or OVF (Open Virtual File) file. If you do not have access to the graphical user interface of Virtualbox, you can use the VBoxManage command line utility. First, list the virtual machines available on your system

 VBoxManage list vms

Then, copy the name of the VM you want to package and export the appliance (you can use either ovf or ova extension) with the following command

 VBoxManage export your_vm_name -o exported_vm.ova

This file can then be distributed and imported in a virtualizer.

Import a vagrant box

To use your virtual box in another system, you can package your box (see above section) and installed it in a new system. Below are the instructions to proceed:

Install Vagrant on the hosting system, create a folder where to store the various Vagrantfile files and for each new virtual machine, create a new sub-folder.
Copy your .box package in the new subfolder and run
```
vagrant box add gazelle-tools gazelle-tools.box
```
then run
```
vagrant init gazelle-tools
```
Finally, start your virtual machine by running
```
vagrant up
```

If you get such a message at start up : "The guest additions on this VM do not match the installed version of VirtualBox", refer to the following blog https://github.com/dotless-de/vagrant-vbguest, it should solve the issue

If you encounter some issues with the network configuration of the virtual machine (eg. an interface is missing), ssh to the virtual machine and delete file /etc/udev/rules.d/70-persistent-net.rules. Logout from the virtual machine and run vagrant reload.