seanballais / botos

A web-based election system for schools.

Botos

An open source web-based election system for schools.

Botos is a web-based school election system designed for low-coercion risk elections. It is designed to be used in schools for student elections. It supports running multiple different elections in one installation, and real-time viewing and exporting of election results.

Documentation

Currently, the documentation is a work-in-progress. However, the project itself is already feature-complete. The repository's wiki is where you can find this project's (incomplete) documentation.

Deployment

Instructions on deploying Botos may be accessed here.

Bug Reports and Feature Suggestions

If you would like to report a bug or suggest a feature, please consider filing an issue. For bug reports, please describe the bug as much as possible, and include a description on how to recreate it.

Development

Botos is developed using Python 3, and Django. At the moment, the project is using Python 3.12 and Django 5.0. In the future, the project will be moved to a newer version of Python 3 and Django. Aside from the two aforementioned technologies, Botos also uses the following:

• PostgreSQL 16
• Django Autocomplete Light
• OpenPyXL
• BeautifulSoup 4 (for development)
• Coverage (for development)

This section is intended for those seeking to contribute or work on Botos. If you are seeking to deploy Botos in a production, please refer to the Deployment section.

Setting Up For Development

At the moment, development and deployment is only supported in Linux machines. Development in Windows has incomplete support, but deployment does not. You may attempt to develop and deploy Botos in Windows and macOS, but there is no complete documentation available yet. However, macOS users may not need to delve away too much from the set-up process detailed here.

Fork this project repository before continuing. This will allow you to make changes without worrying about write access. Before cloning the forked repository, make sure you have install PostgreSQL 16, Python 3.12, and Pipenv. It is recommended that you install Python using pyenv, a Python version manager. The database that Botos will use must already be set-up. Please refer to PostgreSQL documentation to know how to set-up a PostgreSQL database.

Once the requirements have been installed, you may now clone the fork.

$ git clone <repo_url>/botos
$ cd botos

Once you have finishing cloning, perform the following to install the required packages.

$ pipenv shell
$ pipenv install

Since we're using Pipenv, we have to always run pipenv shell before working on Botos. This is because Pipenv provides a virtual environment that isolates dependencies from system-installed dependencies. To learn more virtual environment, you may read this article.

Before we can finally run and start working on Botos, we have to set up environment variables for the database. The following environment variables must exist:

• BOTOS_DEBUG - must be either True, 1, False, or 0. This should be set to True in development environments.
• BOTOS_DATABASE_HOST - the PostgreSQL server host (e.g. localhost)
• BOTOS_DATABASE_PORT - the port of the PostgreSQL server (e.g. 5432)
• BOTOS_DATABASE_NAME - the name of the database that Botos will use
• BOTOS_DATABASE_USERNAME - the username of the user to be used for the Botos database
• BOTOS_DATABASE_PASSWORD - the password of the user to be used for the Botos database
• BOTOS_TEST_DATABASE_NAME - the name of the test database for Botos

It is recommended to set the environment variables in an environment file and call your shell to source them. Different shells will require different ways of sourcing variables. For those using shells such as Bash and ZSH, you may refer to botos/env/botos.env.sample. On the other hand, if you are using PowerShell, you may refer to botos/env/botos.env.ps1.sample instead.

Optionally, you may prefer having the file sourced on start-up of a shell session. This way, you no longer need to export the environment variables every time you start your development machine. If you are using shells like Bash and ZSH, the file can be sourced automatically on start-up by adding the line source /path/to/environment/file to one of your shell's session startup files (e.g. .bash_profile in Bash, and .zshenv in ZSH). If you are using PowerShell, the process is similar. The file can be automatically sourced by adding . \path\to\environment\file to your PowerShell profile. Your PowerShell profile's path can be found by running echo $Profile in a PowerShell instance. Note that the changes will only take effect when you start a new shell session.

Once you have set-up the environment files, you should create an admin user. Just run:

$ python manage.py createsuperuser

and fill out the requested information.

At this point, you can now run Botos. You can do so by simply running:

$ python manage.py runserver

Running Tests

Make sure that the development dependencies have been installed before running the tests. To run tests, just simply run:

$ cd /path/to/project/root/
$ python manage.py test  # or python3, if you're not using virtual environments.

Running Tests with Code Coverage

If you would like to have code coverage while running tests, just do the following:

$ cd /path/to/project/root/
$ coverage run manage.py test

To view the code coverage report, just do the following:

$ coverage report

If you want an HTML version of the report, just do the following:

$ coverage html

The command will produce an HTML version of the report that you can view in the browser with the link, file://</path/to/project/root>/htmlcov/index.html, where </path/to/project/root> is the absolute path to the root of the project.

