Tally-Ho

Overview

Election results data entry and verification software built by Ona Systems, commissioned by the Libyan High National Elections Commission and UNDP.

Quick Install

Checkout the Repository

git clone git@github.com:onaio/tally-ho.git

Install Dependencies

Prerequisites: uv and PostgreSQL.

uv sync

uv will install the pinned Python interpreter from .python-version and create .venv with all dependencies from uv.lock.

Install libpq-dev for PostgreSQL headers:

sudo apt-get install libpq-dev

Install memcached and Redis:

sudo apt-get update && sudo apt-get install -y memcached redis-server

Enable pre-commit hook checks:

uv run pre-commit install

Running Celery

uv run celery -A tally_ho.celeryapp worker --loglevel=info

Loading Tally Demo Data

The docker-compose stack auto-seeds a demo tally on boot via create_demo_tally — 2 ballots, 6 candidates, 2 centers, 4 stations, 8 result forms, plus quarantine checks. It's idempotent on name; re-run with --clean to wipe and re-create.

To run management commands against the running stack, use the ./build.sh wrapper:

./build.sh create_demo_tally --clean

Note: Result form barcodes must be at least 11 characters — the Data Entry barcode-verify UI enforces this client-side. The demo tally uses 11-digit barcodes starting at 10000000001.

For the PVP upload flow specifically, create_demo_pvp_bundle emits a bundle zip targeting every result form in a tally. The zip lands at data/demo_pvp_bundle_<tally_id>.zip (visible on the host via the project-root bind mount).

./build.sh create_demo_pvp_bundle --tally-id <id>

See docs/overview/pvp.md for the full PVP end-to-end walkthrough.

Docker Installation

With Docker and docker-compose installed, build and run:

docker-compose build
docker-compose up

Visit 127.0.0.1:8000. For production, modify the docker-compose.yml file:

1. Change NGINX port from 8000 to 80.
2. Add your host to ALLOWED_HOSTS in tally_ho/settings/docker.py.

Running Tests

Run tests with:

uv run pytest tally_ho

Documentation

Arabic Translations

Follow these steps for managing Arabic translations:

1. Add Arabic Language: Update settings.py:

   # settings.py
       LANGUAGES = [
           ('en', 'English'),
           ('ar', 'Arabic'),
   ]
   
   # Ensure LANGUAGE_CODE is set to a default language (e.g., 'en')
       LANGUAGE_CODE = 'en'

2. Generate Arabic Translation Files:

   django-admin makemessages -l ar

3. Edit Arabic Translations: Update locale/ar/LC_MESSAGES/django.po.

4. Compile Translations:

   django-admin compilemessages

Generating Model Graphs

Install graphviz. The dev dependency group already includes django-extensions and pydot.

Generate all model graphs:

uv run python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -g -o tally-ho-all-models.png

Generate specific app model graphs:

uv run python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -X GroupObjectPermission,... -g -o tally-ho-app-models.png

Demo Users

Use the create_demo_users command to create demo users with usernames like super_administrator, and password data.

File Uploads

File upload limit is set to 10MB in MAX_FILE_UPLOAD_SIZE within tally_ho/settings/common.py.

News

• Article: Writing Python Code to Decide an Election
• PyConZA 2014 presentation: Writing Python Code to Decide an Election