Software Prerequisites

Besides the eRAMS environment itself, you’ll need to download a couple tools that will enable you to run eRAMS as a virtual machine from your computer:

• VirtualBox
  • Download a copy of the eRAMS VirtualBox virtual machine image.  Import the downloaded file into VirtualBox.
• Vagrant
• Mercurial
• SSH client such as Cygwin or Putty if using Windows

Configure Virtual Machine

Shared Folders

A predefined set of shared folders is already preconfigured with the provided VM image, but this likely doesn’t match your local environment.

From the VirtualBox menu, select the new virtual machine and click “Settings.” Select the “Shared Folders” tab. Remove any existing shared folders, and ensure that at least one folder, the folder pointing to where you will download your copy of the eRAMS code repository, exists.  Give full access to this shared folder.

Source Code Repository

Once you’ve configured your shared folder, you’ll need to download the eRAMS source code repository into your ROOT folder.  Contact us to get access to the source code repository. Once access is granted, download Mercurial for your operating system and clone the eRAMS repository into the ROOT directory:

hg clone https://alm.engr.colostate.edu/cb/hg/erams /path/to/ROOT

Vagrant

Vagrant is a simple tool we use to help manage development environments we share with other developers, and we use it ourselves too.  Install Vagrant and then copy the eRAMS Vagrantfile from ROOT/provisioning/roles/webserver/templates/Vagrantfile to ROOT.

Associate the VM with Vagrant

Before you are able to run your virtual machine, you will need to associate the VirtualBox image that you downloaded earlier with Vagrant.

1. Use the VirtualBox command-line API to list existing VirtualBox VMs (here’s an example with Windows: VBoxManage list vms )
   1. If the VBoxManage command doesn’t exist, you’ll need to add C:\Program Files\Oracle\VirtualBox to your PATH, open a new command prompt, and then try again.
2. Copy the id of the VM titled “eRAMS.com – Development Server” and paste this into the file ROOT/.vagrant/machines/default/virtualbox/id.

Start the VM

Open a terminal or command prompt.  Change your working directory to ROOT and then run `vagrant up` to start your virtual machine.

Note: the name of the virtual machine displayed in VirtualBox must match the name configured in your Vagrantfile.  If this is not the case, vagrant will start a different base box than the one that we downloaded in the previous step.

Note: if an SSH connection cannot be made, check to make sure that your local SSH client is installed and that the “ssh” command exists in the PATH.

Note: if vagrant cannot find the base box associated with the Vagrantfile, you may need to download the box manually from VagrantCloud or this list of VMs.

Access the VM

Once the virtual machine is booted, you can access the machine by typing `vagrant ssh` from the command line.

Note: this command will need to be run from within ROOT.

Note: from now on most of the steps will be completed from within the guest VM.

Configuration Files

In addition to the source code, there’s a list of configuration files that will need to be configured for your eRAMS installation:

• Main Settings: ROOT/django/eRAMS/settings.py
• More Settings: ROOT/django/eRAMS/serve/config.py
• Client-side (Javascript) settings: ROOT/media_erams/map/js/eRAMSdefs.js

It is also good to know a few additional locations where your client and server side code resides:

• Static Content: All your static content (javascript, CSS, images) will be contained in ROOT/media_erams/.
• Server-Side: All the server-side (python) code is contained in ROOT/django/eRAMS/

Download your development configuration settings (Contact us to request access to all configuration files).  Change the permissions of all configuration files to be readable and executable by the web server user and then copy each file to their respective location listed above.

Additionally, you’ll need to create a local eRAMS log directory using the following script: mkdir ROOT/log && touch ROOT/log/error.log && touch ROOT/log/celery.log && chmod -R 777 ROOT/log/

Development Files

In addition to configuration files, there are a number of GIS files and other user data that is necessary for some of the GIS/Analysis functionality within eRAMS. Download and install a copy of base development files:

cd /tmp/ && wget https://s3.amazonaws.com/erams-downloads/dev.files.zip /tmp/

unzip dev.files.zip

sudo chown -R www-data:www-data var/ && sudo chown -R www-data:www-data /var/erams

sudo mv var/erams/* /var/erams/

Development Database

The virtual machine should have a preconfigured database already installed for you. If it doesn’t, download a preconfigured development database to be used with eRAMS with the following commands:

cd /tmp/ && wget https://s3.amazonaws.com/erams-downloads/dev.sql.bz2

sudo -u postgres psql -c ‘CREATE DATABASE erams’

sudo -u postgres psql -c “CREATE USER {{ database.user }} WITH ENCRYPTED PASSWORD ‘{{ database.password }}’

sudo -u postgres psql -d erams -f dev.sql

psql -c “ALTER DATABASE erams OWNER TO {{ database.user }}”

Note: database.user and database.password should match the database and user specified in the ‘DATABASE’ section of your settings.py file

Build

eRAMS builds its client-side static assets using a tool called Grunt.  From the ROOT/media_erams directory, run:

sudo npm install

cd main/ && ln -s ../node_modules node_modules && bower install && cd ..

cd map/ && ln -s ../node_modules node_modules && cd ..

./grunt.sh . main/ map/

Development Server

Once all configurations have been completed, go to your ROOT/django/eRAMS directory and type: sudo -u www-data python manage.py runserver 0.0.0.0:8000

This will start a development eRAMS server locally on your machine at port 8000.  This server will dynamically restart when changes are made, so you really don’t need to touch it once it’s started.

Vagrant has configured port 8000 to forward to port 8081 on the host machine.

Finally, open a browser on your host computer to http://localhost:8081 and ensure everything is configured correctly.

Conventions and Libraries

The following are useful notes and links to information that will be helpful in getting acquainted with eRAMS development.

Project Directories

Server-side models, views and controllers will exist in ROOT/django/eRAMS/<project or plugin dir>/

Client-side code, such as javascript files and project-specific assets will be in ROOT/media_erams/map/projects/<project or plugin dir>/

Languages/Libraries

Python

http://docs.python.org/2/

All of the code that exists on the backend (besides models that are written in Java) is written in Python.

Django

https://docs.djangoproject.com/en/1.5/

Django is a Python web-application framework that eRAMS is contained within.  It makes it easy to handle HTTP requests and responses within a Python environment.

jQuery/jQuery UI

http://jquery.com/

http://jqueryui.com/

These libraries are used to query the DOM and build many of the UI elements that you’ll be using in your project.

Backbone

http://backbonejs.org/

This is a javascript library that is used to separate Models, Views, Collections and Events between different parts of the Javascript code.  It is used extensively in eRAMS.

Mercurial

https://www.mercurial-scm.org/guide

Mercurial is the source control system that is used to keep track of/merge/maintain our development repositories.

Linux

eRAMS runs inside of a Ubuntu Linux virtual environment.  It’d be good to be familiar with some common linux commands.  Development environments are provisioned and maintained using Vagrant and Ansible.

Postgres/PostGIS

http://www.postgresql.org/

http://postgis.net/

The database eRAMS uses to do a lot of its work is postgres, which is spatially-enabled with the Postgres PostGIS extension.

Ansible

Ansible is a simple IT automation tool that we use to configure and deploy eRAMS across an array of different environments.  You can also provision your virtual machine, including all software packages, configuration files, and even run a build of eRAMS using the Ansible scripts located in the ROOT/provisioning directory.

Glossary

ROOT: the root directory of your eRAMS installation