docs: improve description of uwsgi & ngingx setup

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

1 files changed, 103 insertions, 46 deletions

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