Contributing

If you would like to contribute, please fork this repository first, and make your changes in the fork. Before working on a feature or a fix, please comment in the corresponding issue that you want to work on the feature or provide a fix for a bug. This is so that we can have a better idea on how to implement the feature or fix. If no issue is available, please write one, so that we still gather feedback.

Make sure to put all contribution work in your fork, and in a separate branch that is branched off the develop branch. The branch name should be prepended with feature/ if the contribution is a feature, fix/ if the contribution is a fix for a bug, or docs/ if the contribution is an improvement to the documentation.

When commiting changes, please use Gitmoji, and prepend them to the commit message. For example, a commit that adds a button to some web page should have a commit message that is something like:

:sparkles: Add awesome button to awesome web page.

Don't forget to pull in from the main repository to get the latest changes and to make merging easier. Do not forget to write tests for the feature or fix you are contributing. Contributions without tests will not be merged with the main repository.

Once you have completed your contribution, please a file a pull request so that we can review your contribution, and merge it when everything checks out.

Notes

Vote Encryption

Botos used to have a vote encryption feature. However, it was removed because it wasn't necessary, as the threat model for this system would make this feature overkill and would even add an additional overhead. It was not also used in a production environment. Botos is only expected to be used in elections where there is a low coercion risk, small-scale elections (the size of a high school or elementary school), where the system is run in a local area network, where voting takes place in a voting station, and where skilled malicious attackers are not prevalent nor non-existent. The threat model assumes that the system administration is the highest security risk for the system. The system administrator has the responsibility of ensuring that no data will be leaked nor modified, and the server configuration is robust enough to repel attacks. If the administrator is corrupt, he/she can rig the elections. Even encrypting votes would not provide adequate security as the system administrator still has access to keys to encrypt and decrypt votes. As such, the vote encryption was removed. It is better to focus on introducing or improving other features instead. The feature may be brought back in the server, but only if there is a reasonable demand for it. If you would like to use a more secure election system, I highly recommend checking Helios.

Licensing

Botos is licensed under the GNU General Public License v3. See LICENSE for details.

Some parts of this project are based on third-party code. See THIRD-PARTY-LICENSES.txt for details.

Contact

Sean Francis N. Ballais - @seanballais - [email protected]

botos's Issues

ValidationError during voting when the voter is assigned to a section that has also been assigned to another voter with a different batch from that of the voter

In the case that the voter has been assigned to a section that was also assigned to another voter with a different batch from that of the voter (which shouldn't happen), a ValidationError is raised with the message

The selected section is already used by another batch. No two batches can have the same section.

when the voter attempts to cast his votes. The votes get casted but the voter's has_voted flag does not get set to True. This should be fixed by showing an error message in the voting subview when the voter attempts to submit a vote. The aforementioned misconfiguration of voter accounts should also be checked for and have an error displayed when saving such voter accounts in the admin page.

Uploading pictures to the Botos database returns a Server 500 error.

Expected Behaviour

The database will update with the photo of the candidate.

Current Behaviour

The server returns an error code 500, and the HTTP logs from the nginx server return the error:

[error] 17858#17858: *3830 client intended to send too large body: 1288108 bytes, client: 112.198.103.11, server: 34.81.107.217, request: "POST /admin/core/candidateparty/2/change/ HTTP/1.1", host: "pshsevc-elections.ed.seanballais.com/admin/core/candidateparty/2/change/"

Steps to Reproduce

1. Setup the server as stated in the Botos Wiki on a Google Cloud Compute Engine VM
2. Upload users to the database
3. Attach a domain name to the server
4. Enable SSL/HTTPS on the server
5. Create a Candidate and upload a photo for the Candidate

Context

The server was deployed on a Google Cloud Compute Engine instance of machine type e2-medium running Debian 11 Bullseye with nginx and gunicorn.

Detailed Description

Changing the client_max_body_size in the http, server, and location blocks of the site has no effect on the issue. Similar issues such as https://stackoverflow.com/questions/39509355/nginx-client-max-body-size-has-no-effect-with-ssl-configured state that the issue appears in servers with SSL configured.
As stated from https://trac.nginx.org/nginx/ticket/1076, running the command
$ curl --insecure -H 'Content-Length: 10000000' https://127.0.0.1/ leads to the server giving no response until timeout, implying that there is no problem with the nginx configuration.

Possible Solution

As stated from the first StackOverflow question linked, requests may be rerouted to somewhere else that also uses nginx (in that case, AWS Elastic Beanstalk). This implies that the issue is in Google Cloud instead of the VM's nginx configuration. Possibly configuring a setting in Google Cloud Compute Engine may be able to fix the problem.