Installation

Serenata de Amor consists of two main components:

Rosie — the AI that analyses congressional expense data and flags suspicious reimbursements.
Jarbas — the Django web application that presents Rosie’s findings to the public.

Both can be run with Docker or installed locally. Docker is the recommended approach because it handles all service dependencies (PostgreSQL, RabbitMQ, Memcached) automatically.

Docker (recommended)
Local install

Prerequisites

Install Docker and Docker Compose for your platform:

Set up the environment file

cp contrib/.env.sample .env

The sample file contains working defaults for local development. Refer to the Configuration page for a full reference of every variable.

Start all services

docker-compose up

This brings up the following containers:

Service	Image	Role
`django`	`serenata/django`	Jarbas web server (Gunicorn)
`tasks`	`serenata/django`	Celery worker for async tasks
`beat`	`serenata/django`	Celery beat scheduler
`queue`	`rabbitmq:3.7.3-alpine`	RabbitMQ message broker
`cache`	`memcached:1.5.8-alpine`	Memcached cache
`elm`	`serenata/elm`	Elm front-end asset compiler
`rosie`	`serenata/rosie`	Rosie AI analysis runner

Run Rosie

docker-compose run --rm rosie python rosie.py run chamber_of_deputies

Available modules: chamber_of_deputies, federal_senate.

Set up Jarbas

Apply migrations and load sample data:

docker-compose run --rm django python manage.py migrate
docker-compose run --rm django python manage.py reimbursements /mnt/data/reimbursements_sample.csv
docker-compose run --rm django python manage.py companies /mnt/data/companies_sample.xz
docker-compose run --rm django python manage.py suspicions /mnt/data/suspicions_sample.xz
docker-compose run --rm django python manage.py searchvector
docker-compose run --rm django python manage.py tweets

Access Jarbas

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

Prerequisites

Install the following on your machine before proceeding:

Dependency	Required version
Python	3.5+
Node.js	8
RabbitMQ	3.6
PostgreSQL	9.6

Clone the repository

git clone https://github.com/okfn-brasil/serenata-de-amor.git
cd serenata-de-amor

Install Jarbas Python dependencies

python -m pip install -r requirements-dev.txt

Install Node.js dependencies

npm install

Install Elm packages

./node_modules/.bin/elm-package install --yes

Elm package installation may not be required in all environments. See npm issue #17316 for context.

Install Rosie dependencies

Rosie has its own Python environment. The simplest setup uses Anaconda:

conda update conda
conda create --name serenata python=3
conda activate serenata
pip install -r rosie/requirements.txt

Alternatively, install directly with pip (a virtual environment is recommended):

pip install -r rosie/requirements.txt

Python `lzma` module on Linux

On some Linux distributions, the lzma module is not installed by default. Verify it is available with:

python -m lzma

On Debian-based systems, fix a missing lzma with:

apt-get install liblzma-dev

On macOS:

brew install xz

You may need to recompile Python after installing the system library.

Configure environment variables

cp contrib/.env.sample .env

Edit .env to match your local PostgreSQL and RabbitMQ connection details. See the Configuration page for the full variable reference.

Apply migrations

python manage.py migrate

Load data

Start a Celery worker first (RabbitMQ must be running):

celery worker --app jarbas

Then load data from the sample files in contrib/data/:

python manage.py reimbursements <path to reimbursements.xz>
python manage.py suspicions <path to suspicions.xz>
python manage.py companies <path to companies.xz>
python manage.py tweets

Build the search index

python manage.py searchvector

Generate static assets

npm run assets
python manage.py collectstatic

Run the development server

python manage.py runserver

Jarbas is available at http://localhost:8000.

Django Admin

Create a superuser to access the admin interface at localhost:8000/admin/:

python manage.py createsuperuser

Running Rosie without Docker

If you prefer to run Rosie outside of Docker after setting up its Python environment:

python rosie.py run chamber_of_deputies

To write output to a custom directory:

python rosie.py run chamber_of_deputies --output /my/serenata/directory/

The output is a suspicions.xz compressed CSV file containing all flagged irregularities.

Overview

Getting Started

Rosie (AI Engine)

Jarbas (Web Platform)

Contributing

Prerequisites

Set up the environment file

Start all services

Run Rosie

Set up Jarbas

Access Jarbas

Prerequisites

Clone the repository

Install Jarbas Python dependencies

Install Node.js dependencies

Install Elm packages

Install Rosie dependencies

Python `lzma` module on Linux

Configure environment variables

Apply migrations

Load data

Build the search index

Generate static assets

Run the development server

Django Admin

Running Rosie without Docker

Build docs developers (and LLMs) love

Overview

Getting Started

Rosie (AI Engine)

Jarbas (Web Platform)

Contributing

​Prerequisites

​Set up the environment file

​Start all services

​Run Rosie

​Set up Jarbas

​Access Jarbas

​Prerequisites

​Clone the repository

​Install Jarbas Python dependencies

​Install Node.js dependencies

​Install Elm packages

​Install Rosie dependencies

​Python lzma module on Linux

​Configure environment variables

​Apply migrations

​Load data

​Build the search index

​Generate static assets

​Run the development server

​Django Admin

​Running Rosie without Docker

Build docs developers (and LLMs) love

Prerequisites

Set up the environment file

Start all services

Run Rosie

Set up Jarbas

Access Jarbas

Prerequisites

Clone the repository

Install Jarbas Python dependencies

Install Node.js dependencies

Install Elm packages

Install Rosie dependencies

Python `lzma` module on Linux

Configure environment variables

Apply migrations

Load data

Build the search index

Generate static assets

Run the development server

Django Admin

Running Rosie without Docker