Nunaliit Tutorial: Installing Nunaliit

Introduction:

Nunaliit is an open source web mapping framework, designed for a Linux operating system (OS) and uses a number of open source software packages. However, this tutorial recognizes that most users are coming from a Windows OS background, and are not accustom to working with Linux.

This tutorial instructs how to install Nunaliit using a virtual machine, which is available to deploy in most OS environments, including; Windows, Mac OS or various Linux distributions. Using a virtual machine allows users to try Nunaliit without forcing them to completely abandon their OS of choice, creating a Linux partition, or needing to invest in a server to see Nunaliit’s potential as a free web mapping framework.

If you’re currently a Linux user and have Ubuntu installed on your desktop or server environment, you can skip steps 1 and 2 and start on step 3. Note: Nunaliit officially supports being run on Ubuntu, but can also work on other distributions.

Step 1 – Download Linux distribution:

Before you can install a new Linux OS as a virtual machine, you will need to download a copy of the OS. For this exercise we will download the popular distribution Ubuntu, which can be downloaded from http://www.ubuntu.com/download. Note: If you’re familiar with Linux, you may want to download the server version of Ubuntu instead of the desktop version, if you have no need for a graphical user interface for your virtual machine.

When downloading the distribution, make sure it’s in an iso file format, and is supported by your hardware (note: if the 64 bit OS is not possible in VirtualBox, then you will likely need to use the 32 bit version of Ubuntu).

Step 2 – Creating a virtual machine with VirtualBox:

With a copy of Ubuntu downloaded, you will now create a virtual machine using the popular open source software VirtualBox.

Step 2.1 – Download VirtualBox:

First you will need to download VirtualBox, a free piece of software allowing you to create virtual machines within your own OS (i.e. you can run a copy of Ubuntu within Windows, MacOS or Linux environment). Go to https://www.virtualbox.org/, to download the software required for your computer, and install it on your system.

Step 2.2 – Create a new virtual machine:

Once successfully installed, run VirtualBox and click the New button.

virtualboxscreenshot

VirtualBox Main Window – Create a new virtual machine (screenshow)

Step 2.3 – Create a new virtual machine:

Provide the name of the OS and select the correct type and version. In our case it will be;

  • Name: Ubuntu 16.04

  • Type: Linux

  • Version: Ubuntu (32bit) (Note: this may be 64 bit depending on Step 1)

newlinuxvm

VirtualBox create a new virtual machine window (screenshot)

Step 2.4 – Define the memory size available for the virtual machine:

Note: A minimum of 2048 MB should be used for Ubuntu. (Note you can change this value afterwards through the settings. If you have memory to spare, providing more than 2048 MB is recommended for improved performance of Nunaliit)

memorysize

VirtualBox define memory size window (screenshot)

Step 2.5 – Create a virtual hard disk:

Select ‘Create a virtual hard disk now’ and click Create.

virtualharddisk

VirtualBox window for creating a virtual hard disk (screenshot)

Step 2.6 – Virtual disk type:

Select the hard disk file type: ‘VirtualBox disk image’, and then click Next.

virtualdisktype

VirtualBox window – Select a hard disk file type (screenshot)

Step 2.7 – Select dynamically allocated for the disk:

dynamicorfixedsize

VirtualBox storage on physical hard disk (screenshot)

Step 2.8 – Set the file location and size:

Set the size of the virtual hard disk and the folder location. Make sure to provide enough space for the work you intended to do in the virtual environment.

filelocationandsize

VirtualBox File location and size window

Step 2.9 – Run the virtual machine:

Select the virtual machine you wish to run (if you only have one, it will automatically be selected). Under the Storage section click ‘[Optical Drive] Empty’, select the option ‘Choose disk image …‘ and then select the Ubuntu iso file you downloaded in Step 1. Lastly click the Start button. Note: If you see an error message stating, ‘FATAL: No bootable medium found! System halted.’ This likely means you need to select the iso file you downloaded in Step 1 to be booted.

runcreatedvm

VirtualBox run Ubuntu 16.04 virtual machine (screenshot)

Step 2.10 – Installing Ubuntu on the virtual machine:

After a couple minutes, an Ubuntu install window should pop up. Next, click the Install Ubuntu button.

installubuntu

