Quick Start

This page describes installation of GIS.lab development version in virtual machine using Vagrant and VirtualBox. Installation process will NOT modify anything on your host machine. Every operation is done inside of virtual machine.

BIG FAT WARNINGS:

1. GIS.lab server contains its own DHCP server. DHCP server is used in almost every local network for automatic network configuration. By default, access to GIS.lab's DHCP server is restricted only for GIS.lab client machines (by list of their MAC addresses) and it is managed by gislab-machines administrator command. It is possible to switch access policy to unrestricted, but it is required to double check that no DHCP servers conflict will occur. Otherwise, serious network breakage may be done. Please, newer change policy to unrestricted when connecting to your corporate LAN !

2. GIS.lab creates it's own network. By default it is in range 192.168.50.0/24. If this range already exists in LAN where GIS.lab is going to be deployed, it is required to change GISLAB_NETWORK configuration to some other value, otherwise IP conflicts may occur. See Configuration section for information about changing GIS.lab configuration.

Command line interface

All lines beginning with '$' (dollar) character are shell commands which must be run in command window. In most cases you can copy and paste commands from this page, but sometimes you will need to modify them little bit to suite to your conditions.

On Linux, open terminal window in Accessories > Terminal Emulator menu.

Terminology

• host machine - main machine where Vagrant, VirtualBox and GIS.lab package is installed
• GIS.lab server - GIS.lab server environment which runs as virtualized system on host machine
• client machine - machine which runs GIS.lab client system launched from LAN
• GIS.lab client - GIS.lab client environment which runs on client machine

Installation

Hardware requirements

• 4 GB RAM on host machine

Software requirements

• host machine running Linux (in our case Kubuntu 14.04 LTS)
• Git
• Ansible (in our case 1.7.2)
• VirtualBox (in our case ver. 4.3)
• Vagrant 1.6 or higher (in our case ver. 1.6.5)

Ansible installation

• add Ansible repository

$ sudo apt-get install software-properties-common
$ sudo apt-add-repository ppa:ansible/ansible
$ sudo apt-get update

• install Ansible
  $ sudo apt-get install ansible

VirtualBox installation

• add VirtualBox repository signing key
  $ wget -q http://download.virtualbox.org/virtualbox/debian/oracle_vbox.asc -O- | sudo apt-key add -
• add VirtualBox repository to system
  $ sudo sh -c 'echo "deb http://download.virtualbox.org/virtualbox/debian trusty contrib" > /etc/apt/sources.list.d/virtualbox.list'
• install Dynamic Kernel Module Support Framework
  $ sudo apt-get update && sudo apt-get install dkms
• install VirtualBox
  $ sudo apt-get install virtualbox-4.3

Vagrant installation

• remove previously downloaded Vagrant packages
  $ rm -vf ~/Downloads/vagrant_*.deb
• download Vagrant from http://www.vagrantup.com/downloads.html
• install package
  $ sudo dpkg -i ~/Downloads/vagrant_*.deb
$ sudo apt-get -f install

Vagrant Box installation

• run following command to download base operating system image (you can run this command from whatever directory)

for 32 bit host system

$ vagrant box add precise-canonical \
http://cloud-images.ubuntu.com/vagrant/precise/current/precise-server-cloudimg-i386-vagrant-disk1.box

for 64 bit host system

$ vagrant box add precise-canonical \
http://cloud-images.ubuntu.com/vagrant/precise/current/precise-server-cloudimg-amd64-vagrant-disk1.box

GIS.lab source code download

• run following command to grab GIS.lab source code

$ git clone https://github.com/imincik/gis-lab.git

Configuration

GIS.lab is designed to install and run out-of-box with default configuration. However, it is required to change default network configuration variable GISLAB_NETWORK, if GIS.lab's default network range (192.168.50.0/24) already exists in LAN, where GIS.lab is going to be deployed, to prevent IP conflicts.

We kindly invite you to briefly look at default GIS.lab configuration file, which exists in system/group_vars/all. If you have decided to adjust it to your needs, do not modify this file directly. For installation in VirtualBox, place configuration variables you want to change to system/host_vars/gislab_vagrant instead (for other deployment types consult Ansible documentation).

GIS.lab installation

GIS.lab installation takes from 30 minutes to few hours depending on your machine performance and Internet connection speed.

• run following command in source code directory

$ vagrant up

If your machine contains multiple network adapters, you will be asked to choose one. Select one corresponding to your wired network adapter (on Linux it is usually 'eth0')

User accounts

GIS.lab installation creates only superuser account (if password supplied at the beginning of installation). Let's create normal user account lab1 with password lab:

$ gislab-adduser -g User -l GIS.lab -m [email protected] -p lab lab1

Continue with Virtual client.