Install Aurum CLI
=================

Prerequisites
-------------

1. Debiab-based (e.g. Debian, Ubuntu operating system)

2. Have the following system packages installed:

   * mercurial (hg)
   * zip
   * unzip

3. Own a Bitbucket account.

4. Optionally, the system has Python's virtualenv support.


.. note::
    
    Currently, we only support Debian-based linux OS. Mac and 
    Windows users may not get the full benefit when they are
    using Aurum CLI.


.. note::

    We encourage users to install Aurum CLI with virtualenv.
    Speak with your system administrator if you are not
    sure about how to install Aurum CLI.

.. note::

    Aurum currently only support **hg** mercurial-based
    repository. GitHub does not support **hg** and 
    Bitbucket offers unlimited free private repository
    for academic user with **.edu** email address.


If **pip** returns error, check :ref:`pip-trouble-shoot-label` below.

-----------------------------


Aurum-cli on Fubini
-------------------

If you are a member of the GLASS Lab, you can find use ``aurum-cli``
off Fubini after ssh into our glasslab network.

.. code-block:: bash

    ssh username@fubini or ssh username@192.168.1.202
    aurum-cli


Install From Source
-------------------

The installation involves cloning down the repository and
running ``setup.py``.


Clone Repository
~~~~~~~~~~~~~~~~

First, clone the repository on Bitbucket.

.. code-block:: bash

    yeukhon@fubini:/home/yeukhon/work$ hg clone https://bitbucket.org/glassla/aurum-cli
    yeukhon@fubini:/home/yeukhon/work$ ls


The second command lists all the files and directories under ``/home/yeukhon/work``. Among
them there is a folder called **aurum-cli**.


Install Aurum CLI without virtualenv
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After cloning down the repository, you can install Aurum CLI
without virtualenv. But this often requires ``sudo`` privilege. 

.. code-block:: bash

    yeukhon@fubini:/home/yeukhon/work$ cd aurum-cli
    yeukhon@fubini:/home/yeukhon/work/aurum-cli$ [sudo] python setup.py develop
  
The last command may require ``sudo`` and will install aurum-cli to your system.
Afterward you can try ``aurum-cli`` from your shell.


Install Aurum CLI with virtualenv
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

    yeukhon@fubini:/home/yeukhon/work$ virtualenv newven
    yeukhon@fubini:/home/yeukhon/work$ source newven/bin/activate
    (newven)yeukhon@fubini:/home/yeukhon/work$ cd aurum-cli
    (newven)yeukhon@fubini:/home/yeukhon/work/aurum-cli$ python setup.py develop


The first command will create a virtualenv called **newven** and the second
will activate it so the current shell's Python environment will now
refer to this virtualenv. The last command will install aurum-cli to your system.
You can verify the installation by typing ``aurum-cli`` from your shell.

.. note::

    If you pay attention, the last two commands have **(newven)**. This
    indicates the current shell is using **newven**'s Python binary.
    So instead of using the system-wide ``/usr/bin/python``, you are using
    ``/path/to/newven/bin/python``. Google virtualenv if you are not
    familiar with virtualenv, but would like to use it because you think
    it is awesome!


----------------------------


.. _pip-trouble-shoot-label:

Pip Troubleshooting
-------------------

If you encounter ``NameError: name 'install' is not defined``, you can do the following:: 

    wget http://python-distribute.org/distribute_setup.py
    python distribute_setup.py

and then proceed to install aurum-cli again.