Advanced Customization

This page describes advanced customization options for the OpenWISP Docker images.

The table of contents below provides a quick overview of the specific areas that can be customized.

Creating the `customization` Directory

The following commands will create the directory structure required for adding customizations. Execute these commands in the same location as the docker-compose.yml file.

mkdir -p customization/configuration/django
touch customization/configuration/django/__init__.py
touch customization/configuration/django/custom_django_settings.py
mkdir -p customization/theme

You can also refer to the directory structure of Docker OpenWISP repository for an example.

Supplying Custom Django Settings

The customization/configuration/django directory created in the previous section is mounted at /opt/openwisp/openwisp/configuration in the dashboard, api, celery, celery_monitoring and celerybeat containers.

You can specify additional Django settings (e.g. SMTP configuration) in the customization/configuration/django/custom_django_settings.py file. OpenWISP will include these settings during the startup phase.

You can also put additional files in customization/configuration/django that need to be mounted at /opt/openwisp/openwisp/configuration in the containers.

Supplying Custom CSS and JavaScript Files

If you want to use your custom styles, add custom JavaScript you can follow the following guide.

Read about the option OPENWISP_ADMIN_THEME_LINKS. Please make ensure the value you have enter is a valid JSON and add the desired JSON in .env file. example:

# OPENWISP_ADMIN_THEME_LINKS = [
#     {
#         "type": "text/css",
#         "href": "/static/custom/css/custom-theme.css",
#         "rel": "stylesheet",
#         "media": "all",
#     },
#     {
#         "type": "image/x-icon",
#         "href": "/static/custom/bootload.png",
#         "rel": "icon",
#     },
#     {
#         "type": "image/svg+xml",
#         "href": "/static/ui/openwisp/images/openwisp-logo-small.svg",
#         "rel": "icons",
#     },
# ]
# JSON string of the above configuration:
OPENWISP_ADMIN_THEME_LINKS='[{"type": "text/css", "href": "/static/custom/css/custom-theme.css", "rel": "stylesheet", "media": "all"}, {"type": "image/x-icon", "href": "/static/custom/bootload.png", "rel": "icon"}, {"type": "image/svg+xml", "href": "/static/ui/openwisp/images/openwisp-logo-small.svg", "rel": "icons"}]'

Create your custom CSS / Javascript file in customization/theme directory created in the above section. E.g. customization/theme/static/custom/css/custom-theme.css.
Start the nginx containers.

Note

You can edit the styles / JavaScript files now without restarting the container, as long as file is in the correct place, it will be picked.
You can create a maintenance.html file inside the customize directory to have a custom maintenance page for scheduled downtime.

Supplying Custom uWSGI configuration

By default, you can only configure "processes", "threads" and "listen" settings of uWSGI using environment variables. If you want to configure more uWSGI settings, you can supply your uWSGI configuration by following these steps:

Create the uWSGI configuration file in the customization/configuration directory. For the sake of this example, let's assume the filename is custom_uwsgi.ini.
In dashboard and api services of docker-compose.yml, add volumes as following

services:
  dashboard:
    ... # other configuration
    volumes:
      ... # other volumes
      - ${PWD}/customization/configuration/custom_uwsgi.ini:/opt/openwisp/uwsgi.ini:ro
  api:
    ... # other configuration
    volumes:
      ... # other volumes
      - ${PWD}/customization/configuration/custom_uwsgi.ini:/opt/openwisp/uwsgi.ini:ro

Supplying Custom Nginx Configurations

Docker

Create nginx your configuration file.
Set NGINX_CUSTOM_FILE to True in .env file.
Mount your file in docker-compose.yml as following:

nginx:
  ...
  volumes:
      ...
      PATH/TO/YOUR/FILE:/etc/nginx/nginx.conf
  ...

Supplying Custom Freeradius Configurations

Note: /etc/raddb/clients.conf, /etc/raddb/radiusd.conf, /etc/raddb/sites-enabled/default, /etc/raddb/mods-enabled/, /etc/raddb/mods-available/ are the default files you may want to overwrite and you can find all of default files in build/openwisp_freeradius/raddb. The following are examples for including custom radiusd.conf and sites-enabled/default files.

Docker

Create file configuration files that you want to edit / add to your container.
Mount your file in docker-compose.yml as following:

nginx:
  ...
  volumes:
      ...
      PATH/TO/YOUR/RADIUSD:/etc/raddb/radiusd.conf
      PATH/TO/YOUR/DEFAULT:/etc/raddb/sites-enabled/default
  ...

Supplying Custom Python Source Code

You can build the images and supply custom python source code by creating a file named .build.env in the root of the repository, then set the variables inside .build.env file in <variable>=<value> format. Multiple variable should be separated in newline.

These are the variables that can be changed:

OPENWISP_MONITORING_SOURCE
OPENWISP_FIRMWARE_SOURCE
OPENWISP_CONTROLLER_SOURCE
OPENWISP_NOTIFICATION_SOURCE
OPENWISP_TOPOLOGY_SOURCE
OPENWISP_RADIUS_SOURCE
OPENWISP_IPAM_SOURCE
OPENWISP_USERS_SOURCE
OPENWISP_UTILS_SOURCE
DJANGO_X509_SOURCE
DJANGO_SOURCE

For example, if you want to supply your own Django and OpenWISP Controller source, your .build.env should be written like this:

DJANGO_SOURCE=https://github.com/<username>/Django/tarball/master
OPENWISP_CONTROLLER_SOURCE=https://github.com/<username>/openwisp-controller/tarball/master

Disabling Services

openwisp-dashboard: You cannot disable the openwisp-dashboard. It is the heart of OpenWISP and performs core functionalities.
openwisp-api: You cannot disable the openwisp-api. It is required for interacting with your devices.
openwisp-websocket: Removing this container will cause the system to not able to update real-time location for mobile devices.

If you want to disable a service, you can simply remove the container for that service, however, there are additional steps for some images:

openwisp-network-topology: Set the USE_OPENWISP_TOPOLOGY variable to False.
openwisp-firmware-upgrader : Set the USE_OPENWISP_FIRMWARE variable to False.
openwisp-monitoring : Set the USE_OPENWISP_MONITORING variable to False.
openwisp-radius : Set the USE_OPENWISP_RADIUS variable to False.
openwisp-postgres: If you are using a separate database instance,
- Ensure your database instance is reachable by the following OpenWISP containers: openvpn, freeradius, celerybeat, celery, celery_monitoring, websocket, api, dashboard.
- Ensure your database server supports GeoDjango. (Install PostGIS for PostgreSQL)
- Change the PostgreSQL Database Setting to point to your instances, if you are using SSL, remember to set DB_SSLMODE, DB_SSLKEY, DB_SSLCERT, DB_SSLROOTCERT.
- If you are using SSL, remember to mount volume containing the certificates and key in all the containers which contact the database server and make sure that the private key permission is 600 and owned by root:root.
- In your database, create database with name <DB_NAME>.
openwisp-postfix:
- Ensure your SMTP instance reachable by the OpenWISP containers.
- Change the email configuration variables to point to your instances.

Settings

Docker OpenWISP FAQs