Installation
============

*machado* is a `Django <https://www.djangoproject.com/>`_ framework for `Chado <http://gmod.org/wiki/Chado_-_Getting_Started>`_.

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

**PostgreSQL 16**

Install PostgreSQL and create a database and user for loading the Chado schema.
As the ``postgres`` user run:

.. code-block:: bash

    psql
    CREATE USER username WITH ENCRYPTED PASSWORD 'password';
    CREATE DATABASE yourdatabase WITH OWNER username;
    ALTER USER username CREATEDB;

Don't forget to configure the PostgreSQL server to allow regular users to connect (``pg_hba.conf``).

**Linux dependencies**

Be sure to have the following packages installed:

.. code-block:: bash

    sudo apt install zlib1g-dev libbz2-dev liblzma-dev python3-dev

**Python 3.12+**

We strongly recommend creating a new virtualenv for your project:

.. code-block:: bash

    mkdir /var/www/MYGENOME
    cd /var/www/MYGENOME
    python3 -m venv .venv
    source .venv/bin/activate

Install machado
---------------

.. code-block:: bash

    pip install machado

Or, to install from the latest source:

.. code-block:: bash

    pip install git+https://github.com/lmb-embrapa/machado.git

Create a project
----------------

The ``machado-startproject`` command creates a ready-to-use Django project
with pre-configured settings, URL routing, and WSGI/ASGI entry points:

.. code-block:: bash

    machado-startproject .

This generates the following files in the current directory:

.. code-block:: text

    .
    ├── .env                # Your configuration (auto-generated SECRET_KEY)
    ├── .env.example        # Reference with all available settings
    ├── manage.py
    └── machadoproject/
        ├── __init__.py
        ├── settings.py
        ├── urls.py
        ├── wsgi.py
        └── asgi.py

Configure the environment
-------------------------

Edit the ``.env`` file and set your PostgreSQL connection string:

.. code-block:: bash

    SECRET_KEY=<auto-generated>
    DATABASE_URL=postgres://username:password@localhost:5432/yourdatabase

The ``DATABASE_URL`` format follows the
`dj-database-url <https://github.com/jazzband/dj-database-url>`_ convention.
Replace ``username``, ``password``, and ``yourdatabase`` with the values you
created in the Prerequisites step.

See ``.env.example`` for the full list of optional settings including
Elasticsearch, JBrowse, and API configuration.

Migrate and run
---------------

Apply the Chado schema migrations:

.. code-block:: bash

    python manage.py migrate

Just ignore warnings about unapplied migrations.

Run the tests to verify the installation:

.. code-block:: bash

    python manage.py test machado

Start the development server:

.. code-block:: bash

    python manage.py runserver

Open ``http://localhost:8000/`` in your browser.

Optional: Elasticsearch
-----------------------

To enable full-text search, install Elasticsearch 7.x and add the Python
client:

.. code-block:: bash

    pip install 'elasticsearch>=7,<8'

Then uncomment ``ELASTICSEARCH_URL`` in ``.env``:

.. code-block:: bash

    ELASTICSEARCH_URL=http://127.0.0.1:9200/

Rebuild the search index after loading data:

.. code-block:: bash

    python manage.py rebuild_index


References
----------

* http://gmod.org/wiki/Chado_Django_HOWTO