Ubuntu installation welcome window (screenshot)

Check both boxes on the preparing to install Ubuntu screen and click the Continue button

preparingtoinstallubuntu

Ubuntu preparation to install window (screenshot)

Select the option Erase disk and install Ubuntu, and then click the Install Now button.

installationtype

Ubuntu installation type window (screenshot)

You will then be asked to confirm you want to write these changes to disk, and you will need to click Continue.

writechangestodisk

Ubuntu confirmation to write changes to disk (screenshot)

Define where you are in the world (this will set your timezone/clock on the desktop) and then click Continue.

whereareyou

Ubuntu Installation window – Selection your location (screenshot)

Define the keyboard layout, and click the Continue button.

definekeyboardlayout

Ubuntu keyboard layout selection window (screenshot)

Provide your user information for your user account in Ubuntu, and then click Continue. Make sure to remember your username and password (you will need these to log into the system after your installation and for downloading/installing new software).

whoareyou

Ubuntu installation window for creating a new account (screenshot)

When the installation is complete it will prompt you to restart your virtual machine. Click Restart Now.

restartnow

Ubuntu installation complete window (screenshot)

Note: If the machine doesn’t restart automatically go to machine -> reset, or you can try closing the window and selecting the option ‘power off machine‘ if the virtual machine is unable to restart and then run it again.

Your virtual machine should now be up and running.

Step 3 – Installing Nunaliit prerequisites:

Now that Ubuntu is installed on your virtual machine and you have logged in with your Ubuntu username and password. Open the program called terminal (you can find it by clicking the window’s key or clover leaf key and type terminal into the search window)

Step 3.1 – Get the latest updates and upgrade software:

In the terminal, type the following commands:

sudo apt-get update

‘sudo apt-get update’ retrieves the latest list of software available via apt-get (Note: You will be prompted for your password when you type sudo for the first time. This is the same password as the one provided for your user account).

sudo apt-get upgrade

‘sudo apt-get upgrade’ downloads the latest software for your system. Next type Y to install the latest software updates.

Step 3.2 – Install Java on your system:
sudo apt-get install -y openjdk-8-jre-headless

Step 3.3 – Install Couchdb:
sudo apt-get install -y couchdb

Step 3.4 – Install FFMpeg:
sudo apt-get install -y ffmpeg libav-tools ubuntu-restricted-extras libavcodec-extra

Step 3.5 – Install ImageMagick:
sudo apt-get install -y imagemagick

Step 4 – Download the Nunaliit software development kit:

Nunaliit can be downloaed from the following website.

