From c71eba68d832792972c11dc0638c25d75ae507a8 Mon Sep 17 00:00:00 2001 From: Adityashandilya555 Date: Sat, 4 Oct 2025 09:15:57 +0530 Subject: [PATCH 1/5] [deps] Migrate from django-celery-email to django-post-office #477 Replaced archived django-celery-email with actively maintained django-post-office for async email handling. - Updated requirements.txt: django-celery-email -> django-post-office - Changed email backend configuration in Dockerfile - Updated settings.py to use post_office app conditionally Fixes #477 --- images/common/openwisp/settings.py | 4 ++-- images/openwisp_base/Dockerfile | 2 +- images/openwisp_base/requirements.txt | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/images/common/openwisp/settings.py b/images/common/openwisp/settings.py index cb3cd21b..f032faa6 100644 --- a/images/common/openwisp/settings.py +++ b/images/common/openwisp/settings.py @@ -436,8 +436,8 @@ INSTALLED_APPS.remove("openwisp_monitoring.device") if "openwisp_monitoring.check" in INSTALLED_APPS: INSTALLED_APPS.remove("openwisp_monitoring.check") -if EMAIL_BACKEND == "djcelery_email.backends.CeleryEmailBackend": - INSTALLED_APPS.append("djcelery_email") +if EMAIL_BACKEND == "post_office.EmailBackend": + INSTALLED_APPS.append("post_office") if env_bool(os.environ.get("METRIC_COLLECTION", "True")): INSTALLED_APPS.append("openwisp_utils.metric_collection") diff --git a/images/openwisp_base/Dockerfile b/images/openwisp_base/Dockerfile index 7c5623bc..3dd0bd1a 100644 --- a/images/openwisp_base/Dockerfile +++ b/images/openwisp_base/Dockerfile @@ -119,7 +119,7 @@ ENV DASHBOARD_APP_SERVICE=dashboard \ INFLUXDB_HOST=influxdb \ INFLUXDB_PORT=8086 \ INFLUXDB_DEFAULT_RETENTION_POLICY=26280h0m0s \ - EMAIL_BACKEND=djcelery_email.backends.CeleryEmailBackend \ + EMAIL_BACKEND=post_office.EmailBackend \ EMAIL_HOST=postfix \ EMAIL_HOST_PORT=25 \ EMAIL_HOST_USER="" \ diff --git a/images/openwisp_base/requirements.txt b/images/openwisp_base/requirements.txt index c6e6c233..76af1983 100644 --- a/images/openwisp_base/requirements.txt +++ b/images/openwisp_base/requirements.txt @@ -7,7 +7,7 @@ supervisor~=4.2 # allows 4.x and > 4.2 django-cors-headers~=4.7 django-pipeline~=4.0 uwsgi~=2.0.30 -django-celery-email~=3.0.0 +django-post-office~=3.8.0 tldextract~=5.3.0 # these add support for object storage # (eg: Amazon S3, GCS) From 01e4e233575a10ec9031dcb4fa117098d9378fbf Mon Sep 17 00:00:00 2001 From: Adityashandilya555 Date: Sat, 11 Oct 2025 23:23:09 +0530 Subject: [PATCH 2/5] [deps] Migrate from django-celery-email to django-celery-email-reboot #477 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The archived django-celery-email package has been replaced with django-celery-email-reboot, a maintained fork that provides Django 4.x/5.x compatibility. This is a drop-in replacement with identical API. Changes: - Updated requirements.txt to use django-celery-email-reboot>=4.1.0,<5.0.0 - Changed EMAIL_BACKEND to djcelery_email.backends.CeleryEmailBackend - Updated settings.py to check for djcelery_email backend Testing performed following maintainer's approach: - Built all Docker images successfully with django-celery-email-reboot 4.1.0 - Tested email flow: docker compose run dashboard python manage.py sendtestemail - Verified postfix logs showing successful email pipeline: Django → Celery → Postfix (queue ID 95C4120370E8) - Email queued and delivery attempted successfully The entire email pipeline is working correctly with the new package. Fixes #477 --- images/common/openwisp/settings.py | 4 ++-- images/openwisp_base/Dockerfile | 2 +- images/openwisp_base/requirements.txt | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/images/common/openwisp/settings.py b/images/common/openwisp/settings.py index 21383039..bdf16b78 100644 --- a/images/common/openwisp/settings.py +++ b/images/common/openwisp/settings.py @@ -450,8 +450,8 @@ INSTALLED_APPS.remove("openwisp_monitoring.device") if "openwisp_monitoring.check" in INSTALLED_APPS: INSTALLED_APPS.remove("openwisp_monitoring.check") -if EMAIL_BACKEND == "post_office.EmailBackend": - INSTALLED_APPS.append("post_office") +if EMAIL_BACKEND == "djcelery_email.backends.CeleryEmailBackend": + INSTALLED_APPS.append("djcelery_email") if env_bool(os.environ.get("METRIC_COLLECTION", "True")): INSTALLED_APPS.append("openwisp_utils.metric_collection") diff --git a/images/openwisp_base/Dockerfile b/images/openwisp_base/Dockerfile index 3dd0bd1a..7c5623bc 100644 --- a/images/openwisp_base/Dockerfile +++ b/images/openwisp_base/Dockerfile @@ -119,7 +119,7 @@ ENV DASHBOARD_APP_SERVICE=dashboard \ INFLUXDB_HOST=influxdb \ INFLUXDB_PORT=8086 \ INFLUXDB_DEFAULT_RETENTION_POLICY=26280h0m0s \ - EMAIL_BACKEND=post_office.EmailBackend \ + EMAIL_BACKEND=djcelery_email.backends.CeleryEmailBackend \ EMAIL_HOST=postfix \ EMAIL_HOST_PORT=25 \ EMAIL_HOST_USER="" \ diff --git a/images/openwisp_base/requirements.txt b/images/openwisp_base/requirements.txt index 077db911..62094753 100644 --- a/images/openwisp_base/requirements.txt +++ b/images/openwisp_base/requirements.txt @@ -7,7 +7,7 @@ supervisor>=4.3.0,<4.4.0 django-cors-headers>=4.9.0,<4.10.0 django-pipeline>=4.1.0,<4.2.0 uwsgi>=2.0.30,<2.1.0 -django-post-office>=3.8.0,<3.9.0 +django-celery-email-reboot>=4.1.0,<5.0.0 tldextract>=5.3.0,<5.4.0 # these add support for object storage # (eg: Amazon S3, GCS) From 6802ce1b81281eceef02c378ab605be64ba5b1cd Mon Sep 17 00:00:00 2001 From: Adityashandilya555 Date: Sun, 26 Oct 2025 11:31:39 +0530 Subject: [PATCH 3/5] [enhancement] Use dashboard domain for monitoring chart loading This change addresses issue #526 by making monitoring charts load from the dashboard domain instead of the API domain. This prevents SSL certificate issues that can confuse new users when the API domain doesn't have a trusted certificate. Changes: - Added DASHBOARD_BASEURL configuration variable - Changed OPENWISP_MONITORING_API_BASEURL to use dashboard domain - Chart loading now uses the same domain as the dashboard interface Fixes #526 --- images/openwisp_dashboard/module_settings.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/images/openwisp_dashboard/module_settings.py b/images/openwisp_dashboard/module_settings.py index 6c092abf..1c4f1c69 100644 --- a/images/openwisp_dashboard/module_settings.py +++ b/images/openwisp_dashboard/module_settings.py @@ -101,6 +101,7 @@ else f":{HTTP_PORT}" ) API_BASEURL = f'{HTTP_SCHEME}://{os.environ["API_DOMAIN"]}{HTTP_PORT}' +DASHBOARD_BASEURL = f'{HTTP_SCHEME}://{os.environ["DASHBOARD_DOMAIN"]}{HTTP_PORT}' OPENWISP_NETWORK_TOPOLOGY_API_URLCONF = "openwisp_network_topology.urls" OPENWISP_MONITORING_API_URLCONF = "openwisp_monitoring.urls" @@ -108,6 +109,6 @@ OPENWISP_NETWORK_TOPOLOGY_API_BASEURL = API_BASEURL OPENWISP_NOTIFICATIONS_HOST = API_BASEURL OPENWISP_CONTROLLER_API_HOST = API_BASEURL -OPENWISP_MONITORING_API_BASEURL = API_BASEURL +OPENWISP_MONITORING_API_BASEURL = DASHBOARD_BASEURL OPENWISP_FIRMWARE_API_BASEURL = API_BASEURL OPENWISP_RADIUS_API_BASEURL = API_BASEURL From 57346054cc31e1b85e4cecfbf372141428b0aacc Mon Sep 17 00:00:00 2001 From: Adityashandilya555 Date: Tue, 9 Dec 2025 12:18:09 +0530 Subject: [PATCH 4/5] [qa] Fix RST formatting --- CHANGES.rst | 49 ++--- README.rst | 10 +- docs/developer/instructions.rst | 31 +-- docs/index.rst | 5 +- docs/user/architecture.rst | 5 +- docs/user/customization.rst | 49 +++-- docs/user/faq.rst | 20 +- docs/user/quickstart.rst | 22 ++- docs/user/settings.rst | 329 +++++++++++++++++--------------- 9 files changed, 283 insertions(+), 237 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 9ef0017e..903a0f7b 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,11 +1,13 @@ -Changelog -========= +########### + Changelog +########### -Version 25.10.0 [2025-10-24] ----------------------------- +****************************** + Version 25.10.0 [2025-10-24] +****************************** Features -~~~~~~~~ +======== - Added support for non-default external ports in the Nginx container `#496 `_. @@ -18,10 +20,10 @@ Features `_. Changes -~~~~~~~ +======= Dependencies -++++++++++++ +------------ - Upgraded to OpenWISP Users 1.2.x (see `changelog `__). @@ -61,7 +63,7 @@ Dependencies - Bumped ``boto3>=1.40.49,<1.41.0``. Bugfixes -~~~~~~~~ +======== - Fixed permissions issues in the Postfix container. - Fixed FreeRADIUS container exit caused by global write permissions. @@ -73,11 +75,12 @@ Bugfixes `_. - Updated auto-install script to suggest the correct VPN hostname. -Version 24.11.2 [2024-12-18] ----------------------------- +****************************** + Version 24.11.2 [2024-12-18] +****************************** Bugfixes -~~~~~~~~ +======== - Resolved an issue in the ``docker-compose`` configuration for the ``openvpn`` service by adding the ``/dev/net/tun`` device. @@ -91,19 +94,21 @@ Bugfixes ``postfix~=3.9.1-r0``. - Bumped ``boto3~=1.35.82``. -Version 24.11.1 [2024-11-27] ----------------------------- +****************************** + Version 24.11.1 [2024-11-27] +****************************** Bugfixes -~~~~~~~~ +======== - Updated ``__openwisp_version__`` to ``24.11.1``. -Version 24.11.0 [2024-11-27] ----------------------------- +****************************** + Version 24.11.0 [2024-11-27] +****************************** Features -~~~~~~~~ +======== - Added a default topology for the default VPN. - Added default credentials and SSH key template. @@ -122,10 +127,10 @@ Features `_. Changes -~~~~~~~ +======= Dependencies -++++++++++++ +------------ - Upgraded to OpenWISP Users 1.1.x (see `changelog `__). @@ -153,7 +158,7 @@ Dependencies ``python:3.10.0-slim-buster``. Backward Incompatible Changes -+++++++++++++++++++++++++++++ +----------------------------- - Merged the OpenWISP RADIUS container into the dashboard and API. - The ``CRON_DELETE_OLD_RADIUSBATCH_USERS`` variable now expects the @@ -164,7 +169,7 @@ Backward Incompatible Changes ``CRON_DELETE_OLD_RADIUSBATCH_USERS``. Other Changes -+++++++++++++ +------------- - Changed cron to update OpenVPN revoke list daily at midnight. - Added admin URLs to the API container. @@ -178,7 +183,7 @@ Other Changes - Disabled nginx ``server_tokens`` for improved security. Bugfixes -~~~~~~~~ +======== - Fixed OpenVPN cron script to download configuration at the correct path. - Fixed project configuration issues in the OpenWISP RADIUS module. diff --git a/README.rst b/README.rst index 8a0566b5..cfe6daf8 100644 --- a/README.rst +++ b/README.rst @@ -1,5 +1,6 @@ -Docker-OpenWISP -=============== +################# + Docker-OpenWISP +################# .. image:: https://github.com/openwisp/docker-openwisp/workflows/Automation%20Tests/badge.svg :target: https://github.com/openwisp/docker-openwisp/actions?query=workflow%3A%22Automation+Tests%22 @@ -23,8 +24,9 @@ in mind. .. image:: https://raw.githubusercontent.com/openwisp/docker-openwisp/master/docs/images/portainer-docker-list.png :target: https://raw.githubusercontent.com/openwisp/docker-openwisp/master/docs/images/portainer-docker-list.png -Documentation -------------- +*************** + Documentation +*************** - `Usage documentation `_ - `Developer documentation diff --git a/docs/developer/instructions.rst b/docs/developer/instructions.rst index 232b83bc..d0c08255 100644 --- a/docs/developer/instructions.rst +++ b/docs/developer/instructions.rst @@ -1,5 +1,6 @@ -Developer Docs -============== +################ + Developer Docs +################ .. include:: ../partials/developer-docs.rst @@ -9,8 +10,9 @@ Developer Docs .. include:: ../partials/updating-host-file.rst -Building and Running Images ---------------------------- +***************************** + Building and Running Images +***************************** 1. Install Docker. 2. In the root directory of the repository, run ``make develop``. Once the @@ -28,8 +30,9 @@ Building and Running Images by ``docker-openwisp``, please refer to the :ref:`makefile options `. -Running Tests -------------- +*************** + Running Tests +*************** You can run tests using either ``geckodriver`` (Firefox) or ``chromedriver`` (Chromium). @@ -37,14 +40,14 @@ You can run tests using either ``geckodriver`` (Firefox) or **Chromium is preferred as it also checks for console log errors.** Using Chromedriver -~~~~~~~~~~~~~~~~~~ +================== 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/``). Using Geckodriver -~~~~~~~~~~~~~~~~~ +================= Install Geckodriver for Firefox for your browser version from https://github.com/mozilla/geckodriver/releases and extract @@ -52,7 +55,7 @@ https://github.com/mozilla/geckodriver/releases and extract ``~/.local/bin/``). Finish Setup and Run Tests -~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================== 1. Install test requirements: @@ -87,8 +90,9 @@ Finish Setup and Run Tests python3 tests/runtests.py . -Run Quality Assurance Checks ----------------------------- +****************************** + Run Quality Assurance Checks +****************************** We use `shfmt `__ to format shell scripts and `hadolint `__ to @@ -109,8 +113,9 @@ To run quality assurance checks, use the ``run-qa-checks`` script: .. _docker_make_options: -Makefile Options ----------------- +****************** + Makefile Options +****************** Most commonly used: diff --git a/docs/index.rst b/docs/index.rst index 6fc7123e..c2381e40 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,6 @@ -Docker OpenWISP -=============== +################# + Docker OpenWISP +################# .. seealso:: diff --git a/docs/user/architecture.rst b/docs/user/architecture.rst index b35ee794..81705c1b 100644 --- a/docs/user/architecture.rst +++ b/docs/user/architecture.rst @@ -1,5 +1,6 @@ -Architecture -============ +############## + Architecture +############## A typical OpenWISP installation is made of multiple components (e.g. application servers, background workers, web servers, database, messaging diff --git a/docs/user/customization.rst b/docs/user/customization.rst index df0afa06..d7e9ffeb 100644 --- a/docs/user/customization.rst +++ b/docs/user/customization.rst @@ -1,5 +1,6 @@ -Advanced Customization -====================== +######################## + Advanced Customization +######################## This page describes advanced customization options for the OpenWISP Docker images. @@ -11,8 +12,9 @@ areas that can be customized. :depth: 1 :local: -Creating the ``customization`` Directory ----------------------------------------- +****************************************** + 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 @@ -32,8 +34,9 @@ for an example. .. _docker_custom_django_settings: -Supplying Custom Django Settings --------------------------------- +********************************** + Supplying Custom Django Settings +********************************** The ``customization/configuration/django`` directory created in the previous section is mounted at ``/opt/openwisp/openwisp/configuration`` in @@ -48,8 +51,9 @@ 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 ------------------------------------------ +******************************************* + Supplying Custom CSS and JavaScript Files +******************************************* If you want to use your custom styles, add custom JavaScript you can follow the following guide. @@ -95,8 +99,9 @@ follow the following guide. 2. You can create a ``maintenance.html`` file inside the ``customize`` directory to have a custom maintenance page for scheduled downtime. -Supplying Custom uWSGI configuration ------------------------------------- +************************************** + Supplying Custom uWSGI configuration +************************************** By default, you can only configure :ref:`"processes", "threads" and "listen" settings of uWSGI using environment variables @@ -125,11 +130,12 @@ supply your uWSGI configuration by following these steps: .. _docker_nginx: -Supplying Custom Nginx Configurations -------------------------------------- +*************************************** + Supplying Custom Nginx Configurations +*************************************** Docker -~~~~~~ +====== 1. Create nginx your configuration file. 2. Set ``NGINX_CUSTOM_FILE`` to ``True`` in ``.env`` file. @@ -146,8 +152,9 @@ Docker .. _docker_freeradius: -Supplying Custom Freeradius Configurations ------------------------------------------- +******************************************** + Supplying Custom Freeradius Configurations +******************************************** Note: ``/etc/raddb/clients.conf``, ``/etc/raddb/radiusd.conf``, ``/etc/raddb/sites-enabled/default``, ``/etc/raddb/mods-enabled/``, @@ -159,7 +166,7 @@ including custom ``radiusd.conf`` and ``sites-enabled/default`` files. .. _docker-1: Docker -~~~~~~ +====== 1. Create file configuration files that you want to edit / add to your container. @@ -175,8 +182,9 @@ Docker PATH/TO/YOUR/DEFAULT:/etc/raddb/sites-enabled/default ... -Supplying Custom Python Source Code ------------------------------------ +************************************* + 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 @@ -206,8 +214,9 @@ written like this: DJANGO_SOURCE=https://github.com//Django/tarball/master OPENWISP_CONTROLLER_SOURCE=https://github.com//openwisp-controller/tarball/master -Disabling Services ------------------- +******************** + Disabling Services +******************** - ``openwisp-dashboard``: You cannot disable the openwisp-dashboard. It is the heart of OpenWISP and performs core functionalities. diff --git a/docs/user/faq.rst b/docs/user/faq.rst index 3f4d8a6e..a68fa5c6 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -1,12 +1,14 @@ -Docker OpenWISP FAQs -==================== +###################### + Docker OpenWISP FAQs +###################### .. contents:: **Table of Contents**: :depth: 1 :local: -1. Setup fails, it couldn't find the images on DockerHub? ---------------------------------------------------------- +*********************************************************** + 1. Setup fails, it couldn't find the images on DockerHub? +*********************************************************** Answer: The setup requires following ports and destinations to be unblocked, if you are using a firewall or any external control to block @@ -25,8 +27,9 @@ traffic, please whitelist: 8 0 tcp 25 172.18.0.0/16 ``/usr/bin/docker-proxy`` = ====== ======== ========== ====================== ===================================== -2. Makefile failed without any information, what's wrong? ---------------------------------------------------------- +*********************************************************** + 2. Makefile failed without any information, what's wrong? +*********************************************************** Answer: You are using an old version of a requirement, please consider upgrading: @@ -46,8 +49,9 @@ upgrading: $ uname -v # kernel-version #1 SMP Debian 4.19.181-1 (2021-03-19) -3. Can I run the containers as the ``root`` or ``docker`` ---------------------------------------------------------- +*********************************************************** + 3. Can I run the containers as the ``root`` or ``docker`` +*********************************************************** No, please do not run the Docker containers as these users. diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index e8eb4b78..8a0a1099 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -1,5 +1,6 @@ -Quick Start Guide -================= +################### + Quick Start Guide +################### This page explains how to deploy OpenWISP using the docker images provided by Docker OpenWISP. @@ -8,15 +9,16 @@ by Docker OpenWISP. :depth: 1 :local: -Available Images ----------------- +****************** + Available Images +****************** The images are hosted on `Docker Hub `__ and `GitLab Container Registry `__. Image Tags -~~~~~~~~~~ +========== All images are tagged using the following convention: @@ -31,8 +33,9 @@ edge This is the development version of OpenWISP. On Github, this corresponds to the current master branch. ====== ========================================================= -Auto Install Script -------------------- +********************* + Auto Install Script +********************* .. figure:: ../images/auto-install.png :target: ../../_images/auto-install.png @@ -98,8 +101,9 @@ by using the following command - Still facing errors while installation? Please :doc:`read the FAQ `. -Using Docker Compose --------------------- +********************** + Using Docker Compose +********************** This setup is suitable for single-server setup requirements. It is quicker and requires less prior knowledge about OpenWISP & networking. diff --git a/docs/user/settings.rst b/docs/user/settings.rst index 5bc46d9c..22562e53 100644 --- a/docs/user/settings.rst +++ b/docs/user/settings.rst @@ -1,5 +1,6 @@ -Settings -======== +########## + Settings +########## The OpenWISP Docker images are designed for customization. You can easily modify environment variables to tailor the containers to your needs. @@ -31,8 +32,9 @@ Additionally, you can search for the following prefixes: .. _docker_essential_env: -Essential ---------- +*********** + Essential +*********** You will need to adapt these values to get the docker images working properly on your system. @@ -40,7 +42,7 @@ properly on your system. .. _dashboard_domain: ``DASHBOARD_DOMAIN`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Domain on which you want to access OpenWISP dashboard. - **Valid Values:** Any valid domain. @@ -49,7 +51,7 @@ properly on your system. .. _api_domain: ``API_DOMAIN`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Domain on which you want to access OpenWISP APIs. - **Valid Values:** Any valid domain. @@ -58,14 +60,14 @@ properly on your system. .. _vpn_domain: ``VPN_DOMAIN`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Valid domain / IP address to reach the OpenVPN server. - **Valid Values:** Any valid domain or IP address. - **Default:** ``openvpn.example.com``. ``TZ`` -~~~~~~ +====== - **Explanation:** Sets the timezone for the OpenWISP containers. - **Valid Values:** Find list of timezone database `here @@ -73,7 +75,7 @@ properly on your system. - **Default:** ``UTC``. ``CERT_ADMIN_EMAIL`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Required by certbot. Email used for registration and recovery contact. @@ -81,7 +83,7 @@ properly on your system. - **Default:** ``example@example.com``. ``SSL_CERT_MODE`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Flag to enable or disable HTTPS. If it is set to ``Yes``, letsencrypt certificates are automatically fetched with the @@ -97,13 +99,14 @@ properly on your system. .. _docker_security_env: -Security --------- +********** + Security +********** Tune these options to strengthen the security of your instance. ``DJANGO_SECRET_KEY`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** A random unique string that must be kept secret for security reasons. You can generate it with the command: ``python @@ -113,7 +116,7 @@ Tune these options to strengthen the security of your instance. - **Default:** ``default_secret_key`` ``DJANGO_ALLOWED_HOSTS`` -~~~~~~~~~~~~~~~~~~~~~~~~ +======================== - **Explanation:** Used to validate a request's HTTP Host header. The default value ``*`` allows all domains. For security, it is recommended @@ -125,7 +128,7 @@ Tune these options to strengthen the security of your instance. - **Example:** ``.openwisp.org,.example.org,www.example.com``. ``OPENWISP_RADIUS_FREERADIUS_ALLOWED_HOSTS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================ - **Explanation:** Default IP address or subnet of your freeradius instance. @@ -134,8 +137,9 @@ Tune these options to strengthen the security of your instance. - **Default:** ``172.18.0.0/16``. - **Example:** ``127.0.0.1,192.0.2.20,172.18.0.0/16``. -OpenWISP --------- +********** + OpenWISP +********** Settings for the OpenWISP application and the underlying Django web framework. @@ -152,7 +156,7 @@ framework. .. _email_host: ``EMAIL_HOST`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Host to be used when connecting to the STMP. ``localhost`` or empty string are not allowed. @@ -161,7 +165,7 @@ framework. - **Default:** ``postfix``. ``EMAIL_DJANGO_DEFAULT`` -~~~~~~~~~~~~~~~~~~~~~~~~ +======================== - **Explanation:** It is the email address to use for various automated correspondence from the site manager(s). @@ -169,7 +173,7 @@ framework. - **Default:** ``example@example.com``. ``EMAIL_HOST_PORT`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Port to use for the SMTP server defined in :ref:`EMAIL_HOST`. @@ -177,7 +181,7 @@ framework. - **Default:** ``25``. ``EMAIL_HOST_USER`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Username to use for the SMTP server defined in :ref:`EMAIL_HOST`. If empty, Django won't attempt authentication. @@ -186,7 +190,7 @@ framework. - **Example:** ``example@example.com`` ``EMAIL_HOST_PASSWORD`` -~~~~~~~~~~~~~~~~~~~~~~~ +======================= - **Explanation:** Password to use for the SMTP server defined in :ref:`EMAIL_HOST`.. If empty, Django won't attempt authentication. @@ -194,7 +198,7 @@ framework. - **Default:** ``""`` (empty string) ``EMAIL_HOST_TLS`` -~~~~~~~~~~~~~~~~~~ +================== - **Explanation:** Whether to use a TLS (secure) connection when talking to the SMTP server. This is used for explicit TLS connections, generally @@ -203,7 +207,7 @@ framework. - **Default:** ``False``. ``EMAIL_TIMEOUT`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Specifies a timeout in seconds used by Django for blocking operations like the connection attempt. @@ -211,7 +215,7 @@ framework. - **Default:** ``10``. ``EMAIL_BACKEND`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Email will be sent using this backend. - **Valid Values:** `Refer to the "Email backends" section on the Django @@ -220,21 +224,21 @@ framework. - **Default:** ``djcelery_email.backends.CeleryEmailBackend``. ``DJANGO_X509_DEFAULT_CERT_VALIDITY`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +===================================== - **Explanation:** Validity of your x509 cert in days. - **Valid Values:** INTEGER. - **Default:** ``1825`` ``DJANGO_X509_DEFAULT_CA_VALIDITY`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=================================== - **Explanation:** Validity of your x509 CA in days. - **Valid Values:** INTEGER. - **Default:** ``3650``. ``DJANGO_CORS_HOSTS`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** Hosts for which `CORS `__. is @@ -244,7 +248,7 @@ framework. - **Example:** ``https://www.openwisp.org,openwisp.example.org`` ``DJANGO_LANGUAGE_CODE`` -~~~~~~~~~~~~~~~~~~~~~~~~ +======================== - **Explanation:** Language for your OpenWISP application. - **Valid Values:** Refer to the `related Django documentation section @@ -252,7 +256,7 @@ framework. - **Default:** ``en-gb``. ``DJANGO_SENTRY_DSN`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** `Sentry DSN `__. - **Valid Values:** Your DSN value provided by sentry. @@ -260,7 +264,7 @@ framework. - **Default:** ``""`` (empty string). ``DJANGO_LEAFET_CENTER_X_AXIS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== - **Explanation:** X-axis coordinate of the leaflet default center property. `Refer to the django-leaflet docs for more information @@ -270,7 +274,7 @@ framework. - **Default:** ``0``. ``DJANGO_LEAFET_CENTER_Y_AXIS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== - **Explanation:** Y-axis coordinate of the leaflet default center property. `Refer to the django-leaflet docs for more information @@ -280,7 +284,7 @@ framework. - **Default:** ``0``. ``DJANGO_LEAFET_ZOOM`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** Default zoom for leaflet. `Refer to the django-leaflet docs for more information @@ -289,7 +293,7 @@ framework. - **Default:** ``1``. ``DJANGO_WEBSOCKET_HOST`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= - **Explanation:** Host on which Daphne should listen for websocket connections. @@ -297,7 +301,7 @@ framework. - **Default:** ``0.0.0.0``. ``OPENWISP_GEOCODING_CHECK`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================ - **Explanation:** Used to check if geocoding is working as expected or not. @@ -305,7 +309,7 @@ framework. - **Default:** ``True``. ``USE_OPENWISP_CELERY_TASK_ROUTES_DEFAULTS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================ - **Explanation:** Whether the default celery task routes should be used by celery. Turn this off if you're defining custom task routing rules. @@ -313,7 +317,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_COMMAND_FLAGS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================= - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``default`` queue. It can be used to configure @@ -325,7 +329,7 @@ framework. - **Default:** ``--concurrency=1``. ``USE_OPENWISP_CELERY_NETWORK`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== - **Explanation:** Whether the dedicated worker for the celery "network" queue is enabled. Must be turned on unless there's another server @@ -334,7 +338,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_NETWORK_COMMAND_FLAGS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================= - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``network`` queue. It can be used to configure @@ -346,7 +350,7 @@ framework. - **Default:** ``--concurrency=1`` ``USE_OPENWISP_CELERY_FIRMWARE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================ - **Explanation:** Whether the dedicated worker for the celery ``firmware_upgrader`` queue is enabled. Must be turned on unless there's @@ -355,7 +359,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_FIRMWARE_COMMAND_FLAGS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================================== - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``firmware_upgrader`` queue. It can be used to @@ -367,7 +371,7 @@ framework. - **Default:** ``--concurrency=1`` ``USE_OPENWISP_CELERY_MONITORING`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================== - **Explanation:** Whether the dedicated worker for the celery ``monitoring`` queue is enabled. Must be turned on unless there's @@ -376,7 +380,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_MONITORING_COMMAND_FLAGS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================================ - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``monitoring`` queue. It can be used to configure @@ -388,7 +392,7 @@ framework. - **Default:** ``--concurrency=1``. ``OPENWISP_CELERY_MONITORING_CHECKS_COMMAND_FLAGS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=================================================== - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``monitoring_checks`` queue. It can be used to @@ -400,7 +404,7 @@ framework. - **Default:** ``--concurrency=1``. ``OPENWISP_CUSTOM_OPENWRT_IMAGES`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================== - **Explanation:** JSON representation of the :ref:`related Firmware Upgrader setting `. @@ -411,7 +415,7 @@ framework. "TestD"]}]`` ``METRIC_COLLECTION`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** Whether :doc:`/utils/user/metric-collection` is enabled or not. @@ -419,7 +423,7 @@ framework. - **Default:** ``True``. ``CRON_DELETE_OLD_RADACCT`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================== - **Explanation:** (Value in days) Deletes RADIUS accounting sessions older than given number of days. @@ -427,7 +431,7 @@ framework. - **Default:** ``365``. ``CRON_DELETE_OLD_POSTAUTH`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================ - **Explanation:** (Value in days) Deletes RADIUS *post-auth* logs older than given number of days. @@ -435,7 +439,7 @@ framework. - **Default:** ``365``. ``CRON_CLEANUP_STALE_RADACCT`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================== - **Explanation:** (Value in days) Closes stale RADIUS sessions that have remained open for the number of specified days. @@ -443,7 +447,7 @@ framework. - **Default:** ``365``. ``CRON_DELETE_OLD_RADIUSBATCH_USERS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +===================================== - **Explanation:** (Value in days) Deactivates expired user accounts which were created temporarily and have an expiration date set. @@ -451,7 +455,7 @@ framework. - **Default:** ``365``. ``DEBUG_MODE`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Enable Django Debugging. Refer to the `related Django documentation section @@ -461,7 +465,7 @@ framework. - **Default:** ``False``. ``REDIS_CACHE_URL`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Allows freely redefining the Redis database URL for the Django cache. @@ -470,7 +474,7 @@ framework. ``redis://:@:/0``. ``CHANNEL_REDIS_URL`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** Allows freely redefining the Redis database URL for Django Channels' layer. @@ -479,7 +483,7 @@ framework. ``redis://:@:/1``. ``CELERY_BROKER_URL`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** Allows freely redefining the Redis database URL for the Celery broker. @@ -488,7 +492,7 @@ framework. ``redis://:@:/2``. DJANGO_LOG_LEVEL -~~~~~~~~~~~~~~~~ +================ - **Explanation:** Logging level for Django. Refer to the `related Django documentation section @@ -497,13 +501,14 @@ DJANGO_LOG_LEVEL - **Valid Values:** STRING. - **Default:** ``ERROR``. -Enabled OpenWISP Modules ------------------------- +************************** + Enabled OpenWISP Modules +************************** These options allow to disable the optional OpenWISP modules. ``USE_OPENWISP_TOPOLOGY`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= - **Explanation:** Whether the :doc:`Network Topology ` module is enabled or not. @@ -511,7 +516,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``True``. ``USE_OPENWISP_RADIUS`` -~~~~~~~~~~~~~~~~~~~~~~~ +======================= - **Explanation:** Whether the :doc:`RADIUS ` module is enabled or not. @@ -519,7 +524,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``True``. ``USE_OPENWISP_FIRMWARE`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= - **Explanation:** Whether the :doc:`Firmware Upgrader ` module is enabled or not. @@ -527,7 +532,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``True``. ``USE_OPENWISP_MONITORING`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================== - **Explanation:** Whether the :doc:`Monitoring ` module is enabled or not. @@ -536,25 +541,26 @@ These options allow to disable the optional OpenWISP modules. .. _docker_postgresql_db_settings: -PostgreSQL Database -------------------- +********************* + PostgreSQL Database +********************* ``DB_NAME`` -~~~~~~~~~~~ +=========== - **Explanation:** The name of the database to use. - **Valid Values:** STRING. - **Default:** ``openwisp_db``. ``DB_USER`` -~~~~~~~~~~~ +=========== - **Explanation:** The username to use when connecting to the database. - **Valid Values:** STRING. - **Default:** ``admin``. ``DB_PASS`` -~~~~~~~~~~~ +=========== - **Explanation:** The password to use when connecting to the database. - **Valid Values:** STRING. @@ -563,7 +569,7 @@ PostgreSQL Database .. _db_engine: ``DB_HOST`` -~~~~~~~~~~~ +=========== - **Explanation:** Host to be used when connecting to the database. ``localhost`` or empty string are not allowed. @@ -571,14 +577,14 @@ PostgreSQL Database - **Default:** ``postgres``. ``DB_PORT`` -~~~~~~~~~~~ +=========== - **Explanation:** The port to use when connecting to the database. - **Valid Values:** INTEGER. - **Default:** ``5432``. ``DB_SSLMODE`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Postgresql SSLMode option. - **Valid Values:** Consult the related `PostgreSQL documentation @@ -586,21 +592,21 @@ PostgreSQL Database - **Default:** ``disable``. ``DB_SSLCERT`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Path inside container to a valid client certificate. - **Valid Values:** STRING. - **Default:** ``None``. ``DB_SSLKEY`` -~~~~~~~~~~~~~ +============= - **Explanation:** Path inside container to valid client private key. - **Valid Values:** STRING. - **Default:** ``None``. ``DB_SSLROOTCERT`` -~~~~~~~~~~~~~~~~~~ +================== - **Explanation:** Path inside container to a valid server certificate for the database. @@ -608,7 +614,7 @@ PostgreSQL Database - **Default:** ``None``. ``DB_OPTIONS`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Additional database options to connect to the database. These options must be supported by your :ref:`DB_ENGINE`. @@ -616,7 +622,7 @@ PostgreSQL Database - **Default:** ``{}``. ``DB_ENGINE`` -~~~~~~~~~~~~~ +============= - **Explanation:** `Django spatial database backend `_ @@ -625,35 +631,36 @@ PostgreSQL Database `__. - **Default:** ``django.contrib.gis.db.backends.postgis`` -InfluxDB --------- +********** + InfluxDB +********** InfluxDB is the default time series database used by the :doc:`Monitoring module `. ``INFLUXDB_USER`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Username of InfluxDB user. - **Valid Values:** STRING. - **Default:** ``admin``. ``INFLUXDB_PASS`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Password for InfluxDB user. - **Valid Values:** STRING. - **Default:** ``admin``. ``INFLUXDB_NAME`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Name of InfluxDB database. - **Valid Values:** STRING. - **Default:** ``openwisp``. ``INFLUXDB_HOST`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Host to be used when connecting to influxDB. Values as ``localhost`` or empty string are not allowed. @@ -661,22 +668,23 @@ module `. - **Default:** ``influxdb``. ``INFLUXDB_PORT`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Port on which InfluxDB is listening to. - **Valid Values:** INTEGER. - **Default:** ``8086``. ``INFLUXDB_DEFAULT_RETENTION_POLICY`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +===================================== - **Explanation:** The default retention policy that applies to the time series data. - **Valid Values:** STRING. - **Default:** ``26280h0m0s`` (3 years). -Postfix -------- +********* + Postfix +********* .. note:: @@ -685,7 +693,7 @@ Postfix available. ``POSTFIX_ALLOWED_SENDER_DOMAINS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================== - **Explanation:** Due to in-built spam protection in Postfix you will need to specify sender domains. @@ -693,7 +701,7 @@ Postfix - **Default:** ``example.org``. ``POSTFIX_MYHOSTNAME`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** You may configure a specific hostname that the SMTP server will use to identify itself. @@ -701,14 +709,14 @@ Postfix - **Default:** ``example.org``. ``POSTFIX_DESTINATION`` -~~~~~~~~~~~~~~~~~~~~~~~ +======================= - **Explanation:** Destinations of the postfix service. - **Valid Values:** Any valid domain name. - **Default:** ``$mydomain, $myhostname``. ``POSTFIX_MESSAGE_SIZE_LIMIT`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================== - **Explanation:** By default, this limit is set to 0 (zero), which means unlimited. Why would you want to set this? Well, this is especially @@ -718,7 +726,7 @@ Postfix - **Example:** ``26214400`` ``POSTFIX_MYNETWORKS`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** Postfix is exposed only in ``mynetworks`` to prevent any issues with this postfix being inadvertently exposed on the @@ -727,7 +735,7 @@ Postfix - **Default:** ``127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128``. ``POSTFIX_RELAYHOST_TLS_LEVEL`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== - **Explanation:** Define relay host TLS connection level. - **Valid Values:** `See list @@ -735,7 +743,7 @@ Postfix - **Default:** ``may``. ``POSTFIX_RELAYHOST`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** Host that relays your mails. - **Valid Values:** any valid IP address or domain name. @@ -743,7 +751,7 @@ Postfix - **Example:** ``[smtp.gmail.com]:587``. ``POSTFIX_RELAYHOST_USERNAME`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================== - **Explanation:** Username for the relay server. - **Valid Values:** STRING. @@ -751,7 +759,7 @@ Postfix - **Example:** ``example@example.com``. ``POSTFIX_RELAYHOST_PASSWORD`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================== - **Explanation:** Login password for the relay server. - **Valid Values:** STRING. @@ -759,7 +767,7 @@ Postfix - **Example:** ``example``. ``POSTFIX_DEBUG_MYNETWORKS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================ - **Explanation:** Set debug_peer_list for given list of networks. - **Valid Values:** STRING. @@ -768,35 +776,37 @@ Postfix .. _docker_uwsgi_env: -uWSGI ------ +******* + uWSGI +******* ``UWSGI_PROCESSES`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Number of uWSGI process to spawn. - **Valid Values:** INTEGER. - **Default:** ``2``. ``UWSGI_THREADS`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Number of threads each uWSGI process will have. - **Valid Values:** INTEGER. - **Default:** ``2``. ``UWSGI_LISTEN`` -~~~~~~~~~~~~~~~~ +================ - **Explanation:** Value of the listen queue of uWSGI. - **Valid Values:** INTEGER. - **Default:** ``100``. -Nginx ------ +******* + Nginx +******* ``NGINX_HTTP2`` -~~~~~~~~~~~~~~~ +=============== - **Explanation:** Used by nginx to enable http2. Refer to the `related Nginx documentation section @@ -806,7 +816,7 @@ Nginx - **Default:** ``http2``. ``NGINX_CLIENT_BODY_SIZE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================== - **Explanation:** Client body size. Refer to the `related Nginx documentation section @@ -816,7 +826,7 @@ Nginx - **Default:** ``30``. ``NGINX_IP6_STRING`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Nginx listen on IPv6 for SSL connection. You can either enter a valid nginx statement or leave this value empty. @@ -824,7 +834,7 @@ Nginx - **Default:** ``""`` (empty string). ``NGINX_IP6_80_STRING`` -~~~~~~~~~~~~~~~~~~~~~~~ +======================= - **Explanation:** Nginx listen on IPv6 connection. You can either enter a valid nginx statement or leave this value empty. @@ -832,7 +842,7 @@ Nginx - **Default:** ``""`` (empty string). ``NGINX_ADMIN_ALLOW_NETWORK`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================= - **Explanation:** IP address allowed to access OpenWISP services. - **Valid Values:** ``all``, IP network. @@ -840,7 +850,7 @@ Nginx - **Default:** ``all``. ``NGINX_SERVER_NAME_HASH_BUCKET`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================= - **Explanation:** Define the `Nginx domain hash bucket size `__. Values should be only in powers @@ -849,7 +859,7 @@ Nginx - **Default:** ``32``. ``NGINX_SSL_CONFIG`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Additional nginx configurations. You can add any valid server block element here. As an example ``index`` option is configured. @@ -860,7 +870,7 @@ Nginx - **Default:** ``""`` (empty string). ``NGINX_80_CONFIG`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Additional nginx configurations. You can add any valid server block element here. As an example ``index`` option is configured. @@ -870,7 +880,7 @@ Nginx - **Default:** ``""`` (empty string). ``NGINX_SSL_PORT`` -~~~~~~~~~~~~~~~~~~ +================== - **Explanation:** Nginx container external HTTPS port. Change if, for example, OpenWISP runs behind a reverse proxy listening on port 443 on @@ -880,7 +890,7 @@ Nginx - **Default:** ``443``. ``NGINX_PORT`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Nginx container external HTTP port. Change if, for example, OpenWISP runs behind a reverse proxy listening on port 80 on @@ -890,14 +900,14 @@ Nginx - **Default:** ``80``. ``NGINX_GZIP_SWITCH`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** Turn on/off Nginx GZIP. - **Valid Values:** ``on``, ``off``. - **Default:** ``on``. ``NGINX_GZIP_LEVEL`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Sets a gzip compression level of a response. Acceptable values are in the range from 1 to 9. @@ -905,7 +915,7 @@ Nginx - **Default:** ``6``. ``NGINX_GZIP_PROXIED`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** Enables or disables gzipping of responses for proxied requests depending on the request and response. @@ -914,7 +924,7 @@ Nginx - **Default:** ``any``. ``NGINX_GZIP_MIN_LENGTH`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= - **Explanation:** Sets the minimum length of a response that will be gzipped. The length is determined only from the "Content-Length" @@ -923,7 +933,7 @@ Nginx - **Default:** ``1000``. ``NGINX_GZIP_TYPES`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Enables gzipping of responses for the specified MIME types in addition to "text/html". The special value "\*" matches any @@ -935,7 +945,7 @@ Nginx - **Default:** ``\*``. ``NGINX_HTTPS_ALLOWED_IPS`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=========================== - **Explanation:** Allow these IP addresses to access the website over http when ``SSL_CERT_MODE`` is set to ``Yes`` . @@ -944,7 +954,7 @@ Nginx - **Default:** ``all``. ``NGINX_HTTP_ALLOW`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Allow http access with https access. Valid only when ``SSL_CERT_MODE`` is set to ``Yes`` or ``SelfSigned``. @@ -952,7 +962,7 @@ Nginx - **Default:** ``True``. ``NGINX_CUSTOM_FILE`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** If you have a custom configuration file mounted, set this to ``True``. @@ -960,7 +970,7 @@ Nginx - **Default:** ``False``. ``NINGX_REAL_REMOTE_ADDR`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================== - **Explanation:** The nginx header to get the value of the real IP address of Access points. Example if a reverse proxy is used in your @@ -972,11 +982,12 @@ Nginx ``$realip_remote_addr``, ``$real_ip``. - **Default:** ``$real_ip``. -OpenVPN -------- +********* + OpenVPN +********* ``VPN_NAME`` -~~~~~~~~~~~~ +============ - **Explanation:** Name of the VPN Server that will be visible on the OpenWISP dashboard. @@ -984,29 +995,31 @@ OpenVPN - **Default:** ``default``. ``VPN_CLIENT_NAME`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Name of the VPN client template that will be visible on the OpenWISP dashboard. - **Valid Values:** STRING. - **Default:** ``default-management-vpn``. -Topology --------- +********** + Topology +********** ``TOPOLOGY_UPDATE_INTERVAL`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +============================ - **Explanation:** Interval in minutes to upload the topology data to the OpenWISP, - **Valid Values:** INTEGER. - **Default:** ``3``. -X509 Certificates ------------------ +******************* + X509 Certificates +******************* ``X509_NAME_CA`` -~~~~~~~~~~~~~~~~ +================ - **Explanation:** Name of the default certificate authority visible on the OpenWISP dashboard. @@ -1014,7 +1027,7 @@ X509 Certificates - **Default:** ``default``. ``X509_NAME_CERT`` -~~~~~~~~~~~~~~~~~~ +================== - **Explanation:** Name of the default certificate visible on the OpenWISP dashboard. @@ -1022,7 +1035,7 @@ X509 Certificates - **Default:** ``default``. ``X509_COUNTRY_CODE`` -~~~~~~~~~~~~~~~~~~~~~ +===================== - **Explanation:** ISO code of the country of issuance of the certificate. - **Valid Values:** Country code, see list `here @@ -1030,7 +1043,7 @@ X509 Certificates - **Default:** ``IN``. ``X509_STATE`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Name of the state / province of issuance of the certificate. @@ -1038,21 +1051,21 @@ X509 Certificates - **Default:** ``Delhi``. ``X509_CITY`` -~~~~~~~~~~~~~ +============= - **Explanation:** Name of the city of issuance of the certificate. - **Valid Values:** STRING. - **Default:** ``New Delhi``. ``X509_ORGANIZATION_NAME`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ +========================== - **Explanation:** Name of the organization issuing the certificate. - **Valid Values:** STRING. - **Default:** ``OpenWISP``. ``X509_ORGANIZATION_UNIT_NAME`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=============================== - **Explanation:** Name of the unit of the organization issuing the certificate. @@ -1060,7 +1073,7 @@ X509 Certificates - **Default:** ``OpenWISP``. ``X509_EMAIL`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Organization email address that'll be available to view in the certificate. @@ -1068,66 +1081,67 @@ X509 Certificates - **Default:** ``certificate@example.com``. ``X509_COMMON_NAME`` -~~~~~~~~~~~~~~~~~~~~ +==================== - **Explanation:** Common name for the CA and certificate. - **Valid Values:** STRING. - **Default:** ``OpenWISP``. -Misc Services -------------- +*************** + Misc Services +*************** ``REDIS_HOST`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Host to establish redis connection. - **Valid Values:** A valid hostname or IP address. - **Default:** ``redis``. ``REDIS_PORT`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Port to establish redis connection. - **Valid Values:** INTEGER. - **Default:** ``6379``. ``REDIS_USER`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Redis username, optional. - **Valid Values:** STRING. - **Default:** ``""`` (empty string). ``REDIS_PASS`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Redis password, optional. - **Valid Values:** STRING. - **Default:** ``None``. ``REDIS_USE_TLS`` -~~~~~~~~~~~~~~~~~ +================= - **Explanation:** Whether to use TLS for redis connection. - **Valid Values:** ``True``, ``False``. - **Default:** ``False``. ``DASHBOARD_APP_SERVICE`` -~~~~~~~~~~~~~~~~~~~~~~~~~ +========================= - **Explanation:** Host to establish OpenWISP dashboard connection. - **Valid Values:** Any hostname or IP address. - **Default:** ``dashboard``. ``API_APP_SERVICE`` -~~~~~~~~~~~~~~~~~~~ +=================== - **Explanation:** Host to establish OpenWISP api connection. - **Valid Values:** Any hostname or IP address. - **Default:** ``api``. ``DASHBOARD_APP_PORT`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** The port on which nginx tries to get the OpenWISP dashboard container. Don't Change unless you know what you are doing. @@ -1135,7 +1149,7 @@ Misc Services - **Default:** ``8000``. ``API_APP_PORT`` -~~~~~~~~~~~~~~~~ +================ - **Explanation:** The port on which nginx tries to get the OpenWISP api container. Don't Change unless you know what you are doing. @@ -1143,7 +1157,7 @@ Misc Services - **Default:** ``8001``. ``WEBSOCKET_APP_PORT`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** The port on which nginx tries to get the OpenWISP websocket container. Don't Change unless you know what you are doing. @@ -1151,7 +1165,7 @@ Misc Services - **Default:** ``8002``. ``DASHBOARD_INTERNAL`` -~~~~~~~~~~~~~~~~~~~~~~ +====================== - **Explanation:** Internal dashboard domain to reach dashboard from other containers. @@ -1159,17 +1173,18 @@ Misc Services - **Default:** ``dashboard.internal``. ``API_INTERNAL`` -~~~~~~~~~~~~~~~~ +================ - **Explanation:** Internal api domain to reach api from other containers. - **Valid Values:** STRING. - **Default:** ``api.internal``. -NFS Server ----------- +************ + NFS Server +************ ``EXPORT_DIR`` -~~~~~~~~~~~~~~ +============== - **Explanation:** Directory to be exported by the NFS server. Don't change this unless you know what you are doing. @@ -1177,7 +1192,7 @@ NFS Server - **Default:** ``/exports``. ``EXPORT_OPTS`` -~~~~~~~~~~~~~~~ +=============== - **Explanation:** NFS export options for the directory in ``EXPORT_DIR`` variable. @@ -1186,7 +1201,7 @@ NFS Server ``10.0.0.0/8(rw,fsid=0,insecure,no_root_squash,no_subtree_check,sync)``. ``COLLECTSTATIC_WHEN_DEPS_CHANGE`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +================================== - **Description:** Runs ``collectstatic`` at container startup only if Python dependencies have changed. Set to ``false`` if you're using the From 8cb14af8bc0e59a099ba7700e53ea91692d0f3c4 Mon Sep 17 00:00:00 2001 From: Adityashandilya555 Date: Tue, 9 Dec 2025 13:12:01 +0530 Subject: [PATCH 5/5] [deps] Pin sphinx<8.0.0 for docstrfmt compatibility --- CHANGES.rst | 49 +++-- README.rst | 10 +- docs/developer/instructions.rst | 31 ++- docs/index.rst | 5 +- docs/user/architecture.rst | 5 +- docs/user/customization.rst | 49 ++--- docs/user/faq.rst | 20 +- docs/user/quickstart.rst | 22 +-- docs/user/settings.rst | 329 +++++++++++++++----------------- requirements-test.txt | 1 + 10 files changed, 238 insertions(+), 283 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index 903a0f7b..9ef0017e 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,13 +1,11 @@ -########### - Changelog -########### +Changelog +========= -****************************** - Version 25.10.0 [2025-10-24] -****************************** +Version 25.10.0 [2025-10-24] +---------------------------- Features -======== +~~~~~~~~ - Added support for non-default external ports in the Nginx container `#496 `_. @@ -20,10 +18,10 @@ Features `_. Changes -======= +~~~~~~~ Dependencies ------------- +++++++++++++ - Upgraded to OpenWISP Users 1.2.x (see `changelog `__). @@ -63,7 +61,7 @@ Dependencies - Bumped ``boto3>=1.40.49,<1.41.0``. Bugfixes -======== +~~~~~~~~ - Fixed permissions issues in the Postfix container. - Fixed FreeRADIUS container exit caused by global write permissions. @@ -75,12 +73,11 @@ Bugfixes `_. - Updated auto-install script to suggest the correct VPN hostname. -****************************** - Version 24.11.2 [2024-12-18] -****************************** +Version 24.11.2 [2024-12-18] +---------------------------- Bugfixes -======== +~~~~~~~~ - Resolved an issue in the ``docker-compose`` configuration for the ``openvpn`` service by adding the ``/dev/net/tun`` device. @@ -94,21 +91,19 @@ Bugfixes ``postfix~=3.9.1-r0``. - Bumped ``boto3~=1.35.82``. -****************************** - Version 24.11.1 [2024-11-27] -****************************** +Version 24.11.1 [2024-11-27] +---------------------------- Bugfixes -======== +~~~~~~~~ - Updated ``__openwisp_version__`` to ``24.11.1``. -****************************** - Version 24.11.0 [2024-11-27] -****************************** +Version 24.11.0 [2024-11-27] +---------------------------- Features -======== +~~~~~~~~ - Added a default topology for the default VPN. - Added default credentials and SSH key template. @@ -127,10 +122,10 @@ Features `_. Changes -======= +~~~~~~~ Dependencies ------------- +++++++++++++ - Upgraded to OpenWISP Users 1.1.x (see `changelog `__). @@ -158,7 +153,7 @@ Dependencies ``python:3.10.0-slim-buster``. Backward Incompatible Changes ------------------------------ ++++++++++++++++++++++++++++++ - Merged the OpenWISP RADIUS container into the dashboard and API. - The ``CRON_DELETE_OLD_RADIUSBATCH_USERS`` variable now expects the @@ -169,7 +164,7 @@ Backward Incompatible Changes ``CRON_DELETE_OLD_RADIUSBATCH_USERS``. Other Changes -------------- ++++++++++++++ - Changed cron to update OpenVPN revoke list daily at midnight. - Added admin URLs to the API container. @@ -183,7 +178,7 @@ Other Changes - Disabled nginx ``server_tokens`` for improved security. Bugfixes -======== +~~~~~~~~ - Fixed OpenVPN cron script to download configuration at the correct path. - Fixed project configuration issues in the OpenWISP RADIUS module. diff --git a/README.rst b/README.rst index cfe6daf8..8a0566b5 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,5 @@ -################# - Docker-OpenWISP -################# +Docker-OpenWISP +=============== .. image:: https://github.com/openwisp/docker-openwisp/workflows/Automation%20Tests/badge.svg :target: https://github.com/openwisp/docker-openwisp/actions?query=workflow%3A%22Automation+Tests%22 @@ -24,9 +23,8 @@ in mind. .. image:: https://raw.githubusercontent.com/openwisp/docker-openwisp/master/docs/images/portainer-docker-list.png :target: https://raw.githubusercontent.com/openwisp/docker-openwisp/master/docs/images/portainer-docker-list.png -*************** - Documentation -*************** +Documentation +------------- - `Usage documentation `_ - `Developer documentation diff --git a/docs/developer/instructions.rst b/docs/developer/instructions.rst index d0c08255..232b83bc 100644 --- a/docs/developer/instructions.rst +++ b/docs/developer/instructions.rst @@ -1,6 +1,5 @@ -################ - Developer Docs -################ +Developer Docs +============== .. include:: ../partials/developer-docs.rst @@ -10,9 +9,8 @@ .. include:: ../partials/updating-host-file.rst -***************************** - Building and Running Images -***************************** +Building and Running Images +--------------------------- 1. Install Docker. 2. In the root directory of the repository, run ``make develop``. Once the @@ -30,9 +28,8 @@ by ``docker-openwisp``, please refer to the :ref:`makefile options `. -*************** - Running Tests -*************** +Running Tests +------------- You can run tests using either ``geckodriver`` (Firefox) or ``chromedriver`` (Chromium). @@ -40,14 +37,14 @@ You can run tests using either ``geckodriver`` (Firefox) or **Chromium is preferred as it also checks for console log errors.** Using Chromedriver -================== +~~~~~~~~~~~~~~~~~~ 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/``). Using Geckodriver -================= +~~~~~~~~~~~~~~~~~ Install Geckodriver for Firefox for your browser version from https://github.com/mozilla/geckodriver/releases and extract @@ -55,7 +52,7 @@ https://github.com/mozilla/geckodriver/releases and extract ``~/.local/bin/``). Finish Setup and Run Tests -========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Install test requirements: @@ -90,9 +87,8 @@ Finish Setup and Run Tests python3 tests/runtests.py . -****************************** - Run Quality Assurance Checks -****************************** +Run Quality Assurance Checks +---------------------------- We use `shfmt `__ to format shell scripts and `hadolint `__ to @@ -113,9 +109,8 @@ To run quality assurance checks, use the ``run-qa-checks`` script: .. _docker_make_options: -****************** - Makefile Options -****************** +Makefile Options +---------------- Most commonly used: diff --git a/docs/index.rst b/docs/index.rst index c2381e40..6fc7123e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,5 @@ -################# - Docker OpenWISP -################# +Docker OpenWISP +=============== .. seealso:: diff --git a/docs/user/architecture.rst b/docs/user/architecture.rst index 81705c1b..b35ee794 100644 --- a/docs/user/architecture.rst +++ b/docs/user/architecture.rst @@ -1,6 +1,5 @@ -############## - Architecture -############## +Architecture +============ A typical OpenWISP installation is made of multiple components (e.g. application servers, background workers, web servers, database, messaging diff --git a/docs/user/customization.rst b/docs/user/customization.rst index d7e9ffeb..df0afa06 100644 --- a/docs/user/customization.rst +++ b/docs/user/customization.rst @@ -1,6 +1,5 @@ -######################## - Advanced Customization -######################## +Advanced Customization +====================== This page describes advanced customization options for the OpenWISP Docker images. @@ -12,9 +11,8 @@ areas that can be customized. :depth: 1 :local: -****************************************** - Creating the ``customization`` Directory -****************************************** +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 @@ -34,9 +32,8 @@ for an example. .. _docker_custom_django_settings: -********************************** - Supplying Custom Django Settings -********************************** +Supplying Custom Django Settings +-------------------------------- The ``customization/configuration/django`` directory created in the previous section is mounted at ``/opt/openwisp/openwisp/configuration`` in @@ -51,9 +48,8 @@ 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 -******************************************* +Supplying Custom CSS and JavaScript Files +----------------------------------------- If you want to use your custom styles, add custom JavaScript you can follow the following guide. @@ -99,9 +95,8 @@ follow the following guide. 2. You can create a ``maintenance.html`` file inside the ``customize`` directory to have a custom maintenance page for scheduled downtime. -************************************** - Supplying Custom uWSGI configuration -************************************** +Supplying Custom uWSGI configuration +------------------------------------ By default, you can only configure :ref:`"processes", "threads" and "listen" settings of uWSGI using environment variables @@ -130,12 +125,11 @@ supply your uWSGI configuration by following these steps: .. _docker_nginx: -*************************************** - Supplying Custom Nginx Configurations -*************************************** +Supplying Custom Nginx Configurations +------------------------------------- Docker -====== +~~~~~~ 1. Create nginx your configuration file. 2. Set ``NGINX_CUSTOM_FILE`` to ``True`` in ``.env`` file. @@ -152,9 +146,8 @@ Docker .. _docker_freeradius: -******************************************** - Supplying Custom Freeradius Configurations -******************************************** +Supplying Custom Freeradius Configurations +------------------------------------------ Note: ``/etc/raddb/clients.conf``, ``/etc/raddb/radiusd.conf``, ``/etc/raddb/sites-enabled/default``, ``/etc/raddb/mods-enabled/``, @@ -166,7 +159,7 @@ including custom ``radiusd.conf`` and ``sites-enabled/default`` files. .. _docker-1: Docker -====== +~~~~~~ 1. Create file configuration files that you want to edit / add to your container. @@ -182,9 +175,8 @@ Docker PATH/TO/YOUR/DEFAULT:/etc/raddb/sites-enabled/default ... -************************************* - Supplying Custom Python Source Code -************************************* +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 @@ -214,9 +206,8 @@ written like this: DJANGO_SOURCE=https://github.com//Django/tarball/master OPENWISP_CONTROLLER_SOURCE=https://github.com//openwisp-controller/tarball/master -******************** - Disabling Services -******************** +Disabling Services +------------------ - ``openwisp-dashboard``: You cannot disable the openwisp-dashboard. It is the heart of OpenWISP and performs core functionalities. diff --git a/docs/user/faq.rst b/docs/user/faq.rst index a68fa5c6..3f4d8a6e 100644 --- a/docs/user/faq.rst +++ b/docs/user/faq.rst @@ -1,14 +1,12 @@ -###################### - Docker OpenWISP FAQs -###################### +Docker OpenWISP FAQs +==================== .. contents:: **Table of Contents**: :depth: 1 :local: -*********************************************************** - 1. Setup fails, it couldn't find the images on DockerHub? -*********************************************************** +1. Setup fails, it couldn't find the images on DockerHub? +--------------------------------------------------------- Answer: The setup requires following ports and destinations to be unblocked, if you are using a firewall or any external control to block @@ -27,9 +25,8 @@ traffic, please whitelist: 8 0 tcp 25 172.18.0.0/16 ``/usr/bin/docker-proxy`` = ====== ======== ========== ====================== ===================================== -*********************************************************** - 2. Makefile failed without any information, what's wrong? -*********************************************************** +2. Makefile failed without any information, what's wrong? +--------------------------------------------------------- Answer: You are using an old version of a requirement, please consider upgrading: @@ -49,9 +46,8 @@ upgrading: $ uname -v # kernel-version #1 SMP Debian 4.19.181-1 (2021-03-19) -*********************************************************** - 3. Can I run the containers as the ``root`` or ``docker`` -*********************************************************** +3. Can I run the containers as the ``root`` or ``docker`` +--------------------------------------------------------- No, please do not run the Docker containers as these users. diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 8a0a1099..e8eb4b78 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -1,6 +1,5 @@ -################### - Quick Start Guide -################### +Quick Start Guide +================= This page explains how to deploy OpenWISP using the docker images provided by Docker OpenWISP. @@ -9,16 +8,15 @@ by Docker OpenWISP. :depth: 1 :local: -****************** - Available Images -****************** +Available Images +---------------- The images are hosted on `Docker Hub `__ and `GitLab Container Registry `__. Image Tags -========== +~~~~~~~~~~ All images are tagged using the following convention: @@ -33,9 +31,8 @@ edge This is the development version of OpenWISP. On Github, this corresponds to the current master branch. ====== ========================================================= -********************* - Auto Install Script -********************* +Auto Install Script +------------------- .. figure:: ../images/auto-install.png :target: ../../_images/auto-install.png @@ -101,9 +98,8 @@ by using the following command - Still facing errors while installation? Please :doc:`read the FAQ `. -********************** - Using Docker Compose -********************** +Using Docker Compose +-------------------- This setup is suitable for single-server setup requirements. It is quicker and requires less prior knowledge about OpenWISP & networking. diff --git a/docs/user/settings.rst b/docs/user/settings.rst index 22562e53..5bc46d9c 100644 --- a/docs/user/settings.rst +++ b/docs/user/settings.rst @@ -1,6 +1,5 @@ -########## - Settings -########## +Settings +======== The OpenWISP Docker images are designed for customization. You can easily modify environment variables to tailor the containers to your needs. @@ -32,9 +31,8 @@ Additionally, you can search for the following prefixes: .. _docker_essential_env: -*********** - Essential -*********** +Essential +--------- You will need to adapt these values to get the docker images working properly on your system. @@ -42,7 +40,7 @@ properly on your system. .. _dashboard_domain: ``DASHBOARD_DOMAIN`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Domain on which you want to access OpenWISP dashboard. - **Valid Values:** Any valid domain. @@ -51,7 +49,7 @@ properly on your system. .. _api_domain: ``API_DOMAIN`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Domain on which you want to access OpenWISP APIs. - **Valid Values:** Any valid domain. @@ -60,14 +58,14 @@ properly on your system. .. _vpn_domain: ``VPN_DOMAIN`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Valid domain / IP address to reach the OpenVPN server. - **Valid Values:** Any valid domain or IP address. - **Default:** ``openvpn.example.com``. ``TZ`` -====== +~~~~~~ - **Explanation:** Sets the timezone for the OpenWISP containers. - **Valid Values:** Find list of timezone database `here @@ -75,7 +73,7 @@ properly on your system. - **Default:** ``UTC``. ``CERT_ADMIN_EMAIL`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Required by certbot. Email used for registration and recovery contact. @@ -83,7 +81,7 @@ properly on your system. - **Default:** ``example@example.com``. ``SSL_CERT_MODE`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Flag to enable or disable HTTPS. If it is set to ``Yes``, letsencrypt certificates are automatically fetched with the @@ -99,14 +97,13 @@ properly on your system. .. _docker_security_env: -********** - Security -********** +Security +-------- Tune these options to strengthen the security of your instance. ``DJANGO_SECRET_KEY`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** A random unique string that must be kept secret for security reasons. You can generate it with the command: ``python @@ -116,7 +113,7 @@ Tune these options to strengthen the security of your instance. - **Default:** ``default_secret_key`` ``DJANGO_ALLOWED_HOSTS`` -======================== +~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Used to validate a request's HTTP Host header. The default value ``*`` allows all domains. For security, it is recommended @@ -128,7 +125,7 @@ Tune these options to strengthen the security of your instance. - **Example:** ``.openwisp.org,.example.org,www.example.com``. ``OPENWISP_RADIUS_FREERADIUS_ALLOWED_HOSTS`` -============================================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Default IP address or subnet of your freeradius instance. @@ -137,9 +134,8 @@ Tune these options to strengthen the security of your instance. - **Default:** ``172.18.0.0/16``. - **Example:** ``127.0.0.1,192.0.2.20,172.18.0.0/16``. -********** - OpenWISP -********** +OpenWISP +-------- Settings for the OpenWISP application and the underlying Django web framework. @@ -156,7 +152,7 @@ framework. .. _email_host: ``EMAIL_HOST`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Host to be used when connecting to the STMP. ``localhost`` or empty string are not allowed. @@ -165,7 +161,7 @@ framework. - **Default:** ``postfix``. ``EMAIL_DJANGO_DEFAULT`` -======================== +~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** It is the email address to use for various automated correspondence from the site manager(s). @@ -173,7 +169,7 @@ framework. - **Default:** ``example@example.com``. ``EMAIL_HOST_PORT`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Port to use for the SMTP server defined in :ref:`EMAIL_HOST`. @@ -181,7 +177,7 @@ framework. - **Default:** ``25``. ``EMAIL_HOST_USER`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Username to use for the SMTP server defined in :ref:`EMAIL_HOST`. If empty, Django won't attempt authentication. @@ -190,7 +186,7 @@ framework. - **Example:** ``example@example.com`` ``EMAIL_HOST_PASSWORD`` -======================= +~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Password to use for the SMTP server defined in :ref:`EMAIL_HOST`.. If empty, Django won't attempt authentication. @@ -198,7 +194,7 @@ framework. - **Default:** ``""`` (empty string) ``EMAIL_HOST_TLS`` -================== +~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether to use a TLS (secure) connection when talking to the SMTP server. This is used for explicit TLS connections, generally @@ -207,7 +203,7 @@ framework. - **Default:** ``False``. ``EMAIL_TIMEOUT`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Specifies a timeout in seconds used by Django for blocking operations like the connection attempt. @@ -215,7 +211,7 @@ framework. - **Default:** ``10``. ``EMAIL_BACKEND`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Email will be sent using this backend. - **Valid Values:** `Refer to the "Email backends" section on the Django @@ -224,21 +220,21 @@ framework. - **Default:** ``djcelery_email.backends.CeleryEmailBackend``. ``DJANGO_X509_DEFAULT_CERT_VALIDITY`` -===================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Validity of your x509 cert in days. - **Valid Values:** INTEGER. - **Default:** ``1825`` ``DJANGO_X509_DEFAULT_CA_VALIDITY`` -=================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Validity of your x509 CA in days. - **Valid Values:** INTEGER. - **Default:** ``3650``. ``DJANGO_CORS_HOSTS`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Hosts for which `CORS `__. is @@ -248,7 +244,7 @@ framework. - **Example:** ``https://www.openwisp.org,openwisp.example.org`` ``DJANGO_LANGUAGE_CODE`` -======================== +~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Language for your OpenWISP application. - **Valid Values:** Refer to the `related Django documentation section @@ -256,7 +252,7 @@ framework. - **Default:** ``en-gb``. ``DJANGO_SENTRY_DSN`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** `Sentry DSN `__. - **Valid Values:** Your DSN value provided by sentry. @@ -264,7 +260,7 @@ framework. - **Default:** ``""`` (empty string). ``DJANGO_LEAFET_CENTER_X_AXIS`` -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** X-axis coordinate of the leaflet default center property. `Refer to the django-leaflet docs for more information @@ -274,7 +270,7 @@ framework. - **Default:** ``0``. ``DJANGO_LEAFET_CENTER_Y_AXIS`` -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Y-axis coordinate of the leaflet default center property. `Refer to the django-leaflet docs for more information @@ -284,7 +280,7 @@ framework. - **Default:** ``0``. ``DJANGO_LEAFET_ZOOM`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Default zoom for leaflet. `Refer to the django-leaflet docs for more information @@ -293,7 +289,7 @@ framework. - **Default:** ``1``. ``DJANGO_WEBSOCKET_HOST`` -========================= +~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Host on which Daphne should listen for websocket connections. @@ -301,7 +297,7 @@ framework. - **Default:** ``0.0.0.0``. ``OPENWISP_GEOCODING_CHECK`` -============================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Used to check if geocoding is working as expected or not. @@ -309,7 +305,7 @@ framework. - **Default:** ``True``. ``USE_OPENWISP_CELERY_TASK_ROUTES_DEFAULTS`` -============================================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the default celery task routes should be used by celery. Turn this off if you're defining custom task routing rules. @@ -317,7 +313,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_COMMAND_FLAGS`` -================================= +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``default`` queue. It can be used to configure @@ -329,7 +325,7 @@ framework. - **Default:** ``--concurrency=1``. ``USE_OPENWISP_CELERY_NETWORK`` -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the dedicated worker for the celery "network" queue is enabled. Must be turned on unless there's another server @@ -338,7 +334,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_NETWORK_COMMAND_FLAGS`` -========================================= +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``network`` queue. It can be used to configure @@ -350,7 +346,7 @@ framework. - **Default:** ``--concurrency=1`` ``USE_OPENWISP_CELERY_FIRMWARE`` -================================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the dedicated worker for the celery ``firmware_upgrader`` queue is enabled. Must be turned on unless there's @@ -359,7 +355,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_FIRMWARE_COMMAND_FLAGS`` -========================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``firmware_upgrader`` queue. It can be used to @@ -371,7 +367,7 @@ framework. - **Default:** ``--concurrency=1`` ``USE_OPENWISP_CELERY_MONITORING`` -================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the dedicated worker for the celery ``monitoring`` queue is enabled. Must be turned on unless there's @@ -380,7 +376,7 @@ framework. - **Default:** ``True``. ``OPENWISP_CELERY_MONITORING_COMMAND_FLAGS`` -============================================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``monitoring`` queue. It can be used to configure @@ -392,7 +388,7 @@ framework. - **Default:** ``--concurrency=1``. ``OPENWISP_CELERY_MONITORING_CHECKS_COMMAND_FLAGS`` -=================================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional flags passed to the command that starts the celery worker for the ``monitoring_checks`` queue. It can be used to @@ -404,7 +400,7 @@ framework. - **Default:** ``--concurrency=1``. ``OPENWISP_CUSTOM_OPENWRT_IMAGES`` -================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** JSON representation of the :ref:`related Firmware Upgrader setting `. @@ -415,7 +411,7 @@ framework. "TestD"]}]`` ``METRIC_COLLECTION`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether :doc:`/utils/user/metric-collection` is enabled or not. @@ -423,7 +419,7 @@ framework. - **Default:** ``True``. ``CRON_DELETE_OLD_RADACCT`` -=========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** (Value in days) Deletes RADIUS accounting sessions older than given number of days. @@ -431,7 +427,7 @@ framework. - **Default:** ``365``. ``CRON_DELETE_OLD_POSTAUTH`` -============================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** (Value in days) Deletes RADIUS *post-auth* logs older than given number of days. @@ -439,7 +435,7 @@ framework. - **Default:** ``365``. ``CRON_CLEANUP_STALE_RADACCT`` -============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** (Value in days) Closes stale RADIUS sessions that have remained open for the number of specified days. @@ -447,7 +443,7 @@ framework. - **Default:** ``365``. ``CRON_DELETE_OLD_RADIUSBATCH_USERS`` -===================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** (Value in days) Deactivates expired user accounts which were created temporarily and have an expiration date set. @@ -455,7 +451,7 @@ framework. - **Default:** ``365``. ``DEBUG_MODE`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Enable Django Debugging. Refer to the `related Django documentation section @@ -465,7 +461,7 @@ framework. - **Default:** ``False``. ``REDIS_CACHE_URL`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Allows freely redefining the Redis database URL for the Django cache. @@ -474,7 +470,7 @@ framework. ``redis://:@:/0``. ``CHANNEL_REDIS_URL`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Allows freely redefining the Redis database URL for Django Channels' layer. @@ -483,7 +479,7 @@ framework. ``redis://:@:/1``. ``CELERY_BROKER_URL`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Allows freely redefining the Redis database URL for the Celery broker. @@ -492,7 +488,7 @@ framework. ``redis://:@:/2``. DJANGO_LOG_LEVEL -================ +~~~~~~~~~~~~~~~~ - **Explanation:** Logging level for Django. Refer to the `related Django documentation section @@ -501,14 +497,13 @@ DJANGO_LOG_LEVEL - **Valid Values:** STRING. - **Default:** ``ERROR``. -************************** - Enabled OpenWISP Modules -************************** +Enabled OpenWISP Modules +------------------------ These options allow to disable the optional OpenWISP modules. ``USE_OPENWISP_TOPOLOGY`` -========================= +~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the :doc:`Network Topology ` module is enabled or not. @@ -516,7 +511,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``True``. ``USE_OPENWISP_RADIUS`` -======================= +~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the :doc:`RADIUS ` module is enabled or not. @@ -524,7 +519,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``True``. ``USE_OPENWISP_FIRMWARE`` -========================= +~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the :doc:`Firmware Upgrader ` module is enabled or not. @@ -532,7 +527,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``True``. ``USE_OPENWISP_MONITORING`` -=========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Whether the :doc:`Monitoring ` module is enabled or not. @@ -541,26 +536,25 @@ These options allow to disable the optional OpenWISP modules. .. _docker_postgresql_db_settings: -********************* - PostgreSQL Database -********************* +PostgreSQL Database +------------------- ``DB_NAME`` -=========== +~~~~~~~~~~~ - **Explanation:** The name of the database to use. - **Valid Values:** STRING. - **Default:** ``openwisp_db``. ``DB_USER`` -=========== +~~~~~~~~~~~ - **Explanation:** The username to use when connecting to the database. - **Valid Values:** STRING. - **Default:** ``admin``. ``DB_PASS`` -=========== +~~~~~~~~~~~ - **Explanation:** The password to use when connecting to the database. - **Valid Values:** STRING. @@ -569,7 +563,7 @@ These options allow to disable the optional OpenWISP modules. .. _db_engine: ``DB_HOST`` -=========== +~~~~~~~~~~~ - **Explanation:** Host to be used when connecting to the database. ``localhost`` or empty string are not allowed. @@ -577,14 +571,14 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``postgres``. ``DB_PORT`` -=========== +~~~~~~~~~~~ - **Explanation:** The port to use when connecting to the database. - **Valid Values:** INTEGER. - **Default:** ``5432``. ``DB_SSLMODE`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Postgresql SSLMode option. - **Valid Values:** Consult the related `PostgreSQL documentation @@ -592,21 +586,21 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``disable``. ``DB_SSLCERT`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Path inside container to a valid client certificate. - **Valid Values:** STRING. - **Default:** ``None``. ``DB_SSLKEY`` -============= +~~~~~~~~~~~~~ - **Explanation:** Path inside container to valid client private key. - **Valid Values:** STRING. - **Default:** ``None``. ``DB_SSLROOTCERT`` -================== +~~~~~~~~~~~~~~~~~~ - **Explanation:** Path inside container to a valid server certificate for the database. @@ -614,7 +608,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``None``. ``DB_OPTIONS`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Additional database options to connect to the database. These options must be supported by your :ref:`DB_ENGINE`. @@ -622,7 +616,7 @@ These options allow to disable the optional OpenWISP modules. - **Default:** ``{}``. ``DB_ENGINE`` -============= +~~~~~~~~~~~~~ - **Explanation:** `Django spatial database backend `_ @@ -631,36 +625,35 @@ These options allow to disable the optional OpenWISP modules. `__. - **Default:** ``django.contrib.gis.db.backends.postgis`` -********** - InfluxDB -********** +InfluxDB +-------- InfluxDB is the default time series database used by the :doc:`Monitoring module `. ``INFLUXDB_USER`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Username of InfluxDB user. - **Valid Values:** STRING. - **Default:** ``admin``. ``INFLUXDB_PASS`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Password for InfluxDB user. - **Valid Values:** STRING. - **Default:** ``admin``. ``INFLUXDB_NAME`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Name of InfluxDB database. - **Valid Values:** STRING. - **Default:** ``openwisp``. ``INFLUXDB_HOST`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Host to be used when connecting to influxDB. Values as ``localhost`` or empty string are not allowed. @@ -668,23 +661,22 @@ module `. - **Default:** ``influxdb``. ``INFLUXDB_PORT`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Port on which InfluxDB is listening to. - **Valid Values:** INTEGER. - **Default:** ``8086``. ``INFLUXDB_DEFAULT_RETENTION_POLICY`` -===================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** The default retention policy that applies to the time series data. - **Valid Values:** STRING. - **Default:** ``26280h0m0s`` (3 years). -********* - Postfix -********* +Postfix +------- .. note:: @@ -693,7 +685,7 @@ module `. available. ``POSTFIX_ALLOWED_SENDER_DOMAINS`` -================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Due to in-built spam protection in Postfix you will need to specify sender domains. @@ -701,7 +693,7 @@ module `. - **Default:** ``example.org``. ``POSTFIX_MYHOSTNAME`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** You may configure a specific hostname that the SMTP server will use to identify itself. @@ -709,14 +701,14 @@ module `. - **Default:** ``example.org``. ``POSTFIX_DESTINATION`` -======================= +~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Destinations of the postfix service. - **Valid Values:** Any valid domain name. - **Default:** ``$mydomain, $myhostname``. ``POSTFIX_MESSAGE_SIZE_LIMIT`` -============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** By default, this limit is set to 0 (zero), which means unlimited. Why would you want to set this? Well, this is especially @@ -726,7 +718,7 @@ module `. - **Example:** ``26214400`` ``POSTFIX_MYNETWORKS`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Postfix is exposed only in ``mynetworks`` to prevent any issues with this postfix being inadvertently exposed on the @@ -735,7 +727,7 @@ module `. - **Default:** ``127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128``. ``POSTFIX_RELAYHOST_TLS_LEVEL`` -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Define relay host TLS connection level. - **Valid Values:** `See list @@ -743,7 +735,7 @@ module `. - **Default:** ``may``. ``POSTFIX_RELAYHOST`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Host that relays your mails. - **Valid Values:** any valid IP address or domain name. @@ -751,7 +743,7 @@ module `. - **Example:** ``[smtp.gmail.com]:587``. ``POSTFIX_RELAYHOST_USERNAME`` -============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Username for the relay server. - **Valid Values:** STRING. @@ -759,7 +751,7 @@ module `. - **Example:** ``example@example.com``. ``POSTFIX_RELAYHOST_PASSWORD`` -============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Login password for the relay server. - **Valid Values:** STRING. @@ -767,7 +759,7 @@ module `. - **Example:** ``example``. ``POSTFIX_DEBUG_MYNETWORKS`` -============================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Set debug_peer_list for given list of networks. - **Valid Values:** STRING. @@ -776,37 +768,35 @@ module `. .. _docker_uwsgi_env: -******* - uWSGI -******* +uWSGI +----- ``UWSGI_PROCESSES`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Number of uWSGI process to spawn. - **Valid Values:** INTEGER. - **Default:** ``2``. ``UWSGI_THREADS`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Number of threads each uWSGI process will have. - **Valid Values:** INTEGER. - **Default:** ``2``. ``UWSGI_LISTEN`` -================ +~~~~~~~~~~~~~~~~ - **Explanation:** Value of the listen queue of uWSGI. - **Valid Values:** INTEGER. - **Default:** ``100``. -******* - Nginx -******* +Nginx +----- ``NGINX_HTTP2`` -=============== +~~~~~~~~~~~~~~~ - **Explanation:** Used by nginx to enable http2. Refer to the `related Nginx documentation section @@ -816,7 +806,7 @@ module `. - **Default:** ``http2``. ``NGINX_CLIENT_BODY_SIZE`` -========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Client body size. Refer to the `related Nginx documentation section @@ -826,7 +816,7 @@ module `. - **Default:** ``30``. ``NGINX_IP6_STRING`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Nginx listen on IPv6 for SSL connection. You can either enter a valid nginx statement or leave this value empty. @@ -834,7 +824,7 @@ module `. - **Default:** ``""`` (empty string). ``NGINX_IP6_80_STRING`` -======================= +~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Nginx listen on IPv6 connection. You can either enter a valid nginx statement or leave this value empty. @@ -842,7 +832,7 @@ module `. - **Default:** ``""`` (empty string). ``NGINX_ADMIN_ALLOW_NETWORK`` -============================= +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** IP address allowed to access OpenWISP services. - **Valid Values:** ``all``, IP network. @@ -850,7 +840,7 @@ module `. - **Default:** ``all``. ``NGINX_SERVER_NAME_HASH_BUCKET`` -================================= +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Define the `Nginx domain hash bucket size `__. Values should be only in powers @@ -859,7 +849,7 @@ module `. - **Default:** ``32``. ``NGINX_SSL_CONFIG`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional nginx configurations. You can add any valid server block element here. As an example ``index`` option is configured. @@ -870,7 +860,7 @@ module `. - **Default:** ``""`` (empty string). ``NGINX_80_CONFIG`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Additional nginx configurations. You can add any valid server block element here. As an example ``index`` option is configured. @@ -880,7 +870,7 @@ module `. - **Default:** ``""`` (empty string). ``NGINX_SSL_PORT`` -================== +~~~~~~~~~~~~~~~~~~ - **Explanation:** Nginx container external HTTPS port. Change if, for example, OpenWISP runs behind a reverse proxy listening on port 443 on @@ -890,7 +880,7 @@ module `. - **Default:** ``443``. ``NGINX_PORT`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Nginx container external HTTP port. Change if, for example, OpenWISP runs behind a reverse proxy listening on port 80 on @@ -900,14 +890,14 @@ module `. - **Default:** ``80``. ``NGINX_GZIP_SWITCH`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Turn on/off Nginx GZIP. - **Valid Values:** ``on``, ``off``. - **Default:** ``on``. ``NGINX_GZIP_LEVEL`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Sets a gzip compression level of a response. Acceptable values are in the range from 1 to 9. @@ -915,7 +905,7 @@ module `. - **Default:** ``6``. ``NGINX_GZIP_PROXIED`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Enables or disables gzipping of responses for proxied requests depending on the request and response. @@ -924,7 +914,7 @@ module `. - **Default:** ``any``. ``NGINX_GZIP_MIN_LENGTH`` -========================= +~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Sets the minimum length of a response that will be gzipped. The length is determined only from the "Content-Length" @@ -933,7 +923,7 @@ module `. - **Default:** ``1000``. ``NGINX_GZIP_TYPES`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Enables gzipping of responses for the specified MIME types in addition to "text/html". The special value "\*" matches any @@ -945,7 +935,7 @@ module `. - **Default:** ``\*``. ``NGINX_HTTPS_ALLOWED_IPS`` -=========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Allow these IP addresses to access the website over http when ``SSL_CERT_MODE`` is set to ``Yes`` . @@ -954,7 +944,7 @@ module `. - **Default:** ``all``. ``NGINX_HTTP_ALLOW`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Allow http access with https access. Valid only when ``SSL_CERT_MODE`` is set to ``Yes`` or ``SelfSigned``. @@ -962,7 +952,7 @@ module `. - **Default:** ``True``. ``NGINX_CUSTOM_FILE`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** If you have a custom configuration file mounted, set this to ``True``. @@ -970,7 +960,7 @@ module `. - **Default:** ``False``. ``NINGX_REAL_REMOTE_ADDR`` -========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** The nginx header to get the value of the real IP address of Access points. Example if a reverse proxy is used in your @@ -982,12 +972,11 @@ module `. ``$realip_remote_addr``, ``$real_ip``. - **Default:** ``$real_ip``. -********* - OpenVPN -********* +OpenVPN +------- ``VPN_NAME`` -============ +~~~~~~~~~~~~ - **Explanation:** Name of the VPN Server that will be visible on the OpenWISP dashboard. @@ -995,31 +984,29 @@ module `. - **Default:** ``default``. ``VPN_CLIENT_NAME`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Name of the VPN client template that will be visible on the OpenWISP dashboard. - **Valid Values:** STRING. - **Default:** ``default-management-vpn``. -********** - Topology -********** +Topology +-------- ``TOPOLOGY_UPDATE_INTERVAL`` -============================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Interval in minutes to upload the topology data to the OpenWISP, - **Valid Values:** INTEGER. - **Default:** ``3``. -******************* - X509 Certificates -******************* +X509 Certificates +----------------- ``X509_NAME_CA`` -================ +~~~~~~~~~~~~~~~~ - **Explanation:** Name of the default certificate authority visible on the OpenWISP dashboard. @@ -1027,7 +1014,7 @@ module `. - **Default:** ``default``. ``X509_NAME_CERT`` -================== +~~~~~~~~~~~~~~~~~~ - **Explanation:** Name of the default certificate visible on the OpenWISP dashboard. @@ -1035,7 +1022,7 @@ module `. - **Default:** ``default``. ``X509_COUNTRY_CODE`` -===================== +~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** ISO code of the country of issuance of the certificate. - **Valid Values:** Country code, see list `here @@ -1043,7 +1030,7 @@ module `. - **Default:** ``IN``. ``X509_STATE`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Name of the state / province of issuance of the certificate. @@ -1051,21 +1038,21 @@ module `. - **Default:** ``Delhi``. ``X509_CITY`` -============= +~~~~~~~~~~~~~ - **Explanation:** Name of the city of issuance of the certificate. - **Valid Values:** STRING. - **Default:** ``New Delhi``. ``X509_ORGANIZATION_NAME`` -========================== +~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Name of the organization issuing the certificate. - **Valid Values:** STRING. - **Default:** ``OpenWISP``. ``X509_ORGANIZATION_UNIT_NAME`` -=============================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Name of the unit of the organization issuing the certificate. @@ -1073,7 +1060,7 @@ module `. - **Default:** ``OpenWISP``. ``X509_EMAIL`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Organization email address that'll be available to view in the certificate. @@ -1081,67 +1068,66 @@ module `. - **Default:** ``certificate@example.com``. ``X509_COMMON_NAME`` -==================== +~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Common name for the CA and certificate. - **Valid Values:** STRING. - **Default:** ``OpenWISP``. -*************** - Misc Services -*************** +Misc Services +------------- ``REDIS_HOST`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Host to establish redis connection. - **Valid Values:** A valid hostname or IP address. - **Default:** ``redis``. ``REDIS_PORT`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Port to establish redis connection. - **Valid Values:** INTEGER. - **Default:** ``6379``. ``REDIS_USER`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Redis username, optional. - **Valid Values:** STRING. - **Default:** ``""`` (empty string). ``REDIS_PASS`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Redis password, optional. - **Valid Values:** STRING. - **Default:** ``None``. ``REDIS_USE_TLS`` -================= +~~~~~~~~~~~~~~~~~ - **Explanation:** Whether to use TLS for redis connection. - **Valid Values:** ``True``, ``False``. - **Default:** ``False``. ``DASHBOARD_APP_SERVICE`` -========================= +~~~~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Host to establish OpenWISP dashboard connection. - **Valid Values:** Any hostname or IP address. - **Default:** ``dashboard``. ``API_APP_SERVICE`` -=================== +~~~~~~~~~~~~~~~~~~~ - **Explanation:** Host to establish OpenWISP api connection. - **Valid Values:** Any hostname or IP address. - **Default:** ``api``. ``DASHBOARD_APP_PORT`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** The port on which nginx tries to get the OpenWISP dashboard container. Don't Change unless you know what you are doing. @@ -1149,7 +1135,7 @@ module `. - **Default:** ``8000``. ``API_APP_PORT`` -================ +~~~~~~~~~~~~~~~~ - **Explanation:** The port on which nginx tries to get the OpenWISP api container. Don't Change unless you know what you are doing. @@ -1157,7 +1143,7 @@ module `. - **Default:** ``8001``. ``WEBSOCKET_APP_PORT`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** The port on which nginx tries to get the OpenWISP websocket container. Don't Change unless you know what you are doing. @@ -1165,7 +1151,7 @@ module `. - **Default:** ``8002``. ``DASHBOARD_INTERNAL`` -====================== +~~~~~~~~~~~~~~~~~~~~~~ - **Explanation:** Internal dashboard domain to reach dashboard from other containers. @@ -1173,18 +1159,17 @@ module `. - **Default:** ``dashboard.internal``. ``API_INTERNAL`` -================ +~~~~~~~~~~~~~~~~ - **Explanation:** Internal api domain to reach api from other containers. - **Valid Values:** STRING. - **Default:** ``api.internal``. -************ - NFS Server -************ +NFS Server +---------- ``EXPORT_DIR`` -============== +~~~~~~~~~~~~~~ - **Explanation:** Directory to be exported by the NFS server. Don't change this unless you know what you are doing. @@ -1192,7 +1177,7 @@ module `. - **Default:** ``/exports``. ``EXPORT_OPTS`` -=============== +~~~~~~~~~~~~~~~ - **Explanation:** NFS export options for the directory in ``EXPORT_DIR`` variable. @@ -1201,7 +1186,7 @@ module `. ``10.0.0.0/8(rw,fsid=0,insecure,no_root_squash,no_subtree_check,sync)``. ``COLLECTSTATIC_WHEN_DEPS_CHANGE`` -================================== +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - **Description:** Runs ``collectstatic`` at container startup only if Python dependencies have changed. Set to ``false`` if you're using the diff --git a/requirements-test.txt b/requirements-test.txt index 8a6b6c72..57875b35 100644 --- a/requirements-test.txt +++ b/requirements-test.txt @@ -1,2 +1,3 @@ docker>=7.1.0,<7.2.0 openwisp-utils[qa,selenium]~=1.2.0 +sphinx<8.0.0