[docs] Restructured Documentation

Restructured the documentation in a way that allows it to
be included in the Unified Documentation of OpenWISP.

For more information see openwisp/openwisp-docs#107.

---------

Co-authored-by: Federico Capoano <[email protected]>

README.rst

@@ -0,0 +1,32 @@
+ansible-openwisp2
+=================
+
+.. image:: https://github.com/openwisp/ansible-openwisp2/workflows/Ansible%20OpenWISP2%20CI%20Build/badge.svg?branch=master
+    :target: https://github.com/openwisp/ansible-openwisp2/actions?query=workflow%3A%22Ansible+OpenWISP2+CI+Build%22
+    :alt: Build Status
+
+.. image:: http://img.shields.io/badge/galaxy-openwisp.openwisp2-blue.svg?style=flat-square
+    :target: https://galaxy.ansible.com/ui/standalone/roles/openwisp/openwisp2/
+    :alt: Galaxy
+
+.. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg
+    :target: https://gitter.im/openwisp/general
+    :alt: Chat
+
+Ansible role that installs the OpenWISP Server Application.
+
+Tested on **Debian (Bookworm/Bullseye)**, **Ubuntu (24/22/20 LTS)**.
+
+**Recommended minimum ansible core version**: 2.13.
+
+Documentation
+-------------
+
+- `Developer documentation
+  <https://openwisp.io/docs/dev/ansible-openwisp2/developer/>`_
+- `User documentation <https://openwisp.io/docs/dev/ansible-openwisp2/>`_
+
+Support
+-------
+
+See `OpenWISP Support Channels <http://openwisp.org/support.html>`__.

docs/developer/installation.rst

@@ -0,0 +1,100 @@
+Developer Installation instructions
+===================================
+
+.. include:: ../partials/developer-docs.rst
+
+.. contents:: **Table of Contents**:
+    :depth: 2
+    :local:
+
+Installing for Development
+--------------------------
+
+First of all, create the directory where you want to place the
+repositories of the ansible roles and create directory roles.
+
+.. code-block:: bash
+
+    mkdir -p ~/openwisp-dev/roles
+    cd ~/openwisp-dev/roles
+
+Clone ``ansible-openwisp2`` and ``Stouts.postfix`` as follows:
+
+.. code-block:: bash
+
+    git clone https://github.com/openwisp/ansible-openwisp2.git openwisp.openwisp2
+    git clone https://github.com/Stouts/Stouts.postfix
+    git clone https://github.com/openwisp/ansible-ow-influxdb openwisp.influxdb
+
+Now, go to the parent directory & create hosts file and playbook.yml:
+
+.. code-block:: bash
+
+    cd ../
+    touch hosts
+    touch playbook.yml
+
+From here on you can follow the instructions available at the following
+sections:
+
+- :ref:`ansible_install`
+- :ref:`ansible_create_inventory_file`
+- :ref:`ansible_create_playbook_file`
+- :ref:`ansible_run_playbook`
+
+All done!
+
+How to Run Tests
+----------------
+
+If you want to contribute to ``ansible-openwisp2`` you should run tests in
+your development environment to ensure your changes are not breaking
+anything.
+
+To do that, proceed with the following steps:
+
+**Step 1**: Clone ``ansible-openwisp2``
+
+Clone repository by:
+
+.. code-block:: shell
+
+    git clone https://github.com/<your_fork>/ansible-openwisp2.git openwisp.openwisp2
+    cd openwisp.openwisp2
+
+**Step 2**: Install docker
+
+If you haven't installed docker yet, you need to install it (example for
+linux debian/ubuntu systems):
+
+.. code-block:: shell
+
+    sudo apt install docker.io
+
+**Step 3**: Install molecule and dependencies
+
+.. code-block:: shell
+
+    pip install molecule[docker] molecule-plugins yamllint ansible-lint docker
+
+**Step 4**: Download docker images
+
+.. code-block:: shell
+
+    docker pull geerlingguy/docker-ubuntu2204-ansible:latest
+    docker pull geerlingguy/docker-ubuntu2004-ansible:latest
+    docker pull geerlingguy/docker-debian11-ansible:latest
+
+**Step 5**: Run molecule test
+
+.. code-block:: shell
+
+    molecule test -s local
+
+If you don't get any error message it means that the tests ran
+successfully without errors.
+
+.. important::
+
+    **Pro Tip:** Use ``molecule test --destroy=never`` to speed up
+    subsequent test runs.

