docs: revision of the installation instructions

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

7 files changed, 361 insertions, 225 deletions

diff --git a/docs/admin/buildhosts.rst b/docs/admin/buildhosts.rst
index c1582cef2..27784764f 100644
--- a/docs/admin/buildhosts.rst
+++ b/docs/admin/buildhosts.rst
@@ -4,13 +4,18 @@
 Buildhosts
 ==========
 
+To get best results from build, its recommend to install additional packages
+on build hosts.
+
 .. sidebar:: This article needs some work
 
    If you have any contribution send us your :pull:`PR <../pulls>`, see
    :ref:`how to contribute`.
 
-To get best results from build, its recommend to install additional packages
-on build hosts.
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
 
 .. _docs build:
 
diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst
index 332c27203..205269973 100644
--- a/docs/admin/filtron.rst
+++ b/docs/admin/filtron.rst
@@ -9,6 +9,11 @@ How to protect an instance
 
    - :ref:`filtron.sh`
 
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
 .. _filtron: https://github.com/asciimoo/filtron
 
 Searx depens on external search services.  To avoid the abuse of these services
diff --git a/docs/admin/index.rst b/docs/admin/index.rst
index b3c7f5119..4190bf24b 100644
--- a/docs/admin/index.rst
+++ b/docs/admin/index.rst
@@ -3,9 +3,12 @@ Administrator documentation
 ===========================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
+   :caption: Contents
 
    installation
+   installation-nginx
+   installation-apache
    settings
    api
    architecture
diff --git a/docs/admin/installation-apache.rst b/docs/admin/installation-apache.rst
new file mode 100644
index 000000000..7f92e47d5
--- /dev/null
+++ b/docs/admin/installation-apache.rst
@@ -0,0 +1,94 @@
+.. _installation apache:
+
+===================
+Install with apache
+===================
+
+.. sidebar:: public HTTP servers
+
+   On public searx instances use an application firewall (:ref:`filtron
+   <filtron.sh>`).
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+Add wsgi mod
+============
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         sudo -H apt-get install libapache2-mod-uwsgi
+         sudo -H a2enmod uwsgi
+
+Add this configuration in the file ``/etc/apache2/apache2.conf``.  To limit
+acces to your intranet replace ``Allow from all`` directive and replace
+``192.168.0.0/16`` with your subnet IP/class.
+
+.. _inranet apache site:
+
+Note that if your instance of searx is not at the root, you should change
+``<Location />`` by the location of your instance, like ``<Location /searx>``:
+
+.. code:: apache
+
+   # CustomLog /dev/null combined
+
+   <IfModule mod_uwsgi.c>
+
+     <Location />
+
+          Options FollowSymLinks Indexes
+          SetHandler uwsgi-handler
+          uWSGISocket /run/uwsgi/app/searx/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
+
+     </Location>
+
+   </IfModule>
+
+Enable apache mod_uwsgi and restart apache:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         a2enmod uwsgi
+         sudo -H systemctl restart apache2
+
+disable logs
+============
+
+For better privacy you can disable Apache logs.  Go back to
+``/etc/apache2/apache2.conf`` :ref:`[example] <inranet apache site>` and above
+``<Location />`` activate directive:
+
+.. code:: apache
+
+    CustomLog /dev/null combined
+
+Restart apache:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         sudo -H systemctl restart apache2
+
+.. warning::
+
+   You can only disable logs for the whole (virtual) server not for a specific
+   path.
diff --git a/docs/admin/installation-nginx.rst b/docs/admin/installation-nginx.rst
new file mode 100644
index 000000000..37d3e7532
--- /dev/null
+++ b/docs/admin/installation-nginx.rst
@@ -0,0 +1,141 @@
+.. _installation nginx:
+
+==================
+Install with nginx
+==================
+
+.. sidebar:: public HTTP servers
+
+   On public searx instances use an application firewall (:ref:`filtron
+   <filtron.sh>`).
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+If nginx is not installed (uwsgi will not work with the package
+nginx-light):
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         sudo -H apt-get install nginx
+
+Hosted at ``/``
+===============
+
+Create the configuration file ``/etc/nginx/sites-available/searx`` with this
+content:
+
+.. code:: nginx
+
+    server {
+        listen 80;
+        server_name searx.example.com;
+        root /usr/local/searx/searx;
+
+        location /static {
+        }
+
+        location / {
+                include uwsgi_params;
+                uwsgi_pass unix:/run/uwsgi/app/searx/socket;
+        }
+    }
+
+Create a symlink to sites-enabled:
+
+.. code:: sh
+
+   sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx
+
+Restart service:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         sudo -H systemctl restart nginx
+         sudo -H systemctl restart uwsgi
+
+from subdirectory URL (``/searx``)
+==================================
+
+Add this configuration in the server config file
+``/etc/nginx/sites-enabled/default``:
+
+.. code:: nginx
+
+    location /searx/static {
+            alias /usr/local/searx/searx/static;
+    }
+
+    location /searx {
+            uwsgi_param SCRIPT_NAME /searx;
+            include uwsgi_params;
+            uwsgi_pass unix:/run/uwsgi/app/searx/socket;
+    }
+
+
+**OR** using reverse proxy (Please, note that reverse proxy advised to be used
+in case of single-user or low-traffic instances.)
+
+.. code:: nginx
+
+    location /searx/static {
+            alias /usr/local/searx/searx/static;
+    }
+
+    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;
+    }
+
+Enable ``base_url`` in ``searx/settings.yml``
+
+.. code:: yaml
+
+    base_url : http://your.domain.tld/searx/
+
+Restart service:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         sudo -H systemctl restart nginx
+         sudo -H systemctl restart uwsgi
+
+
+disable logs
+============
+
+For better privacy you can disable nginx logs about searx.  How to proceed:
+below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default`` add:
+
+.. code:: nginx
+
+    access_log /dev/null;
+    error_log /dev/null;
+
+Restart service:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
+
+         sudo -H systemctl restart nginx
diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst
index bff3e44d9..a901fee1c 100644
--- a/docs/admin/installation.rst
+++ b/docs/admin/installation.rst
@@ -4,50 +4,64 @@
 Installation
 ============
 
