Installation
************

Instructions
============

.. _install:

The recommended way
-------------------

The recommended way to install FPlaneServer is using `pip <https://pip.pypa.io/en/latest/>`_::

    pip install --extra-index-url https://gate.mpe.mpg.de/pypi/simple/ fplaneserver

It's possible to set the extra index URL permanently by adding the following lines
to the ``$HOME/.pip/pip.conf`` file::

    [global]
    extra-index-url = https://gate.mpe.mpg.de/pypi/simple

or exporting the environment variable::

    export PIP_EXTRA_INDEX_URL=https://gate.mpe.mpg.de/pypi/simple

The list of released versions can be seen `on the MPE pypi server
<https://gate.mpe.mpg.de/pypi/simple/pyhetdex/>`_. A specific version can be
installed using `specifiers
<https://pip.pypa.io/en/stable/reference/pip_install/#requirement-specifiers>`_,
e.g. issuing ``pip install fplaneserver==1.0``.

We suggest you install FPlaneServer into a `virtualenv
<https://virtualenv.pypa.io/en/stable/>`_, in an `anaconda
<https://www.continuum.io/downloads>`_/`conda
<http://conda.pydata.org/docs/index.html>`_ or in similar environments.

Of course it is also possible to install FPlaneServer without any of the above with::

    pip install --user --extra-index-url https://gate.mpe.mpg.de/pypi/simple/ fplaneserver

This way the FPlaneServer executables are installed in ``$HOME/.local/bin``, so make sure to add
this to the environment variable ``PATH`` to be able to easily use
them on the command line. The use of ``sudo`` when installing with pip is
`discouraged
<http://stackoverflow.com/questions/21055859/what-are-the-risks-of-running-sudo-pip>`_
and potentially harmful.

.. _svninst:

From the online svn repository
------------------------------

These steps are to be followed if you want to install the latest version.

First get a local copy of ``FPlaneServer``, you can checkout the repository with::

  svn checkout svn://luna.mpe.mpg.de/fplaneserver/trunk fplaneserver

Similarly you can check out any branch. Now you can install with::

  pip install /path/to/fplaneserver

or::

  cd /path/to/fplaneserver
  pip install .

It's also possible to install fplaneserver directly from the svn repository without
checking it out::

  pip install svn+svn://luna.mpe.mpg.de/fplaneserver/trunk#egg=fplaneserver

If necessary replace ``trunk`` with the desired tag or branch to checkout and
install.

.. _Dependances:

Dependances
===========

Mandatory dependences
---------------------

::

   werkzeug
   flask
   flask_login
   peewee
   pyopenssl
   gunicorn

.. _pydep:

Python dependencies
^^^^^^^^^^^^^^^^^^^

* testing::

   robotframework
   robotframework-requests
   coverage>=4.2

   tox  # for automatizing the tests
   tox-pyenv

* documentation::

    sphinx
    numpydoc
    alabaster
    pyhetdex

* automatic documentation build::

    sphinx-autobuild => 0.5.2

.. _inst_devel:

Development
===========

If you develop ``fplaneserver`` we suggest you checkout the svn
repository and install them in `"editable" mode
<https://pip.pypa.io/en/latest/reference/pip_install.html#editable-installs>`_
. We also recommend installing all of the optional dependances::
  
  cd /path/to/fplaneserver
  pip install -e .

See :doc:`contributions` for more information.

.. _notes:

Notes and problems
==================

* It is possible to change the version to install from svn by selecting a specific
  commit::

    pip install svn+svn://luna.mpe.mpg.de/fplaneserver//trunk@5#egg=fplaneserver

  or a different branch/tag::

    pip install svn+svn://luna.mpe.mpg.de/fplaneserver/tag/v0.0.0#egg=fplaneserver

* If the installation gets interrupted with an error like::

    ImportError: No module named 'flask'

  run ``pip install flask`` and then retry ``fplaneserver`` installation