1. Installation

machado is a Django framework for Chado.

1.1. Prerequisites

PostgreSQL 16

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

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:

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

Python 3.12+

We strongly recommend creating a new virtualenv for your project:

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

1.2. Install machado

pip install machado

Or, to install from the latest source:

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

1.3. 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:

machado-startproject .

This generates the following files in the current directory:

.
├── .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

1.4. Configure the environment

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

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

The DATABASE_URL format follows the 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.

1.5. Migrate and run

Apply the Chado schema migrations:

python manage.py migrate

Just ignore warnings about unapplied migrations.

Run the tests to verify the installation:

python manage.py test machado

Start the development server:

python manage.py runserver

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

1.6. Optional: Elasticsearch

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

pip install 'elasticsearch>=7,<8'

Then uncomment ELASTICSEARCH_URL in .env:

ELASTICSEARCH_URL=http://127.0.0.1:9200/

Rebuild the search index after loading data:

python manage.py rebuild_index

1.7. References