-.. contents::
-   :depth: 3
+.. sidebar:: Searx server setup
+
+   - :ref:`installation nginx`
+   - :ref:`installation apache`
+
+   If you do not have any special preferences, it is recommend to use
+   :ref:`searx.sh`.
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
 
 .. _installation basic:
 
 Basic installation
 ==================
 
-.. sidebar:: further reading
+Step by step installation with virtualenv.  For Ubuntu, be sure to have enable
+universe repository.
 
-   - :ref:`searx.sh`
+Install packages:
 
-Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure
-to have enable universe repository.
+.. tabs::
 
-Install packages:
+   .. group-tab:: Ubuntu / debian
 
-.. code:: sh
+      .. code-block:: sh
 
-    $ sudo -H apt-get install \
-           git build-essential libxslt-dev \
-	   python-dev python-virtualenv python-babel \
-	   zlib1g-dev libffi-dev libssl-dev
+         $ sudo -H apt-get install \
+                   git build-essential
+                   libxslt-dev python3-dev python3-babel \
+                   zlib1g-dev libffi-dev libssl-dev
 
 Install searx:
 
 .. code:: sh
 
-    cd /usr/local
-    sudo -H git clone https://github.com/asciimoo/searx.git
-    sudo -H useradd searx -d /usr/local/searx
+    sudo -H useradd searx --system --disabled-password -d /usr/local/searx
+    sudo -H usermod -a -G shadow $SERVICE_USER
+    cd /usr/local/searx
+    sudo -H git clone https://github.com/asciimoo/searx.git searx-src
     sudo -H chown searx:searx -R /usr/local/searx
 
-Install dependencies in a virtualenv:
+Install virtualenv:
 
 .. code:: sh
 
-    cd /usr/local/searx
     sudo -H -u searx -i
+    (searx)$ python3 -m venv searx-pyenv
+    (searx)$ echo 'source ~/searx-pyenv/bin/activate' > ~/.profile
+
+Exit the searx bash and restart a new to install the searx dependencies:
 
 .. code:: sh
 
-    (searx)$ virtualenv searx-ve
-    (searx)$ . ./searx-ve/bin/activate
+    sudo -H -u searx -i
+    (searx)$ cd searx-src
     (searx)$ ./manage.sh update_packages
 
 Configuration
@@ -55,7 +69,9 @@ Configuration
 
 .. code:: sh
 
