Ruralwater

GPLv3 license

Purpose of the project

Open source webapp to allow the design of rural water supplies for non-specialists.

Motivation

This project exists because the design of rural water supplies poses challenges to optimize the investment costs and limit the running costs.
This may be particularly interesting in the case of humanitarian interventions (say in rural communities of Africa, Asia, Latin America), where the funds may be limited and where personnel deployed by humanitarian organizations may not have an engineering professional background.
More information on our website and its quickstart (2019 version, will be updated soon).

How to install ‘ruralwater’ on your local machine

These steps will get you a copy of the project up and running on your local machine for development and testing purposes.
Prerequisites:
  • Python 3.7+

  • Redis

Remark: if, for any reason, you do not want to install redis on your local machine, then, once you have cloned the repository, edit the following setting inside file webapp.core.settings.redis.py: USE_REDIS = True and set it to False.
Installation:
We have created a setup script that should install ruralwater on your local machine in a single command. If this fails, we detailed below the manual installation process.
Once python (and optionally redis) are installed on your local machine and you have cloned the repository, follow the steps below:
  • clone the development branch on you local machine

  • run the script setup_linux_complete.sh (linux) or setup_win_complete.ps1 (windows)

  • Navigate to localhost (http://127.0.0.1:8000/)

You will now see “ruralwater” up and running.
If anything went wrong, then apologise us and follow the steps below.

Manual installation

Once python (and optionally redis) are installed on your local machine and you have cloned the repository, follow the steps below:
  • clone the “development” branch on you local machine

  • create and activate a virtual environment

  • install the requirements at requirements/development.txt

  • run the script setup_linux_database.sh (linux) or setup_win_database.ps1 (windows)

  • Navigate to localhost (http://127.0.0.1:8000/)

You will now see “ruralwater” up and running.

More specifically, setup_*_database implements the following operations:
  • generates the database (using the django framework)

  • populates the database with the hydraulic hardware data

  • creates a superuser and two mock users:

    1. ‘demo’, who is the superuser, with password: pippo121

    2. ‘cat’, with password: meow

    3. ‘dog’, with password: bark

What is ‘hydraulic hardware’? The hydraulic hardware data are the data of the commercially available water pipes, and a selection of some water pumps and diesel engines available from manufacturers. Data include bores of pipes and plate data of pumps and engines. These data are needed since the software algorithms needs them to run its algorithms.

Contributing

The mission of this project is stated at our website.
Additional information may be found in the following documents:
  • XXX for an introduction to the ‘application programming interface’ exposed by the ‘business logic’

  • For contributors more interested in “test-driven development” XXX provides the description of the tests currently included in this repository.

More documentation on the project can be found here:

Current status of the project

The project at present (october 2020) is a ‘proof of concept’. Contributions are welcomed especially in the following fields:
  • the algorithm to optimize the design of dendridic gravity-fed water supplies

  • the design of the user interface, more specifically the javascript for the client side controls to define the water supply.|

Tech/framework used

Ruralwater is built with:

Tests

If you desire to test the entire webapp, do the following:
  • cd into the ‘webapp’ folder

  • run: python manage.py runserver

  • run: python manage.py test

Remark: it is necessary to run the server before running the tests, as it is shown in the above code snippet, becasue the tests must access those “hydraulic hardware data” referred to above (section hydraulic_hardware)
More information about testing may be found in the testing forlder and specifically inside the file howto_casestudies.md.
If you desire to simply thest the ‘business logic’ (not the entire webapp), then do the following:
  • cd into the ‘webapp’ folder

  • run: python manage.py runserver

Authors