docs: improve description of uwsgi & ngingx setup

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

7 files changed, 124 insertions, 56 deletions

diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst
index 2bc663411..785b02261 100644
--- a/docs/admin/filtron.rst
+++ b/docs/admin/filtron.rst
@@ -1,5 +1,5 @@
 
-.. _searx_filtron:
+.. _searx filtron:
 
 ==========================
 How to protect an instance
@@ -8,6 +8,8 @@ How to protect an instance
 .. sidebar:: further reading
 
    - :ref:`filtron.sh`
+   - :ref:`nginx searx site`
+
 
 .. contents:: Contents
    :depth: 2
@@ -150,6 +152,8 @@ of:
    ]
 
 
+.. _filtron route request:
+
 Route request through filtron
 =============================
 
@@ -167,12 +171,14 @@ Use it along with ``nginx`` with the following example configuration.
 .. code:: nginx
 
    location / {
-        proxy_set_header   Host    $http_host;
-        proxy_set_header   X-Real-IP $remote_addr;
-        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header   X-Scheme $scheme;
-        proxy_pass         http://127.0.0.1:4004/;
+       proxy_pass         http://127.0.0.1:4004/;
+
+       proxy_set_header   Host             $http_host;
+       proxy_set_header   X-Real-IP        $remote_addr;
+       proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
+       proxy_set_header   X-Scheme         $scheme;
    }
 
 Requests are coming from port 4004 going through filtron and then forwarded to
-port 8888 where a searx is being run.
+port 8888 where a searx is being run. For a complete setup see: :ref:`nginx
+searx site`.
diff --git a/docs/admin/installation-nginx.rst b/docs/admin/installation-nginx.rst
index 6cd815d1d..0b3ea022f 100644
--- a/docs/admin/installation-nginx.rst
+++ b/docs/admin/installation-nginx.rst
@@ -12,6 +12,12 @@ Install with nginx
    http://nginx.org/en/docs/beginners_guide.html
 .. _Getting Started wiki:
    https://www.nginx.com/resources/wiki/start/
+.. _uWSGI support from nginx:
+   https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
+.. _uwsgi_params:
+   https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html#configuring-nginx
+.. _SCRIPT_NAME:
+   https://werkzeug.palletsprojects.com/en/1.0.x/wsgi/#werkzeug.wsgi.get_script_name
 
 .. contents:: Contents
    :depth: 2
@@ -98,8 +104,8 @@ see a *Fedora Webserver - Test Page*.  The test page comes from the default
 
 .. _nginx searx site:
 
-A searx site
-============
+A nginx searx site
+==================
 
 .. sidebar:: public to the internet?
 
@@ -134,33 +140,42 @@ Started wiki`_ is always a good resource *to keep in the pocket*.
 
 .. tabs::
 
+   .. group-tab:: searx via filtron plus morty
 
-   .. group-tab:: filtron at ``/`` & ``/morty``
-
-      Use this setup, if your instance is public to the internet:
+      Use this setup, if your instance is public to the internet, compare
+      figure: :ref:`architecture <arch public>`.  Configure a reverse proxy for
+      :ref:`filtron <filtron.sh>`, listening on *localhost 4004* (:ref:`filtron
+      route request`):
 
       .. code:: nginx
 
          location / {
-             proxy_set_header   Host    $http_host;
-             proxy_set_header   X-Real-IP $remote_addr;
-             proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
-             proxy_set_header   X-Scheme $scheme;
              proxy_pass         http://127.0.0.1:4004/;
+
+             proxy_set_header   Host             $http_host;
+             proxy_set_header   X-Real-IP        $remote_addr;
+             proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
+             proxy_set_header   X-Scheme         $scheme;
          }
 
+
+      Configure reverse proxy for :ref:`morty <searx morty>`, listening on
+      *localhost 3000*:
+
       .. code:: nginx
 
          location /morty {
-             proxy_set_header   Host    $http_host;
-             proxy_set_header   X-Real-IP $remote_addr;
-             proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
-             proxy_set_header   X-Scheme $scheme;
              proxy_pass         http://127.0.0.1:3000/;
+
+             proxy_set_header   Host             $http_host;
+             proxy_set_header   X-Real-IP        $remote_addr;
+             proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
+             proxy_set_header   X-Scheme         $scheme;
          }
 
-      For a fully result proxification add :ref:`morty's <searx_morty>` public
-      URL to your :origin:`searx/settings.yml`:
+      Note that reverse proxy advised to be used in case of single-user or
+      low-traffic instances.  For a fully result proxification add :ref:`morty's
+      <searx morty>` **public URL** to your :origin:`searx/settings.yml`:
 
       .. code:: yaml
 