docs/index.rst

@@ -0,0 +1,51 @@
+Ansible OpenWISP
+================
+
+.. seealso::
+
+    **Source code**: `github.com/openwisp/ansible-openwisp2
+    <https://github.com/openwisp/ansible-openwisp2>`_.
+
+This ansible role allows deploying the OpenWISP Server Application.
+
+**Recommended minimum ansible core version**: 2.13.
+
+Tested on **Debian (Bookworm/Bullseye)**, **Ubuntu (24/22/20 LTS)**.
+
+The following diagram illustrates the role of the Ansible OpenWISP role
+within the OpenWISP architecture.
+
+.. figure:: images/architecture-v2-ansible-openwisp.png
+    :target: ../_images/architecture-v2-ansible-openwisp.png
+    :align: center
+    :alt: OpenWISP Architecture: Ansible OpenWISP role
+
+    **OpenWISP Architecture: highlighted Ansible OpenWISP role**
+
+.. important::
+
+    For an enhanced viewing experience, open the image above in a new
+    browser tab.
+
+    Refer to :doc:`/general/architecture` for more information.
+
+.. toctree::
+    :caption: Ansible OpenWISP Usage Docs
+    :maxdepth: 1
+
+    ./user/system-requirements.rst
+    ./user/quickstart.rst
+    ./user/certbot-ssl.rst
+    ./user/enabling-modules.rst
+    ./user/deploying-wpa-eap-ttls-pap.rst
+    ./user/deploying-custom-static-content.rst
+    ./user/configuring-cors-headers.rst
+    ./user/installing-on-vm.rst
+    ./user/troubleshooting.rst
+    ./user/role-variables.rst
+
+.. toctree::
+    :caption: Ansible OpenWISP Developer Docs
+    :maxdepth: 1
+
+    ./developer/installation.rst

docs/partials/developer-docs.rst

@@ -0,0 +1,12 @@
+.. note::
+
+    This documentation page is aimed at developers who want to customize,
+    change or extend the code of Ansible OpenWISP2 in order to modify its
+    behavior (eg: for personal or commercial purposes or to fix a bug,
+    implement a new feature or contribute to the project in general).
+
+    If you aren't a developer and you are looking for information on how
+    to use OpenWISP, please refer to:
+
+    - :doc:`General OpenWISP Quickstart </user/quickstart>`
+    - :doc:`Ansible OpenWISP2 User Docs </ansible/index>`

docs/user/certbot-ssl.rst

@@ -0,0 +1,65 @@
+Using Let's Encrypt SSL Certificate
+===================================
+
+This section explains how to **automatically install and renew a valid SSL
+certificate** signed by `Let's Encrypt <https://letsencrypt.org/>`__.
+
+The first thing you have to do is to setup a valid domain for your
+OpenWISP instance, this means your inventory file (hosts) should look like
+the following:
+
+.. code-block:: text
+
+    [openwisp2]
+    openwisp2.yourdomain.com
+
+You must be able to add a DNS record for ``openwisp2.yourdomain.com``, you
+cannot use an ip address in place of ``openwisp2.yourdomain.com``.
+
+Once your domain is set up and the DNS record is propagated, proceed by
+installing the ansible role `geerlingguy.certbot
+<https://galaxy.ansible.com/geerlingguy/certbot/>`__:
+
+.. code-block:: shell
+
+    ansible-galaxy install geerlingguy.certbot
+
+Then proceed to edit your ``playbook.yml`` so that it will look similar to
+the following example:
+
+.. code-block:: yaml
+
+    - hosts: openwisp2
+      become: "{{ become | default('yes') }}"
+      roles:
+        - geerlingguy.certbot
+        - openwisp.openwisp2
+      vars:
+        # SSL certificates
+        openwisp2_ssl_cert: "/etc/letsencrypt/live/{{ inventory_hostname }}/fullchain.pem"
+        openwisp2_ssl_key: "/etc/letsencrypt/live/{{ inventory_hostname }}/privkey.pem"
+
+        # certbot configuration
+        certbot_auto_renew_minute: "20"
+        certbot_auto_renew_hour: "5"
+        certbot_create_if_missing: true
+        certbot_auto_renew_user: "<privileged-users-to-renew-certs>"
+        certbot_certs:
+          - email: "<paste-your-email>"
+            domains:
+              - "{{ inventory_hostname }}"
+      pre_tasks:
+        - name: Update APT package cache
+          apt:
+            update_cache: true
+            changed_when: false
+            retries: 5
+            delay: 10
+            register: result
+            until: result is success
+
+Read the `documentation of geerlingguy.certbot
+<https://github.com/geerlingguy/ansible-role-certbot#readme>`__ to learn
+more about configuration of certbot role.
+
+Once you have set up all the variables correctly, run the playbook again.

