[doc] update documentation of the installation procedures

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

1 files changed, 149 insertions, 276 deletions

diff --git a/docs/admin/installation-apache.rst b/docs/admin/installation-apache.rst
index b60e20ad1..ca919812e 100644
--- a/docs/admin/installation-apache.rst
+++ b/docs/admin/installation-apache.rst
@@ -1,13 +1,13 @@
 .. _installation apache:
 
-===================
-Install with apache
-===================
+======
+Apache
+======
 
 .. _Apache: https://httpd.apache.org/
 .. _Apache Debian:
     https://cwiki.apache.org/confluence/display/HTTPD/DistrosDefaultLayout#DistrosDefaultLayout-Debian,Ubuntu(Apachehttpd2.x):
-.. _README.Debian:
+.. _apache2.README.Debian:
     https://salsa.debian.org/apache-team/apache2/raw/master/debian/apache2.README.Debian
 .. _Apache Arch Linux:
     https://wiki.archlinux.org/index.php/Apache_HTTP_Server
@@ -23,7 +23,9 @@ Install with apache
     https://httpd.apache.org/docs/current/en/configuring.html
 .. _ProxyPreserveHost: https://httpd.apache.org/docs/trunk/mod/mod_proxy.html#proxypreservehost
 .. _LoadModule:
-    https://httpd.apache.org/docs/2.4/mod/mod_so.html#loadmodule
+    https://httpd.apache.org/docs/mod/mod_so.html#loadmodule
+.. _IncludeOptional:
+    https://httpd.apache.org/docs/mod/core.html#includeoptional
 .. _DocumentRoot:
     https://httpd.apache.org/docs/trunk/mod/core.html#documentroot
 .. _Location:
@@ -32,11 +34,30 @@ Install with apache
     https://uwsgi-docs.readthedocs.io/en/latest/Apache.html
 .. _mod_proxy_uwsgi:
     https://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-proxy-uwsgi
+.. _mod_proxy_http:
+    https://httpd.apache.org/docs/current/mod/mod_proxy_http.html
+.. _mod_proxy:
+    https://httpd.apache.org/docs/current/mod/mod_proxy.html
+
+
+This section explains how to set up a SearXNG site using the HTTP server Apache_.
+If you have used the :ref:`installation scripts` and do not have any preference
+you can install the :ref:`SearXNG site <apache searxng site>` using
+:ref:`searxng.sh <searxng.sh overview>`:
+
+.. code:: bash
+
+   $ sudo -H ./utils/searxng.sh install apache
+
+If you have special interests or problems with setting up Apache, the following
+section might give you some guidance.
+
 
 .. sidebar:: further read
 
    - `Apache Arch Linux`_
-   - `Apache Debian`_ and `README.Debian`_
+   - `Apache Debian`_
+   - `apache2.README.Debian`_
    - `Apache Fedora`_
    - `Apache directives`_
 
@@ -45,23 +66,8 @@ Install with apache
    :local:
    :backlinks: entry
 
-----
-
-**Install** :ref:`apache searxng site` using :ref:`filtron.sh <filtron.sh overview>`
-
-.. code:: bash
-
-   $ sudo -H ./utils/filtron.sh apache install
-
-**Install** :ref:`apache searxng site` using :ref:`morty.sh <morty.sh overview>`
-
-.. code:: bash
 
-   $ sudo -H ./utils/morty.sh apache install
-
-----
-
-The apache HTTP server
+The Apache HTTP server
 ======================
 
 If Apache_ is not installed, install it now. If apache_ is new to you, the
@@ -73,13 +79,13 @@ Directives`_ documentation gives first orientation.  There is also a list of
 
    .. group-tab:: Ubuntu / debian
 
-      .. code:: sh
+      .. code:: bash
 
          sudo -H apt-get install apache2
 
    .. group-tab:: Arch Linux
 
-      .. code:: sh
+      .. code:: bash
 
          sudo -H pacman -S apache
          sudo -H systemctl enable httpd
@@ -87,7 +93,7 @@ Directives`_ documentation gives first orientation.  There is also a list of
 
    .. group-tab::  Fedora / RHEL
 
-      .. code:: sh
+      .. code:: bash
 
          sudo -H dnf install httpd
          sudo -H systemctl enable httpd
@@ -101,7 +107,7 @@ How this default intro site is configured, depends on the linux distribution
 
    .. group-tab:: Ubuntu / debian
 
