1. How to start

1.1. Installation of requirements

Git installation

By far the easiest way of getting Git installed and ready to use is by using default repositories. This is the fastest method, but the version may be older than the newest version. For GIS.lab version from official repositories should be normally sufficient.

The instructions below are valid for Debian/Ubuntu operating systems. At first, apt package management tools can be used to update local package index. Afterwards, Git can be downloaded and installed.

$ sudo apt install git

GIS.lab source code download

Following command will grab the most recent GIS.lab source code to user system.

$ git clone https://github.com/gislab-npo/gislab.git
$ git checkout version-0.8

Note

Git is not necessary but it is recommended. One can get GIS.lab source code also by downloading latest GIS.lab package from https://github.com/gislab-npo/gislab.git and unpacking it in working directory.

For production environment it’s recommended to grab recent stable version (source code) directly from GitHub.

Ansible installation

Ansible is an automation engine used by GIS.lab for fully automatized provisioning. Its installation can be performed by typing ordinary commands.

$ sudo apt install ansible

Attention

Since version 0.8 GIS.lab requires Ansible version >= 2.4.

Tip

Most recent version of Ansible software can be also installed also by PIP.

$ sudo pip install ansible

Or alternatively custom PPA can be used.

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

VirtualBox installation

Install Dynamic Kernel Module Support Framework and VirtualBox packages. These packages are needed only for installation in Virtual Mode.

$ sudo apt install dkms virtualbox virtualbox-qt

Vagrant installation

Installing vagrant package from default repositories should be normally sufficient. The latest version can be downloaded from vagrantup.com. Vagrant is required only for installation in Virtual Mode.

$ sudo apt install vagrant

Also Vagrant disksize plugin is required and must be installed.

$ vagrant plugin install vagrant-disksize

Tip

If plugin installation fails, try to install more recent version of Vagrant.

1.2. Configuration

It is recommended to set at least some basic configuration before GIS.lab installation is performed.

GIS.lab is designed to install and run out of box with default configuration. However, it is required to change at least default network configuration variable GISLAB_NETWORK, if GIS.lab’s default network range 192.168.50.0/24 already exists in LAN to prevent IP conflicts.

Default GIS.lab configuration file named all exists in system/group_vars directory located in GIS.lab source code, see Fig. 1.1. When user decides to adjust it, this file should not be modified directly. Instead a custom configuration file in system/host_vars directory should be created.

Tip

Find the system/group_vars/all file in GIS.lab source code tree and see its content to become acquainted with all possibilities of configuration settings. It is full of commented out information.

For installation in Virtual mode it is recommended to create file named gislab_vagrant in system/host_vars directory for host specific GIS.lab configuration and put various changes there.

When Physical mode is used, file in system/host_vars directory should be named according to name of GIS.lab unit. This name is a part of Ansible inventory file content, script that Ansible uses to determine what to provide. All file names must always match unique host name specified in inventory file.

Fig. 1.1 File layout related to configuration.

File gislab_vagrant will be loaded automatically by Vagrant without need to manually create the Ansible inventory file.

Tip

See practical example of configuration file.

See also

Network configuration