.. -*- mode: rst; mode: visual-line; mode: flyspell -*-

Exercise 1: Installing GeoMOOSE
===============================

Pull in the packages we need
----------------------------
::

  # update the server
  sudo apt-get update

  # GeoMoose Runtime Deps
  sudo apt-get install -y \
      apache2 libapache2-mod-php5 \
      mapserver-bin cgi-mapserver gdal-bin \
      php5-mapscript php5-sqlite php5-gd php5-curl
    
  # GeoMoose Build Deps
  sudo apt-get install -y \
      git-core \
      default-jre \
      python-sphinx make texlive texlive-latex-extra \
      naturaldocs

Get the GeoMoose source
-----------------------
::

  sudo mkdir /srv/geomoose
  sudo chown ubuntu:ubuntu /srv/geomoose
  git clone --recursive https://github.com/geomoose/geomoose.git /srv/geomoose

Git and Versions
----------------

By default this installs the latest development version of GeoMoose which is a work in progress.  It may be unstable and generally inappropriate for daily use. To install a released version switch to appropriate branch or tag and update the submodules.  

Released branches are named rx.y where x and y are the major and minor version numbers.  Released branches always point to the latest bugfix release for that branch.  Tags point to a specific release and are formatted as rx.y.z where x and y are as with branches and z is the patch level. e.g: ::

    cd /srv/geomoose
    git checkout r2.9.0
    git submodule update --init --recursive

As of this writing 2.9.0 is the latest version of GeoMoose.

  *Why do this with Git?*

  Using Git to control versions makes upgrades much easier.  It can allow you to try different versions of GeoMoose, including the latest development versions without having to download mulitple ZIP files or create multiple directories.

Build the JavaScript code
-------------------------

It is necessary to rebuild the JavaScript code any time the code changes so that the optimized build (geomoose.html) contains the current code.  This could occur if you make changes yourself, or if you switch to a different branch or tag.

::
   
    cd /srv/geomoose/js/libs
    ./build_js.sh



*Don't be fooled!*
References to ``geomoose2.6`` will appear while building GeoMoose.  This is normal.  All versions past 2.6.0 will show these messages.  They are normal and the version of GeoMoose that was selected before is the version being built.


Configuring Apache
------------------

Apache will be used to serve GeoMoose but Apache needs to have files pointed in the right places. 

First, we need to normalize the ``/srv/geomoose`` directory::
   
    cd /srv/geomoose/js
    ln -s ../services/php .
    ln -s geomoose.html index.html


Make things available in the apache document root
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
   
    sudo ln -s /srv/geomoose/js /var/www/html/geomoose
    sudo ln -s /srv/geomoose/docs/build/html /var/www/html/geomoose-docs

Enable CGI apache module (for MapServer)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
   
    sudo a2enmod cgi

Restart apache
^^^^^^^^^^^^^^
::
   
    sudo apachectl restart



Setup local config files
------------------------

GeoMoose uses two files to describe where local resources are located.  The first is ``local_settings.ini``. This uses the familiar ``.ini`` file format to point to temporary directories, MapServer, and the directory where MapFiles are loated.

These next steps can be intimidating to those unfamiliar with the command prompt.  We will be using the ``nano`` text editor to edit these files. ``nano`` does not need to be scary! You can use arrow keys to navigate and it uses the ``CTRL`` key with a basic set of commands to save and exit.

local_settings.ini
^^^^^^^^^^^^^^^^^^

Open ``local_settings.ini`` in the ``nano`` text editor
:: 
   nano /srv/geomoose/conf/local_settings.ini

Type or copy/paste the following lines into that file::
   
    [paths]
    root=/srv/geomoose/maps/
    mapserver_url=/cgi-bin/mapserv
    temp=/tmp/

After those lines are in the file use the ``CTRL`` key and the ``X`` key at the same time. When prompted type ``Y`` to save your changes, and then ``ENTER`` to save the file.


temp_directory.map
^^^^^^^^^^^^^^^^^^

This file is used to tell mapserver where to save data it uses temporarily to render images.

Open ``temp_directory.map`` in ``nano``::

    nano /srv/geomoose/maps/temp_directory.map

Change this line::

    IMAGEPATH "/tmp/www/"

To this line::

    IMAGEPATH "/tmp/"


After that line is in the file use the ``CTRL`` key and the ``X`` key at the same time. When prompted type ``Y`` to save your changes, and then ``ENTER`` to save the file.


Testing the install
-------------------

In a web browser go to your GeoMoose site.  It will be at ``http://<your VMs IP>/geomoose/geomoose.html``  You should see something like this:

.. image:: ex1-finished.png