-      .. code:: sh
+      .. code:: bash
 
          less /etc/apache2/sites-enabled/000-default.conf
 
@@ -115,7 +121,7 @@ How this default intro site is configured, depends on the linux distribution
 
    .. group-tab:: Arch Linux
 
-      .. code:: sh
+      .. code:: bash
 
          less /etc/httpd/conf/httpd.conf
 
@@ -130,8 +136,8 @@ How this default intro site is configured, depends on the linux distribution
              Require all granted
          </Directory>
 
-      The *welcome* page of Arch Linux is a page showing directory located at
-      ``DocumentRoot``.  This is *directory* page is generated by the Module
+      The *welcome* page of Arch Linux is a page showing the directory located
+      at ``DocumentRoot``.  This *directory* page is generated by the Module
       `mod_autoindex <https://httpd.apache.org/docs/2.4/mod/mod_autoindex.html>`_:
 
       .. code:: apache
@@ -142,7 +148,7 @@ How this default intro site is configured, depends on the linux distribution
 
    .. group-tab::  Fedora / RHEL
 
-      .. code:: sh
+      .. code:: bash
 
          less /etc/httpd/conf/httpd.conf
 
@@ -163,323 +169,204 @@ How this default intro site is configured, depends on the linux distribution
 
         less /etc/httpd/conf.d/welcome.conf
 
-.. _apache searxng site:
 
-Apache Reverse Proxy
-====================
+.. _Debian's Apache layout:
 
-.. sidebar:: public to the internet?
+Debian's Apache layout
+----------------------
 
-   If your SearXNG instance is public, stop here and first install :ref:`filtron
-   reverse proxy <filtron.sh>` and :ref:`result proxy morty <morty.sh>`, see
-   :ref:`installation scripts`.  If already done, follow setup: *SearXNG via
-   filtron plus morty*.
+Be aware, Debian's Apache layout is quite different from the standard Apache
+configuration.  For details look at the apache2.README.Debian_
+(``/usr/share/doc/apache2/README.Debian.gz``).  Some commands you should know on
+Debian:
 
-To setup a Apache revers proxy you have to enable the *headers* and *proxy*
-modules and create a `Location`_ configuration for the SearXNG site.  In most
-distributions you have to un-comment the lines in the main configuration file,
-except in :ref:`The Debian Layout`.
+* :man:`apache2ctl`:  Apache HTTP server control interface
+* :man:`a2enmod`, :man:`a2dismod`: switch on/off modules
+* :man:`a2enconf`, :man:`a2disconf`: switch on/off configurations
+* :man:`a2ensite`, :man:`a2dissite`: switch on/off sites
+
+.. _apache modules:
+
+Apache modules
+--------------
+
+To load additional modules, in most distributions you have to un-comment the
+lines with the corresponding LoadModule_ directive, except in :ref:`Debian's
+Apache layout`.
 
 .. tabs::
 
    .. group-tab:: Ubuntu / debian
 
-      In the Apache setup, enable headers and proxy modules:
+      :ref:`Debian's Apache layout` uses :man:`a2enmod` and :man:`a2dismod` to
+      activate or disable modules:
 
-      .. code:: sh
+      .. code:: bash
 
+         sudo -H a2enmod ssl
          sudo -H a2enmod headers
          sudo -H a2enmod proxy
          sudo -H a2enmod proxy_http
-
-      In :ref:`The Debian Layout` you create a ``searxng.conf`` with the
-      ``<Location /searx >`` directive and save this file in the *sites
-      available* folder at ``/etc/apache2/sites-available``.  To enable the
-      ``searxng.conf`` use :man:`a2ensite`:
-
-      .. code:: sh
-
-         sudo -H a2ensite searxng.conf
+         sudo -H a2enmod proxy_uwsgi
 
    .. group-tab:: Arch Linux
 
-      In the ``/etc/httpd/conf/httpd.conf`` file, activate headers and proxy
-      modules (LoadModule_):
+      In the ``/etc/httpd/conf/httpd.conf`` file, activate LoadModule_
+      directives:
 
       .. code:: apache
 
