openwisp-controller 0.7

Deploy it in production

An automated installer is available at ansible-openwisp2.

Dependencies

• Python >= 3.6

• OpenSSL

Install stable version from pypi

Install from pypi:

pip install openwisp-controller

Install development version

Install tarball:

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

Alternatively you can install via pip using git:

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

If you want to contribute, follow the instructions in Installing for development.

Setup (integrate in an existing django project)

INSTALLED_APPS and EXTENDED_APPS (an internal openwisp2 setting) in settings.py should look like the following (ordering is important):

INSTALLED_APPS = [
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django.contrib.gis',
    # openwisp2 admin theme
    # (must be loaded here)
    'openwisp_utils.admin_theme',
    # all-auth
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    'django_extensions',
    # openwisp2 module
    'openwisp_controller.config',
    'openwisp_controller.pki',
    'openwisp_controller.geo',
    'openwisp_controller.connection',
    'openwisp_users',
    # admin
    'django.contrib.admin',
    # other dependencies
    'sortedm2m',
    'reversion',
    'leaflet',
    # rest framework
    'rest_framework',
    'rest_framework_gis',
    # channels
    'channels',
]

EXTENDED_APPS = ('django_netjsonconfig', 'django_x509', 'django_loci',)

Ensure you are using one of the available geodjango backends, eg:

DATABASES = {
    'default': {
        'ENGINE': 'django.contrib.gis.db.backends.spatialite',
        'NAME': 'openwisp-controller.db',
    }
}

Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS in your settings.py:

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

Add openwisp_utils.loaders.DependencyLoader to template loaders and openwisp_utils.admin_theme.context_processor.menu_items to context processors in the TEMPLATES setting of settings.py:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
                'openwisp_utils.loaders.DependencyLoader',
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
                'openwisp_utils.admin_theme.context_processor.menu_items'
            ],
        },
    }
]

Add the following settings to settings.py:

FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

ASGI_APPLICATION = 'openwisp_controller.geo.channels.routing.channel_routing'
CHANNEL_LAYERS = {
    'default': {
        'BACKEND': 'channels.layers.InMemoryChannelLayer'
    },
}

LOGIN_REDIRECT_URL = 'admin:index'
ACCOUNT_LOGOUT_REDIRECT_URL = LOGIN_REDIRECT_URL

urls.py:

from django.conf.urls import include, url
from django.contrib import admin
from django.contrib.staticfiles.urls import staticfiles_urlpatterns

urlpatterns = [
    url(r'^admin/', include(admin.site.urls)),
    url(r'', include('openwisp_controller.urls')),
]

urlpatterns += staticfiles_urlpatterns()

Signals

is_working_changed

Path: openwisp_controller.connection.signals.is_working_changed

Arguments:

• instance: instance of DeviceConnection

• is_working: value of DeviceConnection.is_working

• old_is_working: previous value of DeviceConnection.is_working, either None (for new connections), True or False

• failure_reason: error message explaining reason for failure in establishing connection

This signal is emitted every time DeviceConnection.is_working changes.

It is not triggered when the device is created for the first time.

Settings

(
  ('openwisp_controller.connection.connectors.ssh.Ssh', 'SSH'),
)

(
  ('openwisp_controller.connection.connectors.openwrt.ssh.OpenWrt', 'OpenWRT SSH'),
)

{
  'netjsonconfig.OpenWrt': OPENWISP_UPDATE_STRATEGIES[0][0],
}

Installing for development

Install the system dependencies:

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

Launch Redis:

docker-compose up -d redis

Install your forked repo:

git clone git://github.com/<your_fork>/openwisp-controller
cd openwisp-controller/
python setup.py develop

Install development dependencies (optional):

./install-dev.sh

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:

./run-qa-checks
./runtests.py

Install and run on docker

Build from the Dockerfile:

docker-compose build

Run the docker container:

docker-compose up

Troubleshooting Steps

You may encounter some issues while installing GeoDjango.

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

Talks

• OpenWISP2 - a self hosted solution to control OpenWRT/LEDE devices (FOSDEM 2017)

Contributing

Please read the OpenWISP contributing guidelines and also keep in mind the following:

1. Announce your intentions in the OpenWISP Mailing List

2. Fork this repo and install it

3. Follow PEP8, Style Guide for Python Code

4. Write code

5. Write tests for your code

6. Ensure all tests pass

7. Ensure test coverage does not decrease

8. Document your changes

9. Send pull request

Changelog

See CHANGES.

License

See LICENSE.