.. _installation_development:

Development Environment
=======================

Installing the Virtualenv Environment
-------------------------------------

As it is explained in :ref:`installation_deployment`, it is best practice to
install `PubliForge` into a "virtual" Python environment. To do so, invoke
the following:

.. code-block:: bash

    $ virtualenv ~/bin/virtualenv
    $ source ~/bin/virtualenv/bin/activate
    (virtualenv3)$ pip install -U pip setuptools

Setting up an UTF-8 environment
-------------------------------

To efficiently work with text data, you must have an **UTF-8 environment**. To
check it, run the ``locale`` program:

.. code-block:: bash

    $ locale

If you don't have ``.UTF-8`` in your configuration, make sure that on your
system an UTF-8 locale is generated. To do so, type:

.. code-block:: bash

    $ sudo dpkg-reconfigure locales

Then, in your ``~/.bashrc`` file, add lines similar to:

.. code-block:: bash

    $ export LC_ALL=en_US.UTF-8
    $ export LANG=en_US.UTF-8
    $ export LANGUAGE=en_US.UTF-8 

To make these changes active in the current shell, source the ``.bashrc``:

.. code-block:: bash

    $ source ~/.bashrc

All newly started interactive bash processes will respect these settings.

Installing Required Packages and modules
----------------------------------------

See :ref:`installation_deployment_packages` for packages to install.

If you want to use the automatic HTML validation, you need to install the
`wdg-html-validator <http://htmlhelp.com/tools/validator>`_ package.

Setting up the Database
-----------------------

See :ref:`installation_deployment_database` to setup your database.

For development, you can name your database ``PubliForge``:

.. code-block:: bash

    $ sudo su - postgres -c "createdb -T template0 -E UTF-8 -O publiforge PubliForge"

Installing `PubliForge`
-----------------------

Check out the latest code:

.. code-block:: bash

    $ source ~/bin/virtualenv/bin/activate
    (virtualenv)$ pip install Mercurial
    (virtualenv)$ hg clone https://hg.publiforge.org/PubliForge

Install application and its dependencies:

.. code-block:: bash

    (virtualenv)$ cd PubliForge
    (virtualenv)$ pip install -e .

Now, set up the application by tuning ``development.ini`` and
``agent_development.ini`` (See :ref:`installation_customization`).

Populating the Database and the Storages
----------------------------------------

You need to use the :ref:`frontguide_scripts_pfpopulate` console script to
populate your database and your storages. To do so, type the following
command:

.. code-block:: bash

    (virtualenv)$ pfpopulate development.ini


Testing the application
-----------------------

To get this functionality working, you’ll need to install
`nose <https://github.com/nose-devs/nose>`_ package:

.. code-block:: bash

    (virtualenv)$ pip install nose

Once `nose` is installed, you can run the tests:

.. code-block:: bash

    (virtualenv)$ nosetests -v --with-id --failed

Running the application
-----------------------

Finally, to launch your application in front mode, invoke the following:

.. code-block:: bash

    (virtualenv)$ pserve --reload development.ini

To simulate an agent only mode, open a second console and execute:

.. code-block:: bash

    $ source ~/bin/virtualenv/bin/activate
    (virtualenv)$ pserve --reload development_agent.ini

The running application will now be available at http://localhost:6543.