-	 FIXME needs test
-
-         LoadModule headers_module modules/mod_headers.so
-         LoadModule proxy_module modules/mod_proxy.so
-         LoadModule proxy_http_module modules/mod_proxy_http.so
+         LoadModule ssl_module           modules/mod_ssl.so
+         LoadModule headers_module       modules/mod_headers.so
+         LoadModule proxy_module         modules/mod_proxy.so
+         LoadModule proxy_http_module    modules/mod_proxy_http.so
+         LoadModule proxy_uwsgi_module   modules/mod_proxy_uwsgi.so
 
    .. group-tab::  Fedora / RHEL
 
-      In the ``/etc/httpd/conf/httpd.conf`` file, activate headers and proxy
-      modules (LoadModule_):
+      In the ``/etc/httpd/conf/httpd.conf`` file, activate LoadModule_
+      directives:
 
       .. code:: apache
 
-	 FIXME needs test
+         LoadModule ssl_module           modules/mod_ssl.so
+         LoadModule headers_module       modules/mod_headers.so
+         LoadModule proxy_module         modules/mod_proxy.so
+         LoadModule proxy_http_module    modules/mod_proxy_http.so
+         LoadModule proxy_uwsgi_module   modules/mod_proxy_uwsgi.so
 
-	 LoadModule headers_module modules/mod_headers.so
-         LoadModule proxy_module modules/mod_proxy.so
-         LoadModule proxy_http_module modules/mod_proxy_http.so
 
-With ProxyPreserveHost_ the incoming Host HTTP request header is passed to the
-proxied host.
+.. _apache sites:
 
-.. _apache searxng via filtron plus morty:
-
-.. tabs::
-
-   .. group-tab:: SearXNG via filtron plus morty
-
-      Use this setup, if your instance is public to the internet, compare
-      figure: :ref:`architecture <arch public>` and :ref:`installation scripts`.
-
-      1. Configure a reverse proxy for :ref:`filtron <filtron.sh>`, listening on
-         *localhost 4004* (:ref:`filtron route request`):
-
-      .. code:: apache
-
-         <Location /searx >
-
-             # SetEnvIf Request_URI "/searx" dontlog
-             # CustomLog /dev/null combined env=dontlog
-
-             Require all granted
-
-             Order deny,allow
-             Deny from all
-             #Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
-             Allow from all
-
-             ProxyPreserveHost On
-             ProxyPass http://127.0.0.1:4004
-             RequestHeader set X-Script-Name /searx
-
-         </Location>
-
-      2. Configure reverse proxy for :ref:`morty <searxng morty>`, listening on
-      *localhost 3000*
-
-      .. code:: apache
-
-         ProxyPreserveHost On
-
-         <Location /morty >
-
-             # SetEnvIf Request_URI "/morty" dontlog
-             # CustomLog /dev/null combined env=dontlog
-
-             Require all granted
-
-             Order deny,allow
-             Deny from all
-             #Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
-             Allow from all
-
-             ProxyPass http://127.0.0.1:3000
-             RequestHeader set X-Script-Name /morty
-
-         </Location>
-
-      For a fully result proxification add :ref:`morty's <searxng morty>` **public
-      URL** to your :origin:`searx/settings.yml`:
-
-      .. code:: yaml
-
-         result_proxy:
-             # replace example.org with your server's public name
-             url : https://example.org/morty
-             key : !!binary "insert_your_morty_proxy_key_here"
-
-         server:
-             image_proxy : True
-
-uWSGI support
-=============
-
-Be warned, with this setup, your instance isn't :ref:`protected <searxng
-filtron>`, nevertheless it is good enough for intranet usage.  In modern Linux
-distributions, the `mod_proxy_uwsgi`_ is compiled into the *normal* apache
-package and you need to install only the :ref:`uWSGI <searxng uwsgi>` package:
+Apache sites
+------------
 
 .. tabs::
 
    .. group-tab:: Ubuntu / debian
 
-      .. code:: sh
+      In :ref:`Debian's Apache layout` you create a ``searxng.conf`` with the
+      ``<Location /searxng >`` directive and save this file in the *sites
+      available* folder at ``/etc/apache2/sites-available``.  To enable the
+      ``searxng.conf`` use :man:`a2ensite`:
 
-         sudo -H apt-get install uwsgi
+      .. code:: bash
 
-         # Ubuntu =< 18.04
-         sudo -H apt-get install libapache2-mod-proxy-uwsgi
+         sudo -H a2ensite searxng.conf
 
    .. group-tab:: Arch Linux
 
