.. _installation:

Installation Instructions
=========================

MAGI Core
---------

1. Install the following dependencies.
  - python-yaml
  - python-pymongo
  - python-pydot
  - python-networkx
  - py-matplotlib

  These packages can all be installed using pip.

  Install pip, if not already available.

  .. code-block:: bash

      curl -O https://bootstrap.pypa.io/get-pip.py
      python get-pip.py

  .. code-block:: bash

      pip install pyyaml
      pip install pymongo
      pip install pydot
      pip install networkx
      pip install matplotlib


2. Download and install MAGI

  .. code-block:: bash

      $ git clone https://github.com/deter-project/magi.git
      $ cd magi
      $ sudo python setup.py install

3. Create a MAGI distribution for MAGI installation on experiment nodes

  .. code-block:: bash

      $ mkdir /share/magi
      $ sudo python setup.py sdist toshare -p /share/magi/current/

4. Copy the source installation files, if required. Some of the existing agents
   refer to these.

  .. code-block:: bash

      $ scp -r users.isi.deterlab.net:/share/magi/tarfiles /share/magi/

5. Make a copy of the existing MAGI modules, if required

  .. code-block:: bash

      $ cd /share/magi
      $ mkdir modules
      $ git clone https://github.com/deter-project/magi-modules.git modules


..
   cd /usr/ports/devel/py-yaml
   make install clean
   
   cd /usr/ports/databases/pymongo
   make install clean
   
   cd /usr/ports/math/py-matplotlib
   make install clean
   
   - Mongo DB
      sudo pkg update -f
      sudo pkg install mongodb

   
MAGI Visualization
------------------

We have been working on a javascript based visualization library for MAGI
experiments. Although, currently, the libray only has a few sample
visualizations, we have tried to create a framework that can be expanded to do
generalizaed visualizations.

Experimenters can download the curently available source from out git repo, use
it as it is, or build upon the same. We would be more than happy to see what
others build, and if feasible add it to our codebase.

1. Download MAGI visualization code

  Make a copy of the visualization code under your web server home directory.

  .. code-block:: bash

      $ cd $WEBSERVER_HOME
      $ git clone https://github.com/deter-project/magi-viz.git

2. Install Mongo DB

  The visualization code works with Mongo DB. Install it and run a mongod server.

  Try connecting to the mongo db server to make sure it is up.

  .. code-block:: bash

     $ mongo
     MongoDB shell version: 2.6.4
     connecting to: test
     >

3. Enable PHP

  Install php module, and enable it in the apache configuration file.

4. Install PHP MongoDB extension

  .. code-block:: bash

      http://php.net/manual/en/book.mongo.php

5. Install PHP JSON extension

  .. code-block:: bash

      http://php.net/manual/en/book.json.php

6. Install PHP YAML extension

  .. code-block:: bash

      http://php.net/manual/en/book.yaml.php

Canned Data Visualization
^^^^^^^^^^^^^^^^^^^^^^^^^

  At this point you should be able to populate the database with canned data, and
  see sample visualizations.

  .. code-block:: bash

      $ cd $WEBSERVER_HOME/magi-viz/casestudy/clientserver
      $ ../../util/populate_db.sh magi_cs experiment_data


  If the data is successfully imported into the database, visit the following
  link to see a sample visualization.

  .. code-block:: bash

      http://localhost/magi-viz/casestudy/clientserver/traffic.html

  .. note::
  
      The information about importing/exporting of data, and visualization urls 
      is available in a README file under each experiment directory.
      
Realtime Data Visualization
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To be able to visualize real time data for an experiment, the visualization
code needs to be able to pull data from the experiment database.

SSH keys need to be setup for automatic creation of a SSH tunnel to experiment
database through DeterLab Ops machine.

1. Generate keys for web server user

  .. code-block:: bash

      sudo -u www ssh-keygen

2. Add generated pubkey as an authorized key for a user on Deter. This can be
   done by visiting the DeterLab webpage. The default userid that magi
   visualization code tries to use is 'muser'. This can either be changed in the
   code base, or can be overwritten using the config file or url parameters.

  .. code-block:: bash

      magi-viz/util/helpers.js
      getDefault(db_config, 'sshUserName', 'muser')

3. Add host key to known_hosts

  .. code-block:: bash

      $ sudo -u www ssh muser@users.isi.deterlab.net
      The authenticity of host 'users.isi.deterlab.net (206.117.25.49)'
      can't be established.
      ECDSA key fingerprint is SHA256:jj1atx6ugYXTkkmzAIPWVsl9LsOaOjxjb3n9emb4iwE.
      Are you sure you want to continue connecting (yes/no)? yes