-    sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml
+    sudo -H -u searx -i
+    (searx)$ cd searx-src
+    (searx)$ sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml
 
 Edit searx/settings.yml if necessary.
 
@@ -66,7 +82,9 @@ Start searx:
 
 .. code:: sh
 
-    python searx/webapp.py
+    sudo -H -u searx -i
+    (searx)$ cd searx-src
+    (searx)$ python3 searx/webapp.py
 
 Go to http://localhost:8888
 
@@ -76,254 +94,118 @@ If everything works fine, disable the debug option in settings.yml:
 
     sed -i -e "s/debug : True/debug : False/g" searx/settings.yml
 
-At this point searx is not demonized ; uwsgi allows this.
-
-You can exit the virtualenv and the searx user bash (enter exit command
-twice).
+At this point searx is not demonized ; uwsgi allows this.  You can exit the
+virtualenv and the searx user bash (enter exit command twice).
 
 uwsgi
 =====
 
 Install packages:
 
-.. code:: sh
-
-    sudo -H apt-get install \
-         uwsgi uwsgi-plugin-python
-
-Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this
-content:
-
-.. code:: ini
-
-    [uwsgi]
-    # Who will run the code
-    uid = searx
-    gid = searx
-
-    # disable logging for privacy
-    disable-logging = true
-
-    # Number of workers (usually CPU count)
-    workers = 4
-
-    # The right granted on the created socket
-    chmod-socket = 666
+.. tabs::
 
-    # Plugin to use and interpretor config
-    single-interpreter = true
-    master = true
-    plugin = python
-    lazy-apps = true
-    enable-threads = true
+   .. group-tab:: Ubuntu / debian
 
-    # Module to import
-    module = searx.webapp
+      .. code-block:: bash
 
-    # Support running the module from a webserver subdirectory.
-    route-run = fixpathinfo:
+         sudo -H apt-get install uwsgi uwsgi-plugin-python3
 
-    # Virtualenv and python path
-    virtualenv = /usr/local/searx/searx-ve/
-    pythonpath = /usr/local/searx/
-    chdir = /usr/local/searx/searx/
-
-Activate the uwsgi application and restart:
-
-.. code:: sh
-
-    cd /etc/uwsgi/apps-enabled
-    ln -s ../apps-available/searx.ini
-    /etc/init.d/uwsgi restart
-
-Web server
-==========
-
-with nginx
-----------
-
-If nginx is not installed (uwsgi will not work with the package
-nginx-light):
-
-.. code:: sh
-
-    sudo -H apt-get install nginx
-
-Hosted at /
-~~~~~~~~~~~
-
-Create the configuration file ``/etc/nginx/sites-available/searx`` with this
+Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this
 content:
 
-.. code:: nginx
-
-    server {
-        listen 80;
-        server_name searx.example.com;
-        root /usr/local/searx/searx;
-
-        location /static {
-        }
-
-        location / {
-                include uwsgi_params;
-                uwsgi_pass unix:/run/uwsgi/app/searx/socket;
-        }
-    }
-
-Create a symlink to sites-enabled:
-
-.. code:: sh
-
-   sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx
-
-Restart service:
-
-.. code:: sh
-
-    sudo -H service nginx restart
-    sudo -H service uwsgi restart
-
-from subdirectory URL (/searx)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Add this configuration in the server config file
-``/etc/nginx/sites-enabled/default``:
-
-.. code:: nginx
-
-    location /searx/static {
-            alias /usr/local/searx/searx/static;
-    }
-
-    location /searx {
-            uwsgi_param SCRIPT_NAME /searx;
-            include uwsgi_params;
-            uwsgi_pass unix:/run/uwsgi/app/searx/socket;
-    }
-
-
-**OR** using reverse proxy (Please, note that reverse proxy advised to be used
-in case of single-user or low-traffic instances.)
-
-.. code:: nginx
-
-    location /searx/static {
-            alias /usr/local/searx/searx/static;
-    }
-
-    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;
-    }
-
-
-Enable ``base_url`` in ``searx/settings.yml``
-
-.. code:: yaml
-
-    base_url : http://your.domain.tld/searx/
+.. code:: ini
 
-Restart service:
+   [uwsgi]
 
-.. code:: sh
+   # uWSGI core
+   # ----------
+   #
+   # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#uwsgi-core
 