@@ -169,66 +184,108 @@ Started wiki`_ is always a good resource *to keep in the pocket*.
              url : http://searx.example.com/
 
 
-   .. group-tab:: searx at ``/``
+   .. group-tab:: proxy or uWSGI
 
-      Use this setup only, if your instance is **NOT** public to the internet:
+      Be warned, with this setup, your Instance isn't :ref:`protected <searx
+      filtron>`.  Nevertheless it is good enough for intranet usage and it is a
+      excellent example of; *how different services can be set up*.  The next
+      example shows a reverse proxy configuration wrapping the :ref:`searx-uWSGI
+      application <uwsgi configuration>`, listening on ``http =
+      127.0.0.1:8888``.
 
       .. code:: nginx
 
-         server {
-             listen 80;
-             listen [::]:80;
+          location / {
+              proxy_pass http://127.0.0.1:8888;
 
+              proxy_set_header Host $host;
+              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+              proxy_set_header X-Scheme $scheme;
+              proxy_set_header X-Script-Name /searx;
+              proxy_buffering off;
+          }
+
+      Alternatively you can use the `uWSGI support from nginx`_ via unix
+      sockets.  For socket communication, you have to activate ``socket =
+      /run/uwsgi/app/searx/socket`` and comment out the ``http =
+      127.0.0.1:8888`` configuration in your :ref:`uwsgi ini file <uwsgi
+      configuration>`.
+
+      The example shows a nginx virtual ``server`` configuration, listening on
+      port 80 (IPv4 and IPv6 http://[::]:80).  The uWSGI app is configured at
+      location ``/`` by importing the `uwsgi_params`_ and passing requests to
+      the uWSGI socket (``uwsgi_pass``).  The ``server``\'s root points to the
+      :ref:`searx-src clone <searx-src>` and wraps directly the
+      :origin:`searx/static/` content at ``location /static``.
+
+      .. code:: nginx
+
+         server {
              # replace searx.example.com with your server's public name
              server_name searx.example.com;
 
-             root /usr/local/searx/searx;
-
-             location /static {
-             }
+             listen 80;
+             listen [::]:80;
 
              location / {
                  include uwsgi_params;
                  uwsgi_pass unix:/run/uwsgi/app/searx/socket;
              }
+
+	     root /usr/local/searx/searx-src/searx;
+             location /static { }
          }
 
-   .. group-tab:: searx at ``/searx``
+      If not already exists, create a folder for the unix sockets, which can be
+      used by the searx account:
 
-      Use this setup only, if your instance is **NOT** public to the internet:
+      .. code:: bash
 
-      .. code:: nginx
+	 mkdir -p /run/uwsgi/app/searx/
+	 sudo -H chown -R searx:searx /run/uwsgi/app/searx/
 
-          location /searx/static {
-                  alias /usr/local/searx/searx/static;
-          }
+   .. group-tab:: subdirectory URL
+
+      Be warned, with these setups, your Instance isn't :ref:`protected <searx
+      filtron>`.  The examples are just here to demonstrate how to export the
+      searx application from a subdirectory URL
+      http://searx.example.com/searx/\.
+
+      .. code:: nginx
 
           location /searx {
-                  uwsgi_param SCRIPT_NAME /searx;
-                  include uwsgi_params;
-                  uwsgi_pass unix:/run/uwsgi/app/searx/socket;
+              proxy_pass http://127.0.0.1:8888;
+
+              proxy_set_header Host $host;
+              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+              proxy_set_header X-Scheme $scheme;
+              proxy_set_header X-Script-Name /searx;
+              proxy_buffering off;
           }
 
+          location /searx/static {
+              alias /usr/local/searx/searx-src/searx/static;
+          }
 
-      **OR** using reverse proxy.  Please, note that reverse proxy advised to be
-      used in case of single-user or low-traffic instances.
+      The ``X-Script-Name /searx`` is needed by the searx implementation to
+      calculate relative URLs correct.  The next example shows a uWSGI
+      configuration.  Since there are no HTTP headers in a (u)WSGI protocol, the
+      value is shipped via the SCRIPT_NAME_ in the WSGI environment.
 
       .. code:: nginx
 
           location /searx/static {
-                  alias /usr/local/searx/searx/static;
+              alias /usr/local/searx/searx-src/searx;
           }
 
           location /searx {
-              proxy_pass http://127.0.0.1:8888;
-              proxy_set_header Host $host;
-              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-              proxy_set_header X-Scheme $scheme;
-              proxy_set_header X-Script-Name /searx;
-              proxy_buffering off;
+              uwsgi_param SCRIPT_NAME /searx;
+              include uwsgi_params;
+              uwsgi_pass unix:/run/uwsgi/app/searx/socket;
           }
 
-      Enable ``base_url`` in :origin:`searx/settings.yml`
+      For searx to work correctly the ``base_url`` must be set in the
+      :origin:`searx/settings.yml`.
 
       .. code:: yaml
 
@@ -246,21 +303,21 @@ Restart service:
       .. code:: sh
 
          sudo -H systemctl restart nginx
-         sudo -H systemctl restart uwsgi
+         sudo -H service uwsgi restart searx
 
    .. group-tab:: Arch Linux
 
       .. code:: sh
 
          sudo -H systemctl restart nginx
-         sudo -H systemctl restart uwsgi
+         sudo -H systemctl restart uwsgi@searx
 
    .. group-tab:: Fedora
 
       .. code:: sh
 
          sudo -H systemctl restart nginx
-         sudo -H systemctl restart uwsgi
+         sudo -H touch /etc/uwsgi.d/searx.ini
 
 
 Disable logs
diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst
index 88562f3e3..91891d85c 100644
--- a/docs/admin/installation-searx.rst
+++ b/docs/admin/installation-searx.rst
@@ -32,6 +32,8 @@ Create user
    :start-after: START create user
    :end-before: END create user
 
+.. _searx-src:
+
 install searx & dependencies
 ============================
 
diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst
index 7996bf937..67a8e127a 100644
--- a/docs/admin/installation-uwsgi.rst
+++ b/docs/admin/installation-uwsgi.rst
@@ -92,6 +92,8 @@ could control specific instance(s) by issuing::
 
 My experience is, that this command is a bit buggy.
 
+.. _uwsgi configuration:
+
 Alltogether
 ===========
 
diff --git a/docs/admin/morty.rst b/docs/admin/morty.rst
index 9af9b6ae9..48ff5b9c4 100644
--- a/docs/admin/morty.rst
+++ b/docs/admin/morty.rst
@@ -1,5 +1,5 @@
 
-.. _searx_morty:
+.. _searx morty:
 
 =========================
 How to setup result proxy
diff --git a/docs/utils/filtron.sh.rst b/docs/utils/filtron.sh.rst
index 1bba1b3e4..e6d7d6251 100644
--- a/docs/utils/filtron.sh.rst
+++ b/docs/utils/filtron.sh.rst
@@ -8,7 +8,7 @@
 .. sidebar:: further reading
 
    - :ref:`installation`
-   - :ref:`searx_filtron`
+   - :ref:`searx filtron`
    - :ref:`architecture`
 
 .. _Go: https://golang.org/
@@ -64,6 +64,7 @@ To install searx in your public HTTP server use:
 		  $ sudo -H a2enmod proxy
 		  $ sudo -H a2enmod proxy_http
 
+.. _filtron.sh overview:
 
 Overview
 ========
diff --git a/docs/utils/morty.sh.rst b/docs/utils/morty.sh.rst
index 9997ffec5..5ab6ee982 100644
--- a/docs/utils/morty.sh.rst
+++ b/docs/utils/morty.sh.rst
@@ -26,7 +26,7 @@ into this user account.
 
 .. hint::
 
-   To add morty to your searx instance read chapter :reF:`searx_morty`.
+   To add morty to your searx instance read chapter :ref:`searx morty`.
 
 
 Overview