docs: improve description of uwsgi & ngingx setup

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

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`.

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

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
 ============================
 

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
 ===========
 

docs/admin/morty.rst

@@ -1,5 +1,5 @@
 
-.. _searx_morty:
+.. _searx morty:
 
 =========================
 How to setup result proxy

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
 ========

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

utils/lib.sh

@@ -881,6 +881,7 @@ uWSGI_enable_app() {
             mkdir -p "${uWSGI_APPS_ENABLED}"
             rm -f "${uWSGI_APPS_ENABLED}/${CONF}"
             ln -s "${uWSGI_APPS_AVAILABLE}/${CONF}" "${uWSGI_APPS_ENABLED}/${CONF}"
+            systemctl enable "uwsgi@${CONF%.*}"
             info_msg "enabled uWSGI app: ${CONF} (restart required)"
             ;;
         fedora-*)

utils/searx.sh

@@ -88,7 +88,7 @@ usage() {
 usage::
 
   $(basename "$0") shell
-  $(basename "$0") install    [all|user|searx-src|pyenv|apache]
+  $(basename "$0") install    [all|user|searx-src|pyenv|uwsgi|apache]
   $(basename "$0") update     [searx]
   $(basename "$0") remove     [all|user|pyenv|searx-src]
   $(basename "$0") activate   [service]
@@ -104,6 +104,7 @@ install / remove
   :user:       add/remove service user '$SERVICE_USER' ($SERVICE_HOME)
   :searx-src:  clone $SEARX_GIT_URL
   :pyenv:      create/remove virtualenv (python) in $SEARX_PYENV
+  :uwsgi:      install searx uWSGI application
   :settings:   reinstall settings from ${REPO_ROOT}/searx/settings.yml
 update searx
   Update searx installation ($SERVICE_HOME)
@@ -165,6 +166,7 @@ main() {
                 pyenv) create_pyenv ;;
                 searx-src) clone_searx ;;
                 settings) install_settings ;;
+                uwsgi) install_searx_uwsgi;;
                 *) usage "$_usage"; exit 42;;
             esac ;;
         update)

utils/templates/etc/uwsgi/apps-archlinux/searx.ini

@@ -57,10 +57,24 @@ virtualenv = ${SEARX_PYENV}
 pythonpath = ${SEARX_SRC}
 
 
-# plugin http
-# -----------
+# speak to upstream
+# -----------------
 #
-# https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http
+# Activate the 'http' configuration for filtron or activate the 'socket'
+# configuration if you setup your HTTP server to use uWSGI protocol via sockets.
 
+# using IP:
+#
+# https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http
 # Native HTTP support: https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html
+
 http = ${SEARX_INTERNAL_URL}
+
+# using unix-sockets:
+#
+# On some distributions you need to create the app folder for the sockets::
+#
+#   mkdir -p /run/uwsgi/app/searx/socket
+#   chmod -R ${SERVICE_USER}:${SERVICE_GROUP}  /run/uwsgi/app/searx/socket
+#
+# socket = /run/uwsgi/app/searx/socket

utils/templates/etc/uwsgi/apps-available/searx.ini

@@ -56,10 +56,24 @@ virtualenv = ${SEARX_PYENV}
 pythonpath = ${SEARX_SRC}
 
 
-# plugin http
-# -----------
+# speak to upstream
+# -----------------
 #
-# https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http
+# Activate the 'http' configuration for filtron or activate the 'socket'
+# configuration if you setup your HTTP server to use uWSGI protocol via sockets.
 
+# using IP:
+#
+# https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http
 # Native HTTP support: https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html
+
 http = ${SEARX_INTERNAL_URL}
+
+# using unix-sockets:
+#
+# On some distributions you need to create the app folder for the sockets::
+#
+#   mkdir -p /run/uwsgi/app/searx/socket
+#   chmod -R ${SERVICE_USER}:${SERVICE_GROUP}  /run/uwsgi/app/searx/socket
+#
+# socket = /run/uwsgi/app/searx/socket