.. _installation_base:

Installation of `Chrysalio`
===========================

.. _installation_base_packages:

Installing Required Packages
----------------------------

Before installing `Chrysalio`, you must install on your system the following
packages:

.. code-block:: bash

    $ sudo aptitude install python3-dev libffi-dev libzip-dev libxml2-dev libxslt1-dev build-essential

.. _installation_base_virtualenv:

Installing a Virtual Environment
--------------------------------

It is best practice to install `Chrysalio` into a "virtual" Python environment
in order to obtain isolation from any "system" packages you've got installed in
your current Python environment. This can be done by using `venv
<https://docs.python.org/3/library/venv.html>`_ module for Python 3.

To install a virtual environment, invoke the following commands for Python 3:

.. code-block:: bash

   $ sudo aptitude install python3-venv
   $ mkdir ~/bin
   $ python3 -m venv ~/bin/virtualenv3
   $ source ~/bin/virtualenv3/bin/activate
   (virtualenv3)$ pip install -U pip setuptools wheel

If you are deploying `Chrysalio` on a server with Apache 2 or Nginx, replace in
the preceding commands ``~/bin/virtualenv3`` by ``/usr/local/virtualenv3``.

.. _installation_base_database:

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

You need to create the database that matches your future configuration. We
suppose the current user is ``super``.

If you decide to use **SQLite**, you have nothing to do.

If you decide to use **PostgreSQL** (the recommended database), first install
it:

.. code-block:: bash

    $ sudo aptitude install postgresql libpq-dev
    $ sudo su - postgres -c "createuser --superuser --pwprompt super"
    $ createuser --no-superuser --pwprompt chrysalio
    $ createdb -T template0 -E UTF-8 -O chrysalio Chrysalio

In the provided configuration, the password for PostgreSQL user is `sesame`.

Then, install the corresponding Python package:

.. code-block:: bash

    $ source ~/bin/virtualenv3/bin/activate
    (virtualenv3)$ pip install psycopg2-binary

If you decide to use **MariaDB**, install it:

.. code-block:: bash

    $ sudo aptitude install mariadb-server libmariadb-dev libmariadbclient-dev
    $ sudo mysql -u root mysql
    mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,CREATE,DROP,ALTER ON *.* TO chrysalio@localhost IDENTIFIED BY 'sesame';
    mysql> CREATE DATABASE Chrysalio;
    mysql> QUIT;

Then, install the following Python package:

.. code-block:: bash

    $ source ~/bin/virtualenv3/bin/activate
    (virtualenv3)$ pip install mysqlclient

.. _installation_base_application:

Installing the Application
--------------------------

Installation in Standard Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Install the latest stable released and all its requirements into your virtual
Python environment:

.. code-block:: bash

    $ source ~/bin/virtualenv3/bin/activate
    (virtualenv3)$ pip install --extra-index-url=https://pypi.chrysal.io Chrysalio

Create a directory to deploy your instance and retrieve an example of
configuration files:

.. code-block:: bash

    $ mkdir Chrysalio
    $ cd Chrysalio
    $ wget https://pypi.chrysal.io/conf/Chrysalio.zip
    $ unzip Chrysalio.zip
    $ rm -f Chrysalio.zip

You can set up the application by tuning ``development.ini``, ``production.ini``
or ``ciouser.ini``. For instance, you can configure additional modules. See:
:ref:`installation_modules`.

You could update your installation with the following command:

.. code-block:: bash

    (virtualenv3)$ pip install --extra-index-url=https://pypi.chrysal.io -U Chrysalio

Installation in Development Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to use the release still in development, follow these steps:

.. code-block:: bash

    $ mkdir ~/Repositories
    $ cd ~/Repositories
    $ git clone https://gitlab.iinov.com/chrysalio/Chrysalio.git
    $ source ~/bin/virtualenv3/bin/activate
    (virtualenv3)$ cd ~/Repositories/Chrysalio
    (virtualenv3)$ pip install -e ".[development]"

.. _installation_base_run:

Populating and Running the Application
--------------------------------------

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

.. code-block:: bash

    (virtualenv3)$ ciopopulate development.ini

Then launch your server:

.. code-block:: bash

    (virtualenv3)$ pserve development.ini
    Starting server in PID xxxx.
    Serving on http://0.0.0.0:6543

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

.. _installation_base_test:

Testing the Application
-----------------------

To get this functionality working, you’ll need to install `Chrysalio` in
development mode (see :ref:`installation_base_application`) with testing
packages:

.. code-block:: bash

    (virtualenv3)$ pip install -e ".[testing]"

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

.. code-block:: bash

    (virtualenv3)$ pytest --last-failed

To know if the coverage of the tests is complete, you can use the following
command:

.. code-block:: bash

    (virtualenv3)$ pytest --last-failed --cov --cov-report=term-missing

Or, scripts can help you:

.. code-block:: bash

    (virtualenv3)$ ./pylint.sh
    (virtualenv3)$ ./pytest.sh