INSTALL.md

Installation requirements on ubuntu

WCIVF requires Python 3.12.

To install the required system packages:

Ubuntu

sudo apt-get install python3-dev libpq-dev libjpeg-dev redis-server libtidy-dev

OSX with Homebrew

brew install redis postgresql jpeg cmake

OSX users also need to manually install tidy following these steps

Python packages

Python packages and environments are managed using uv.

To install:

uv sync

This will create a virtual environment and install packages into it.

You can activate this environment by running

source .venv/bin/activate

Or by uv run will automatically use the correct environment.

Running tests

Check that your env has correctly installed and project is working by running the tests:

uv run pytest

Code formatting

Additionally, this project uses ruff and djhtml for code formatting and linting:

• ruff check . (lint with ruff)
• ruff format . (auto-format with ruff)
• git ls-files '*.html' | xargs djhtml (auto-format templates with djhtml)

ruff has in-built functionality to fix common linting errors. Use the --fix option to do this.

Ruff is automatically called as part of pytest in this project.

A pre-commit hook is defined in the project to run it automatically before each commit. See the pre-commit docs for more information, or simply run the below command to setup:

pre-commit install

Database setup

Create a Postgres database as detailed below, then:

python manage.py migrate
python manage.py import_parties
python manage.py import_ballots
python manage.py import_people

If you want election results, you'll also need to import them:

python manage.py import_ballots --current

If you don't want to install Redis for some reason (like e.g. laziness) you can override the cache backend with a file at ./wcivf/settings/local.py with the following:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.dummy.DummyCache',
    }
}

Setting up PostgreSQL

WhoCanIVoteFor uses PostgreSQL. To set this up locally, first install the packages:

sudo apt-get install postgresql

Then create, for example, a wcivf user:

sudo -u postgres createuser -P wcivf

Set the password to, for example, wcivf. Then create the database, owned by the wcivf user:

sudo -u postgres createdb -O wcivf wcivf

Then, create a file wcivf/settings/local.py with the following contents, assuming you used the same username, password and database name as above:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'wcivf',
        'USER': 'wcivf',
        'PASSWORD': 'wcivf',
        'HOST': 'localhost',
        'PORT': '',
    }
}

See the local.example.py file for other suggested settings to use for local development.

Test Feedback Form changes to Slack Webhooks

You will need access to incoming webhooks page in the DC Slack account.

Once you have access, create a new webhook and select slackbot as the channel. Add that URL to your local.py:

SLACK_FEEDBACK_WEBHOOK_URL = "URL"

Then, have your local install post to your channel in Slack.

Complete the feedback form on localhost, then run the management command manage.py batch_feedback_to_slack --hours-ago=1

Feedback should appear in your Slack channel.

Update Welsh Translations

To add new strings into the translation files, run:

make makemessages

Once translated, run:

make compilemessages`

If you're just filling in blanks for Welsh translations that already exist, you can skip the makemessages step and just run make compilemessages.