-    sudo -H service nginx restart
-    sudo -H service uwsgi restart
+   # Who will run the code
+   uid = searx
+   gid = searx
 
-disable logs
-^^^^^^^^^^^^
+   # chdir to specified directory before apps loading
+   chdir = /usr/local/searx/searx-src/searx
 
-for better privacy you can disable nginx logs about searx.
+   # disable logging for privacy
+   disable-logging = true
 
-how to proceed: below ``uwsgi_pass`` in ``/etc/nginx/sites-available/default``
-add:
+   # The right granted on the created socket
+   chmod-socket = 666
 
-.. code:: nginx
+   # Plugin to use and interpretor config
+   single-interpreter = true
 
-    access_log /dev/null;
-    error_log /dev/null;
+   # enable master process
+   master = true
 
-Restart service:
+   # load apps in each worker instead of the master
+   lazy-apps = true
 
-.. code:: sh
+   # load uWSGI plugins
+   plugin = python3,http
 
-    sudo -H service nginx restart
+   # By default the Python plugin does not initialize the GIL.  This means your
+   # app-generated threads will not run.  If you need threads, remember to enable
+   # them with enable-threads.  Running uWSGI in multithreading mode (with the
+   # threads options) will automatically enable threading support. This *strange*
+   # default behaviour is for performance reasons.
+   enable-threads = true
 
-with apache
------------
+   # plugin: python
+   # --------------
+   #
+   # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-python
 
-Add wsgi mod:
+   # load a WSGI module
+   module = searx.webapp
 
-.. code:: sh
+   # set PYTHONHOME/virtualenv
+   virtualenv = /usr/local/searx/searx-pyenv
 
-    sudo -H apt-get install libapache2-mod-uwsgi
-    sudo -H a2enmod uwsgi
+   # add directory (or glob) to pythonpath
+   pythonpath = /usr/local/searx/searx-src
 
-Add this configuration in the file ``/etc/apache2/apache2.conf``:
 
-.. code:: apache
+   # plugin http
+   # -----------
+   #
+   # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http
 
-    <Location />
-        Options FollowSymLinks Indexes
-        SetHandler uwsgi-handler
-        uWSGISocket /run/uwsgi/app/searx/socket
-    </Location>
+   # Native HTTP support: https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html
+   http = 127.0.0.1:8888
 
-Note that if your instance of searx is not at the root, you should change
-``<Location />`` by the location of your instance, like ``<Location /searx>``.
-
-Restart Apache:
+Activate the uwsgi application and restart:
 
 .. code:: sh
 
-    sudo -H /etc/init.d/apache2 restart
-
-disable logs
-~~~~~~~~~~~~
-
-For better privacy you can disable Apache logs.
-
-.. warning::
-
-   You can only disable logs for the whole (virtual) server not for a specific
-   path.
-
-Go back to ``/etc/apache2/apache2.conf`` and above ``<Location />`` add:
-
-.. code:: apache
-
-    CustomLog /dev/null combined
-
-Restart Apache:
-
-.. code:: sh
+    cd /etc/uwsgi/apps-enabled
+    ln -s ../apps-available/searx.ini
+    /etc/init.d/uwsgi restart
 
-    sudo -H /etc/init.d/apache2 restart
 
 How to update
 =============
 
 .. code:: sh
 
-    cd /usr/local/searx
     sudo -H -u searx -i
-
-.. code:: sh
-
-    (searx)$ . ./searx-ve/bin/activate
     (searx)$ git stash
     (searx)$ git pull origin master
     (searx)$ git stash apply
     (searx)$ ./manage.sh update_packages
 
-.. code:: sh
+Restart uwsgi:
+
+.. tabs::
+
+   .. group-tab:: Ubuntu / debian
+
+      .. code:: sh
 
-    sudo -H service uwsgi restart
+         sudo -H systemctl restart uwsgi
 
 Docker
 ======
diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst
index 0bfdcc6cb..59a406a28 100644
--- a/docs/admin/settings.rst
+++ b/docs/admin/settings.rst
@@ -4,11 +4,17 @@
 ``settings.yml``
 ================
 
+This page describe the options possibilities of the :origin:`searx/settings.yml`
+file.
+
 .. sidebar:: Further reading ..
 
    - :ref:`search API`
 
-This page describe the options possibilities of the settings.yml file.
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
 
 .. _settings global: