Developer Installation Instructions

Note

This documentation page is aimed at developers who want to customize, change or extend the code of OpenWISP Utils in order to modify its behavior (e.g.: for personal or commercial purposes or to fix a bug, implement a new feature or contribute to the project in general).

If you aren't a developer and you are looking for information on how to use OpenWISP, please refer to:

The following diagram illustrates the role of the Utils module within the OpenWISP architecture.

OpenWISP Architecture: Utils module

OpenWISP Architecture: highlighted utils module

Important

For an enhanced viewing experience, open the image above in a new browser tab.

Refer to Architecture, Modules, Technologies for more information.

Installing for Development

Install the system dependencies:

sudo apt-get install sqlite3 libsqlite3-dev

# For running E2E Selenium tests (Firefox is the default browser)
sudo apt install firefox chromium

Fork the openwisp-utils repository on GitHub, then clone your fork. Replace YOUR_GITHUB_USERNAME with your GitHub username:

git clone git@github.com:YOUR_GITHUB_USERNAME/openwisp-utils.git

Navigate into the cloned repository:

cd openwisp-utils/

Setup and activate a virtual-environment (we'll be using virtualenv):

python -m virtualenv env
source env/bin/activate

Make sure that your base python packages are up to date before moving to the next step:

pip install -U pip wheel setuptools

Install development dependencies:

pip install -e ".[all]"
pip install -r requirements-test.txt
sudo npm install -g prettier

Set up the git pre-push hook to run tests and QA checks automatically right before the git push action, so that if anything fails the push operation will be aborted:

openwisp-pre-push-hook --install

Create database:

cd tests/
./manage.py migrate
./manage.py createsuperuser

Launch development server:

./manage.py runserver

You can access the admin interface at http://127.0.0.1:8000/admin/.

Run tests with:

./runtests

Run quality assurance tests with:

./run-qa-checks

Alternative Sources

Pypi

To install the latest Pypi:

pip install openwisp-utils

Github

To install the latest development version tarball via HTTPs:

pip install https://github.com/openwisp/openwisp-utils/tarball/master

Alternatively you can install the latest development version from Git:

pip install -e git+https://github.com/openwisp/openwisp-utils#egg=openwisp_utils