diff --git a/README.md b/README.md index f98b57388..7100ae4a0 100644 --- a/README.md +++ b/README.md @@ -6,193 +6,161 @@ ## Overview -Election results data entry and verification software built by [Ona Systems](http://company.ona.io) and commissioned by the Libyan [High National Elections Commission](http://hnec.ly/) and the [United Nations Development Program](http://www.undp.org). +Election results data entry and verification software built by [Ona Systems](http://company.ona.io), commissioned by the Libyan [High National Elections Commission](http://hnec.ly/) and [UNDP](http://www.undp.org). -## Quick install +## Quick Install -### Checkout the repos +### Checkout the Repository ```bash git clone git@github.com:onaio/tally-ho.git ``` -### Make a virtual environment and install requirements +### Set Up Virtual Environment and Install Requirements -Prerequisites: this assumes you have [virtualenvwrapper](http://virtualenvwrapper.readthedocs.org/en/latest/install.html) and [PostgreSQL](https://wiki.postgresql.org/wiki/Detailed_installation_guides) installed. +Prerequisites: Ensure [virtualenvwrapper](http://virtualenvwrapper.readthedocs.org/en/latest/install.html) and [PostgreSQL](https://wiki.postgresql.org/wiki/Detailed_installation_guides) are installed. ```bash mkvirtualenv tally --python=python3.9 pip install -r requirements/dev.pip ``` -Install `libpq-dev` library that contains a minimal set of `PostgreSQL`_binaries and headers requried -for building 3rd-party applications for `PostgreSQL`_. +Install `libpq-dev` for PostgreSQL headers: ```bash sudo apt-get install libpq-dev ``` -Install memcache +Install memcached and Redis: ```bash -sudo apt-get update && sudo apt-get install -y memcached +sudo apt-get update && sudo apt-get install -y memcached redis-server ``` -Install redis - -```bash -sudo apt-get install -y redis-server -``` - -Make sure you have the latest versions of pip, wheel, and setuptools installed, run +Ensure latest versions of pip, wheel, and setuptools: ```bash python -m pip install -U pip wheel setuptools ``` -To Enable [pre-commit hook checks](https://pre-commit.com/#3-install-the-git-hook-scripts) for development, in your virtual env, run +Enable [pre-commit hook checks](https://pre-commit.com/#3-install-the-git-hook-scripts): ```bash pre-commit install ``` -### Running celery +### Running Celery ```bash celery -A tally_ho.celeryapp worker --loglevel=info ``` -### Quick start with user demo data +### Quick Start with User Demo Data -> This will remove all data in the database. - -To create the database, load demo users, and start the server all in one, run +> **Warning**: This will erase all database data. ```bash ./scripts/quick_start ``` -If you've aleady setup the server, you can start the server with +If server setup is complete, start the server: ```bash python manage.py runserver --settings=tally_ho.settings.dev ``` -### Loading tally demo data - -> TODO: add some demo result forms and candidate lists +### Loading Tally Demo Data -### Advanced: recreate the database, then load the data and demo users +> **Note**: Add demo result forms and candidate lists. -> This will remove all data in the database. -> This will only work if you have data files in the folder `./data` +### Advanced: Recreate Database and Load Demo Users -The first argument is the database user, the second is the database host IP -address, and the third is the settings file. Modify these arguments as needed. +> **Warning**: This erases all database data and only works with files in `./data`. ```bash ./scripts/reload_all postgres 127.0.0.1 tally_ho.settings.common ``` -## Docker Install +## Docker Installation -If you already have Docker and `docker-compose` installed on your machine you can quickly have a demo up by changing into the checked out code directory and running: +With Docker and `docker-compose` installed, build and run: ```bash docker-compose build docker-compose up ``` -You can now visit the site at `127.0.0.1:8000`. - -If you want to use Docker to run the site in production you will need to: +Visit `127.0.0.1:8000`. For production, modify the `docker-compose.yml` file: -1. modify the `docker-compose.yml` file to change the NGINX listening port from 8000 to 80, -2. add the host you are running the site on to a new `ALLOWED_HOSTS` list in the `tally_ho/settings/docker.py` 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 `pytest tally_ho` - -## Documentation - -### Arabic Translations - -This project supports Arabic translations using Django’s internationalization (i18n) framework. Follow these steps to manage Arabic translations in the project: - -### 1. Set Up Arabic Language Support +Run tests with: -Ensure that Arabic (`ar`) is added to the list of supported languages in the Django settings file (`settings.py`): - -```python -# settings.py -LANGUAGES = [ - ('en', 'English'), - ('ar', 'Arabic'), - # Add other languages as needed -] - -# Ensure LANGUAGE_CODE is set to a default language (e.g., 'en') -LANGUAGE_CODE = 'en' +```bash +pytest tally_ho ``` -### 2. Generate Arabic Translation Files - -In your project root, run the following command to generate a `django.po` file for Arabic. This file will be located in `locale/ar/LC_MESSAGES/django.po`: +## Documentation -```bash -django-admin makemessages -l ar -``` +### Arabic Translations -This command will extract all translatable strings marked with the `gettext` functions (e.g., `_("Your text here")`) from your codebase and add them to the Arabic `.po` file. +Follow these steps for managing Arabic translations: -### 3. Edit Arabic Translations +1. **Add Arabic Language**: Update `settings.py`: -Open `locale/ar/LC_MESSAGES/django.po` and provide Arabic translations for each entry. Each translation entry will look like this: + ```python + # settings.py + LANGUAGES = [ + ('en', 'English'), + ('ar', 'Arabic'), + ] -```po -#: path/to/your/template.html:42 -msgid "Original text to translate" -msgstr "Your Arabic translation here" -``` + # Ensure LANGUAGE_CODE is set to a default language (e.g., 'en') + LANGUAGE_CODE = 'en' + ``` -Replace `"Your Arabic translation here"` with the Arabic equivalent of the `msgid` string. +2. **Generate Arabic Translation Files**: -### 4. Compile Arabic Translations + ```bash + django-admin makemessages -l ar + ``` -After updating the translations, compile them to create the `.mo` files required by Django. Run: +3. **Edit Arabic Translations**: Update `locale/ar/LC_MESSAGES/django.po`. -```bash -django-admin compilemessages -``` +4. **Compile Translations**: -This command will compile all `.po` files, including Arabic, into `.mo` files for use by Django. + ```bash + django-admin compilemessages + ``` ### Generating Model Graphs -The below assumes you have `pip` installed `requirements/dev.pip` and [graphviz](https://graphviz.org/download/) in your machine. +Install requirements from `requirements/dev.pip` and [graphviz](https://graphviz.org/download/). -Generate model graph for all models: +Generate all model graphs: -```python +```bash python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -g -o tally-ho-all-models.png ``` -Generate model graph for app models: +Generate specific app model graphs: -```python -python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -X GroupObjectPermission,UserObjectPermission,GroupObjectPermissionBase,BaseGenericObjectPermission,UserObjectPermissionBase,BaseObjectPermission,Version,Revision,Pageview,Visitor,Session,AbstractBaseSession,Site,LogEntry,User,Group,AbstractUser,Permission,ContentType,AbstractBaseUser,PermissionsMixin,BaseModel -g -o tally-ho-app-models.png +```bash +python manage.py graph_models --settings=tally_ho.settings.dev --pydot -a -X GroupObjectPermission,... -g -o tally-ho-app-models.png ``` ### Demo Users -The `create_demo_users` command will create demo users for each role with usernames like `super_administrator`, and password `data`. +Use the `create_demo_users` command to create demo users with usernames like `super_administrator`, and password `data`. ### File Uploads -The `MAX_FILE_UPLOAD_SIZE` variable in `tally_ho/settings/common.py` file defines the file upload limit which is currently set to 10MB. +File upload limit is set to 10MB in `MAX_FILE_UPLOAD_SIZE` within `tally_ho/settings/common.py`. ## News -- This is an [article about tally-ho](https://ona.io/home/writing-python-code-to-decide-an-election-2/) and its use in Libya. -- This presentation at PyConZA 2014 about the project, [Writing Python Code to Decide an Election](https://ona.io/home/writing-python-code-to-decide-an-election-2/). +- Article: [Writing Python Code to Decide an Election](https://ona.io/home/writing-python-code-to-decide-an-election-2/). +- PyConZA 2014 presentation: [Writing Python Code to Decide an Election](https://ona.io/home/writing-python-code-to-decide-an-election-2/).