Jarbas setup

Prerequisites

Before starting, copy the sample environment file to the project root:

cp contrib/.env.sample .env

Edit .env with your settings. The most important variables are covered in the configuration reference below.

Docker (recommended)
Local install

Docker Compose handles every service — PostgreSQL, RabbitMQ, Memcached, Celery workers, and the Elm frontend build — with a single command.Requirements: Docker and Docker Compose.

Build and start all services

docker-compose up -d

This starts the following containers: django, elm, queue (RabbitMQ), tasks (Celery worker), beat (Celery beat scheduler), and cache (Memcached).

Apply database migrations

docker-compose run --rm django python manage.py migrate

Seed with sample data

Load the sample datasets bundled in contrib/data/:

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 tweets

For a full dataset, run Rosie first, then copy the output files to contrib/data/ and reference them from /mnt/data/ inside the container.

Build the full-text search index

Required for the dashboard search bar to work:

docker-compose run --rm django python manage.py searchvector

Open the dashboard

Mode	URL
Development	localhost:8000
Production	localhost

Verify the setup:

docker-compose run --rm django python manage.py check
docker-compose run --rm django python manage.py test

Install and manage all dependencies directly on your machine.Requirements:

Install JavaScript and Elm dependencies

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

The elm-package install step may not be necessary depending on your npm version. See npm/npm#17316 for context.

Install Python dependencies

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

On some Linux distributions, Python’s lzma module is not installed by default. Check with python -m lzma. On Debian-based systems run apt-get install liblzma-dev; on macOS run brew install xz. You may need to recompile Python afterward.

Apply database migrations

python manage.py migrate

Start the Celery worker

Data loading commands require RabbitMQ and a running Celery worker:

celery worker --app jarbas

Keep this process running in a separate terminal while you load data.

Load data

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

Sample files are available in contrib/data/. Full datasets can be produced by Rosie or downloaded with the serenata-toolbox.

Build the search index

python manage.py searchvector

Generate static assets

npm run assets
python manage.py collectstatic

Start the development server

python manage.py runserver

Open localhost:8000 in your browser.

Verify the setup:

python manage.py check
python manage.py test

Environment variables

The .env file controls all runtime configuration. Key variables:

Django settings

Variable	Type	Description
`SECRET_KEY`	string	Django secret key. Required.
`ENVIRONMENT`	string	`development` or `production`. Controls `DEBUG` mode.
`LOG_LEVEL`	string	Gunicorn log level (e.g. `debug`, `info`). Setting `debug` enables the Django Debug Toolbar.
`ALLOWED_HOSTS`	string	Comma-separated list of allowed hostnames. Defaults to `*`.
`WEB_WORKERS`	int	Number of Gunicorn worker processes.
`WEB_TIMEOUT`	int	Gunicorn worker timeout in seconds.
`CACHE_BACKEND`	string	Django cache backend class (e.g. `django.core.cache.backends.memcached.MemcachedCache`).
`CACHE_LOCATION`	string	Cache server address (e.g. `localhost:11211`).

Database and message broker

Variable	Type	Description
`DATABASE_URL`	string	PostgreSQL connection URL. Must be PostgreSQL — `JSONField` and `SearchVectorField` require it.
`CELERY_BROKER_URL`	string	RabbitMQ or other Celery-compatible broker URL (e.g. `amqp://guest:guest@localhost//`).

Google settings

Variable	Type	Description
`GOOGLE_ANALYTICS`	string	Google Analytics tracking ID (e.g. `UA-123456-7`).
`GOOGLE_STREET_VIEW_API_KEY`	string	Google Street View Image API key for receipt location previews.

Twitter settings

Variable	Type	Description
`TWITTER_CONSUMER_KEY`	string	Twitter API key.
`TWITTER_CONSUMER_SECRET`	string	Twitter API secret.
`TWITTER_ACCESS_TOKEN`	string	Twitter access token.
`TWITTER_ACCESS_SECRET`	string	Twitter access token secret.

Obtain credentials by following the python-twitter getting started guide.

Production settings

Variable	Type	Description
`VIRTUAL_HOST_WEB`	string	Hostname for the HTTPS certificate. Add to `/etc/hosts` when testing locally.
`LETSENCRYPT_EMAIL`	string	Email address for the Let’s Encrypt certificate.
`HTTPS_METHOD`	string	Set to `noredirect` to disable HTTP→HTTPS redirect. Default is `redirect`.
`USE_X_FORWARDED_HOST`	bool	Whether to trust the `X-Forwarded-Host` header.
`SECURE_PROXY_SSL_HEADER`	string	Tuple-like value for `SECURE_PROXY_SSL_HEADER` (e.g. `HTTP_X_FORWARDED_PROTO,https`).

Overview

Getting Started

Rosie (AI Engine)

Jarbas (Web Platform)

Contributing

Prerequisites

Environment variables

Build docs developers (and LLMs) love

Overview

Getting Started

Rosie (AI Engine)

Jarbas (Web Platform)

Contributing

​Prerequisites

​Environment variables

Build docs developers (and LLMs) love

Prerequisites

Environment variables