-      .. code:: sh
-
-         sudo -H pacman -S uwsgi
-
-   .. group-tab::  Fedora / RHEL
-
-      .. code:: sh
-
-         sudo -H dnf install uwsgi
-
-The next example shows a configuration using the `uWSGI Apache support`_ via
-unix sockets and `mod_proxy_uwsgi`_.
-
-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>`.  If not
-already exists, create a folder for the unix sockets, which can be used by the
-SearXNG account (see :ref:`create searxng user`):
-
-.. code:: bash
-
-   sudo -H mkdir -p /run/uwsgi/app/searx/
-   sudo -H chown -R searx:searx /run/uwsgi/app/searx/
-
-If the server is public; to limit access to your intranet replace ``Allow from
-all`` directive and replace ``192.168.0.0/16`` with your subnet IP/class.
-
-.. tabs::
-
-   .. group-tab:: Ubuntu / debian
+      In the ``/etc/httpd/conf/httpd.conf`` file add a IncludeOptional_
+      directive:
 
       .. code:: apache
 
-	 LoadModule headers_module /usr/lib/apache2/mod_headers.so
-	 LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
-	 LoadModule proxy_uwsgi_module /usr/lib/apache2/modules/mod_proxy_uwsgi.so
-
-	 # SetEnvIf Request_URI /searx dontlog
-	 # CustomLog /dev/null combined env=dontlog
+         IncludeOptional sites-enabled/*.conf
 
-	 <Location /searx>
+      Create two folders, one for the *available sites* and one for the *enabled sites*:
 
-	     Require all granted
-	     Order deny,allow
-	     Deny from all
-	     # Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
-	     Allow from all
+      .. code:: bash
 
-	     ProxyPreserveHost On
-	     ProxyPass unix:/run/uwsgi/app/searx/socket|uwsgi://uwsgi-uds-searx/
+         mkdir -p /etc/httpd/sites-available
+         mkdir -p /etc/httpd/sites-enabled
 
-	 </Location>
+      Create configuration at ``/etc/httpd/sites-available`` and place a
+      symlink to ``sites-enabled``:
 
-   .. group-tab:: Arch Linux
-
-      .. code:: apache
+      .. code:: bash
 
-	 FIXME needs test
+         sudo -H ln -s /etc/httpd/sites-available/searxng.conf \
+                       /etc/httpd/sites-enabled/searxng.conf
 
-         LoadModule proxy_module modules/mod_proxy.so
-         LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so
-
-         # SetEnvIf Request_URI /searx dontlog
-         # CustomLog /dev/null combined env=dontlog
+   .. group-tab::  Fedora / RHEL
 
-         <Location /searx>
+      In the ``/etc/httpd/conf/httpd.conf`` file add a IncludeOptional_
+      directive:
 
-             Require all granted
-             Order deny,allow
-             Deny from all
-             # Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
-             Allow from all
+      .. code:: apache
 
-             ProxyPreserveHost On
-             ProxyPass unix:/run/uwsgi/app/searx/socket|uwsgi://uwsgi-uds-searx/
+         IncludeOptional sites-enabled/*.conf
 
-	 </Location>
+      Create two folders, one for the *available sites* and one for the *enabled sites*:
 
-   .. group-tab::  Fedora / RHEL
+      .. code:: bash
 
-      .. code:: apache
+         mkdir -p /etc/httpd/sites-available
+         mkdir -p /etc/httpd/sites-enabled
 
-	 FIXME needs test
+      Create configuration at ``/etc/httpd/sites-available`` and place a
+      symlink to ``sites-enabled``:
 
-	 LoadModule proxy_module modules/mod_proxy.so
-         LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so
-         <IfModule proxy_uwsgi_module>
+      .. code:: bash
 
-             # SetEnvIf Request_URI /searx dontlog
-             # CustomLog /dev/null combined env=dontlog
+         sudo -H ln -s /etc/httpd/sites-available/searxng.conf \
+                       /etc/httpd/sites-enabled/searxng.conf
 
-             <Location /searx>
 
-                 Require all granted
-                 Order deny,allow
-                 Deny from all
-                 # Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
-                 Allow from all
+.. _apache searxng site:
 
-                 ProxyPreserveHost On
-                 ProxyPass unix:/run/uwsgi/app/searx/socket|uwsgi://uwsgi-uds-searx/
+Apache's SearXNG site
+=====================
 
-	     </Location>
+.. _mod_uwsgi: https://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-uwsgi
 
-         </IfModule>
+.. sidebar:: uWSGI
 
-   .. group-tab:: old mod_wsgi
+   Use mod_proxy_uwsgi_ / don't use the old mod_uwsgi_ anymore.
 
-      We show this only for historical reasons, DON'T USE `mod_uwsgi
-      <https://uwsgi-docs.readthedocs.io/en/latest/Apache.html#mod-uwsgi>`_.
-      ANYMORE!
+To proxy the incoming requests to the SearXNG instance Apache needs the
+mod_proxy_ module (:ref:`apache modules`).
 