docs/user/configuring-cors-headers.rst

@@ -0,0 +1,73 @@
+Configuring CORS Headers
+========================
+
+While integrating OpenWISP with external services, you can run into issues
+related to `CORS (Cross-Origin Resource Sharing)
+<https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`__. This role
+allows users to configure the CORS headers with the help of
+`django-cors-headers
+<https://github.com/adamchainz/django-cors-headers>`__ package. Here's a
+short summary of how to do this:
+
+**Step 1**: :ref:`Install ansible <ansible_install>`
+
+**Step 2**: :ref:`Install this role <ansible_install_role>`
+
+**Step 3**: :ref:`Create inventory file <ansible_create_inventory_file>`
+
+**Step 4**: Create a playbook file with following contents:
+
+.. code-block:: yaml
+
+    - hosts: openwisp2
+      become: "{{ become | default('yes') }}"
+      roles:
+        - openwisp.openwisp2
+      vars:
+        # Cross-Origin Resource Sharing (CORS) settings
+        openwisp2_django_cors:
+          enabled: true
+          allowed_origins_list:
+            - https://frontend.openwisp.org
+            - https://logs.openwisp.org
+
+**Note:** to learn about the supported fields of the
+``openwisp2_django_cors`` variable, look for the word
+“openwisp2_django_cors” in the :doc:`role-variables` section of this
+document.
+
+**Step 5**: :ref:`Run the playbook <ansible_run_playbook>`
+
+When the playbook is done running, if you got no errors you can login at
+https://openwisp2.mydomain.com/admin, with the following credentials:
+
+.. code-block:: text
+
+    username: admin
+    password: admin
+
+The ansible-openwisp2 only provides abstraction (variables) for handful of
+settings available in `django-cors-headers
+<https://github.com/adamchainz/django-cors-headers>`__ module. Use the
+``openwisp2_extra_django_settings_instructions`` or
+``openwisp2_extra_django_settings`` variable to configure additional
+setting of ``django-cors-headers`` as shown in the following example:
+
+.. code-block:: yaml
+
+    - hosts: openwisp2
+      become: "{{ become | default('yes') }}"
+      roles:
+        - openwisp.openwisp2
+      vars:
+        openwisp2_django_cors:
+          enabled: true
+          allowed_origins_list:
+            - https://frontend.openwisp.org
+            - https://logs.openwisp.org
+          replace_https_referer: true
+        # Configuring additional settings for django-cors-headers
+        openwisp2_extra_django_settings_instructions:
+          - |
+            CORS_ALLOW_CREDENTIALS = True
+            CORS_ALLOW_ALL_ORIGINS = True

docs/user/deploying-custom-static-content.rst

@@ -0,0 +1,14 @@
+Deploying Custom Static Content
+===============================
+
+For deploying custom static content (HTML files, etc.) add all the static
+content in ``files/ow2_static`` directory. The files inside
+``files/ow2_static`` will be uploaded to a directory named
+``static_custom`` in ``openwisp2_path``.
+
+This is helpful for :ref:`customizing OpenWISP's theme
+<openwisp_admin_theme_links>`.
+
+E.g., if you added a custom CSS file in
+``files/ow2_static/css/custom.css``, the file location to use in
+:ref:`openwisp_admin_theme_links` setting will be ``css/custom.css``.