Pick the latest release (2.2.6 at the time of this instruction) and download the Nunaliit development kit (SDK) tar ball (e.g. http://central.maven.org/maven2/ca/carleton/gcrc/nunaliit2-couch-sdk/2.2.6/nunaliit2-couch-sdk-2.2.6-nunaliit.tar.gz). Note: v. 2.2.7 is now released.

Next you will need to uncompress/extract the tar-ball’s files. You can either double click the file and uncompress/extract it to the desired directory using the graphical user interface, or you can uncompress/extract the files through the terminal (see command below).

tar –xzvf nunallit2-couch-sdk-2.2.6-nunaliit.tar.gz

Step 5 – Change CouchDB Admin Password:

Before you can run an atlas you will first need to add an admin account in CouchDB. Start by opening a browser by going to the following url: http://127.0.0.1:5984/_utils (CouchDB’s futon page). Note: If CouchDB is installed by not running, you may need to start the service from the terminal, see this post for instructions.

Click on the link ‘Fix this’, located at the bottom right-hand corner. Then in the create server admin window, add an admin password by typing admin into the username text field and then a password into the password field (Note: make sure to write this password down, you will need it to run Nunaliit).

changecouchdbpassword

CouchDB Futon – Creating a server admin (screenshot)

Step 6 – Create a new Nunaliit Atlas:

You can create a new Nunaliit atlas using the following command in terminal. Note: make sure your current directory contains the extracted SDK sub-directory from the tar-ball:

./nunaliit2-couch-sdk-2.2.6/bin/nunaliit create

Provide the information for configuring a new atlas.

  • Enter the name/location where the atlas will be created (keep the name lowercase and without spaces or special characters)

  • Note: many of the fields used for creating an atlas have default values (shown in [ ]), to accept these values simply hit enter/return.

  • Update the admin password to the new CouchDB admin password provided in Step 5.

  • See the screenshot of the create atlas configuration questions below;

createanewatlas_config

Creating a new atlas (called testatlas) with Nunallit (screenshot)

Step 7 – Update and Run a Nunaliit Atlas:

Once the atlas has been created, it will need to be updated first and then run. Start by changing the directory to the new atlas sub-directory, and then run the atlas update command as follows (Note: you may need to update the command below, if your copy of Nunaliit is located elsewhere):

../nunaliit2-couch-sdk-2.2.6/bin/nunaliit update

and then type the following to run the atlas:

../nunaliit2-couch-sdk-2.2.6/bin/nunaliit run

To see your atlas up and running go to the URL http://127.0.0.1:8080 (Note: replace the port 8080 with the port you provided in the initial create procedure if it’s different).

newnunaliitschema

New Nunaliit atlas shown in a browser. (Screenshot)

Step 8 – Stop a running atlas:

To stop the running atlas, type CTRL+C in the terminal

Advertisements

Quick tip: searching your shell history

My boss recently shared a great tip for performing a reverse search of your shell history. The next time you’re trying to remember a command you recently typed in terminal. Try the key stroke combination of Ctrl + r.

Typing Ctrl + r in your terminal will prompt you for a search string, and the first result it matches in your history will be returned. If the match is not correct, you can add more characters to make the search more specific, or type Ctrl + r again, and the next valid match will be displayed.

Note: The filtered search results may include the string in any portion of a history log entry, and are not limited to the beginning characters of each log entry. This also means that if multiple matches exists in a single log entry, Ctrl + r will move the search cursor to the next match in the same entry.

Search and Replace in vi

I frequently edit documents in vi and one task that’s often required is searching and replacing text. To search and replace text, you can use the substitute command :s, which follows the pattern :[range]s/{search-string}/{replacement-string}/[flags].

Example of range values:

  • % – indicates the search should occur with all lines
  • 4 – indicates the search should occur on line 4
  • 2,8 – indicates the search will occur from line 2 to line 8

Examples of flag values:

  • g – make the replacement if the text is found for all instances
  • c – ask for confirmation of a change
  • i – not case sensitive
  • I – case sensitive
  • e – don’t report error messages if no match is found

Usage examples:

Find and replace

:s/StringToFind/Replacement/

Find and replace all instances on the current line

:s/StringToFind/Replacement/g

Find and replace all instances from line 5 to line 7 upon confirmation

:5,7s/StringToFind/Replacement/gc

Find and replace with case sensitivity throughout the entire document

:%s/StringToFind/Replacement/gI

To learn more about the substitute command, open vi and type :help :s

Checking available and used disk space

Two useful terminal commands for checking disk usage in Linux, are the commands df and du.

The first command, df, provides a table of file systems with information on free and used disk space. Note: Using the -h option provides the table in a human readable format.

df -h

The second command, du, can also retrieve disk usage information. Typing du into any directory will provide a list of files and directories at the specified location with their corresponding disk usage. However du may be more useful with the options -s and -h providing a human readable summary of the specified location on disk.

eg. display disk usage for the current working directory

du -hs

or at a specified directory

du -hs directoryname

How to create symbolic links

Occasionally you will need to make a link to a file or directory in Linux. To create a symbolic link you will need to use the ln command, which will follow the form of;

ln -s <target> <link name>

Example: Assume you frequently use gnome-calculator and decide you want a link on your desktop so you can quickly start that application in the future. To accomplish this with a symbolic link you could do the following;

ln -s /usr/bin/gnome-calculator ~/Desktop/calculator

You can also update an old symbolic link by overwriting the link using the following command.

ln -sf /usr/bin/gnome-calculator ~/Desktop/calculator

or when linking to directories you will need to include an n option

ln -sfn /mydir/ linkname

Help in vi

Vi is a great text editor but requires practice to learn its many commands. To aid this process vi provides a great command called help. User’s can access an overview of the help command, by typing the following;

:help

For a listing of common commands used by vi, type;

:help quickref

For help with a specific command you can also type :help <command>. For example, to see the help for the insert command you would type;

:help i