-      .. code:: apache
+.. sidebar:: HTTP headers
 
-         <IfModule mod_uwsgi.c>
+   With ProxyPreserveHost_ the incoming ``Host`` header is passed to the proxied
+   host.
 
-             # SetEnvIf Request_URI "/searx" dontlog
-             # CustomLog /dev/null combined env=dontlog
+Depending on what your SearXNG installation is listen, you need a http
+mod_proxy_http_) or socket (mod_proxy_uwsgi_) communication to upstream.
 
-             <Location /searx >
+The :ref:`installation scripts` installs by default the :ref:`reference setup
+<use_default_settings.yml>` and a :ref:`uwsgi setup` that listens on a socket.
+You can install and activate your own ``searxng.conf`` like shown in
+:ref:`apache sites`.
 
-                 Require all granted
+.. tabs::
 
-                 Options FollowSymLinks Indexes
-                 SetHandler uwsgi-handler
-                 uWSGISocket /run/uwsgi/app/searx/socket
+   .. group-tab:: socket
 
-                 Order deny,allow
-                 Deny from all
-                 # Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
-                 Allow from all
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START apache socket
+         :end-before: END apache socket
 
-             </Location>
+   .. group-tab:: http
 
-         </IfModule>
+      .. kernel-include:: $DOCS_BUILD/includes/searxng.rst
+         :start-after: START apache http
+         :end-before: END apache http
 
 .. _restart apache:
 
-Restart service
-===============
+Restart service:
 
 .. tabs::
 
    .. group-tab:: Ubuntu / debian
 
-      .. code:: sh
+      .. code:: bash
 
          sudo -H systemctl restart apache2
-         sudo -H service uwsgi restart searx
+         sudo -H service uwsgi restart searxng
 
    .. group-tab:: Arch Linux
 
-      .. code:: sh
+      .. code:: bash
 
          sudo -H systemctl restart httpd
-         sudo -H systemctl restart uwsgi@searx
+         sudo -H systemctl restart uwsgi@searxng
 
    .. group-tab::  Fedora / RHEL
 
-      .. code:: sh
+      .. code:: bash
 
          sudo -H systemctl restart httpd
          sudo -H touch /etc/uwsgi.d/searxng.ini
@@ -489,27 +376,13 @@ disable logs
 ============
 
 For better privacy you can disable Apache logs.  In the examples above activate
-one of the lines and `restart apache`_::
-
+one of the lines and `restart apache`_:
 
-  # SetEnvIf Request_URI "/searx" dontlog
-  # CustomLog /dev/null combined env=dontlog
+.. code:: apache
 
-The ``CustomLog`` directive disable logs for the whole (virtual) server, use it
-when the URL of the service does not have a path component (``/searx``) / is
-located at root (``/``).
+   SetEnvIf Request_URI "/searxng" dontlog
+   # CustomLog /dev/null combined env=dontlog
 
-.. _The Debian Layout:
-
-The Debian Layout
-=================
-
-Be aware that the Debian layout is quite different from the standard Apache
-configuration.  For details look at the README.Debian_
-(``/usr/share/doc/apache2/README.Debian.gz``).  Some commands you should know on
-Debian:
-
-* :man:`apache2ctl`:  Apache HTTP server control interface
-* :man:`a2enmod`, :man:`a2dismod`: switch on/off modules
-* :man:`a2enconf`, :man:`a2disconf`: switch on/off configurations
-* :man:`a2ensite`, :man:`a2dissite`: switch on/off sites
+The ``CustomLog`` directive disable logs of the entire (virtual) server, use it
+when the URL of the service does not have a path component (``/searxng``), when
+SearXNG is located at root (``/``).