Developer Installation Instructions

Note

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

For user guides and general information, please see:

Requirements

Install Dependencies

Install spatialite and sqlite:

sudo apt-get install sqlite3 libsqlite3-dev openssl libssl-dev
sudo apt-get install gdal-bin libproj-dev libgeos-dev libspatialite-dev

Installing for Development

Fork and clone the forked repository:

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

Navigate into the cloned repository:

cd openwisp-firmware-upgrader/

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 prettier

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 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 celery and celery-beat with the following commands (separate terminal windows are needed):

# (cd tests)
celery -A openwisp2 worker -l info
celery -A openwisp2 beat -l info

Run quality assurance tests with:

./run-qa-checks

Run tests with (make sure you have the selenium dependencies installed locally first):

# standard tests
./runtests.py

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 only specific selenium tests classes
cd tests/
DJANGO_SETTINGS_MODULE=openwisp2.postgresql_settings ./manage.py test openwisp_firmware_upgrader.tests.test_selenium.TestDeviceAdmin

# tests for the sample app
SAMPLE_APP=1 ./runtests.py --keepdb --failfast

When running the last line of the previous example, the environment variable SAMPLE_APP activates the app in /tests/openwisp2/sample_firmware_upgrader/ which is a simple django app that extends openwisp-firmware-upgrader with the sole purpose of testing its extensibility, for more information regarding this concept, read Extending OpenWISP Firmware Upgrader.

Important

If you want to add openwisp-firmware-upgrader to an existing Django project, then you can take reference from the test project in openwisp-firmware-upgrader repository