Skip to content

Developer's Guide

Jump to bottom
Brian Elvesæter edited this page Jan 3, 2017 · 4 revisions

This developer's guide is intended for new developers contributing to the DataGraft Portal project. The guide covers development tools, relevant technologies and procedures for contributing your code. The guide assumes that your are using a Windows computer:

  • A Ubuntu virtual machine (VirtualBox) will be used for the run-time environment (Ruby on Rails and Docker).
  • The Windows environment will be used for development tools (text editor, Git client and text difference analyzer).

Run-time environment (VirtualBox)

The DataGraft Portal is one core component of the DataGraft Platform. The DataGraft Platform is separated into different components that are deployed as Docker containers. The DataGraft Portal thus depends on other Docker containers. The DataGraft Portal component itself is written in Ruby on Rails. We recommend to set up a Ubuntu virtual machine with Ruby on Rails and Docker using VirtualBox.

Ubuntu virtual machine on VirtualBox installation

Downloads

Download the latest release of VirtualBox and Ubuntu LTS for desktop PCs and laptops:

Install VirtualBox

Install VirtualBox on your Windows computer.

Create a Ubuntu virtual machine

Create a Ubuntu virtual machine with the following settings:

  • Name: DataGraft
  • Type: Linux
  • Version: Ubuntu (64-bit)
  • Memory size: 8192 MB
  • Hard disk: Create a virtual hard disk now
  • File size: 24,00 GB
  • Hard disk file type: VDI (VirtualBox Disk Image)
  • Storage on physical hard disk: Dynamically allocated

Start the VirtualBox machine and select the latest Ubuntu LTS Desktop image that you downloaded as start-up disk and complete the Ubuntu installation.

Install Guest Additions

To add support for mouse pointer integration, shared folders, etc. install the Guest Additions (see https://www.virtualbox.org/manual/ch04.html) to your virtual machine. The Guest Additions also fixes an issue with Ubuntu booting up in a low resolution (640x480). Follow these instructions:

  1. Boot Ubuntu in the VirtualBox, enter username/password in login window.
  2. Go to (VirtualBox) Devices – Insert Guest Additions CD image and complete the installation. See http://linuxlove.eu/virtualbox-and-ubuntu-14-04-low-resolution-640x480-fix/ for further details.

Virtual machine settings

After completing the installation instructions above, please update your settings and configure NAT for communication between your Windows computer and the Ubuntu virtual machine.

Clipboard and display settings

  • General -> Advanced -> Shared Clipboard: Bidirection
  • Display -> Video Memory: 128 MB

Port forwarding settings

  • Network -> Adapter 1 -> Advanced -> Port Forwarding

Add the following ports:

  • 3000

Shared folder settings

We assume that you clone the GitHub project to a folder location on your Windows computer. In order to be able to run the DataGraft Portal source in your Ubuntu VirtualBox you will need to set up a shared folder:

  • Shared Folders -> Add new shared folder

Configure the path to your GitHub folder on your Windows computer:

  • Name: GitHub
  • Path: [Path to the GitHub folder on your Windows computer], e.g. C:\GitHub
  • Auto-mount: Yes
  • Access: Full

The shared folder will be available in your Ubuntu VirtualBox under the folder:

  • /media/sf_GitHub/

Ruby on Rails installation

To install Ruby on Rails, please follow the rvm instructions at https://gorails.com/setup/ubuntu/14.04 and complete the sections:

  • Installing Ruby
  • Installing Rails

Skip the Git, MySQL and PostgreSQL sections. This guide assumes that Git will be used on your Windows environment. Moreover, a PostgreSQL database service will be provided as a separate Docker Container.

If you experience a Gem installation failure, the please follow the instructions at http://stackoverflow.com/questions/29317640/gem-install-rails-fails-on-ubuntu and run the following commands:

rvm requirements
sudo apt-get install build-essential bison openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libxml2-dev autoconf libc6-dev ncurses-dev automake libtool

Docker installation

Install Docker

Follow the installation instructions at https://docs.docker.com/engine/installation/linux/ubuntulinux/

Below is the list of commands to run:

sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates
sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D

sudo nano /etc/apt/sources.list.d/docker.list

sudo apt-get update
sudo apt-get purge lxc-docker
apt-cache policy docker-engine

sudo apt-get update
sudo apt-get install linux-image-extra-$(uname -r)

sudo apt-get update
sudo apt-get install docker-engine
sudo service docker start
sudo docker run hello-world

Install Docker Compose

Follow the installation instructions at https://docs.docker.com/compose/install/

Below is the list of commands to run:

sudo -i
curl -L https://github.com/docker/compose/releases/download/1.8.0-rc2/docker-compose-`uname -s`-`uname -m` > /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
exit

Create a Docker group

Run the following commands to create a Docker group.

sudo groupadd docker
sudo usermod -aG docker ubuntu

NB! You will need to restart your Ubuntu VirtualBox machine in order for these changes to take effect.

Development tools

The following developments tools are recommend for your Windows computer:

Download and install the tools listed above.

Technologies

The DataGraft Portal implementation uses the following technologies in the design and development of the new user interfaces of the portal:

  • Ruby on Rails
  • Material Design Lite (MDL) library of CSS
  • HTML or SLIM
  • JavaScript components

If you are not already familiar with Ruby on Rails we recommend you to go through the Rails for Zombies Tutorial. In case you get stuck (which you should not, well not at least until level 4 or something) you can find solutions to the tutorial exercises here.

Other useful links

Contribution procedures

Wireframes

In order to plan new features of the DataGraft Portal we use the online wireframing tool myBalsamiq. A series of detailed wireframes (including flows) are created for the DataGraft home page, file page, SPARQL endpoint page and SPARQL queries. Development of these wireframes are then planned using the GitHub repository issue tracker, where tasks and milestone releases are defined and assigned to individual members of the development team.

GitHub branches

We distinguish between three types of branches:

  • master branch: This is the production branch in which production-ready code from the development branch are integrated and made available for new creating new releases.
  • develop branch: This is the development branch where we integrate mature code from the feature branches and integration tests are performed.
  • feature branches. These are individual branches created by a team member when implementing new assigned features. Developers are responsible for writing unit tests for their features. When the feature is fully developed and merged with the develop branch, the feature branch can be deleted.
Clone this wiki locally