Developer Installation Instructions

Note

This page is for developers who want to customize or extend OpenWISP Controller, whether for bug fixes, new features, or contributions.

For user guides and general information, please see:

Installing for Development

Install the system dependencies:

sudo apt update
sudo apt install -y sqlite3 libsqlite3-dev openssl libssl-dev
sudo apt install -y gdal-bin libproj-dev libgeos-dev libspatialite-dev libsqlite3-mod-spatialite
sudo apt install -y chromium-browser

Fork and clone the forked repository:

git clone git://github.com/<your_fork>/openwisp-controller

Navigate into the cloned repository:

cd openwisp-controller/

Launch Redis and PostgreSQL:

docker-compose up -d redis postgres

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 .
pip install -r requirements-test.txt
sudo npm install -g jshint stylelint

Install WebDriver for Chromium for your browser version from https://chromedriver.chromium.org/home and Extract chromedriver to one of directories from your $PATH (example: ~/.local/bin/).

Create database:

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

Launch celery worker (for background jobs):

celery -A openwisp2 worker -l info

Launch development server:

./manage.py runserver 0.0.0.0:8000

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

Run tests with:

./runtests.py --parallel

Some tests, such as the Selenium UI tests, require a PostgreSQL database to run. If you don't have a PostgreSQL database running on your system, you can use the Docker Compose configuration provided in this repository. Once set up, you can run these specific tests as follows:

# Run database tests against PostgreSQL backend
POSTGRESQL=1 ./runtests.py --parallel

# Run only specific selenium tests classes
cd tests/
DJANGO_SETTINGS_MODULE=openwisp2.postgresql_settings ./manage.py test openwisp_controller.config.tests.test_selenium.TestDeviceAdmin

Run quality assurance tests with:

./run-qa-checks

Alternative Sources

Pypi

To install the latest Pypi:

pip install openwisp-controller

Github

To install the latest development version tarball via HTTPs:

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

Alternatively you can use the git protocol:

pip install -e git+git://github.com/openwisp/openwisp-controller#egg=openwisp_controller

Install and Run on Docker

Warning

This Docker image is for development purposes only.

For the official OpenWISP Docker images, see: docker-openwisp.

Build from the Dockerfile:

docker-compose build

Run the docker container:

docker-compose up

Troubleshooting Steps for Common Installation Issues

You may encounter some issues while installing GeoDjango.

Unable to Load SpatiaLite library Extension?

If you are incurring in the following exception:

django.core.exceptions.ImproperlyConfigured: Unable to load the SpatiaLite library extension

You need to specify SPATIALITE_LIBRARY_PATH in your settings.py as explained in django documentation regarding how to install and configure spatialte.

Having Issues with Other Geospatial Libraries?

Please refer troubleshooting issues related to geospatial libraries.

Important

If you want to add OpenWISP Controller to an existing Django project, then you can refer to the test project in the openwisp-controller repository.

Developer Docs

Code Utilities