docs: add some documentation about the tooling box ./utils/*

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

8 files changed, 153 insertions, 28 deletions

diff --git a/docs/admin/arch_public.dot b/docs/admin/arch_public.dot
index a46c96de3..5018225c3 100644
--- a/docs/admin/arch_public.dot
+++ b/docs/admin/arch_public.dot
@@ -4,11 +4,11 @@ digraph G {
   edge [fontname="Sans"];
 
   browser [label="Browser", shape=Mdiamond];
-  rp      [label="Reverse Proxy", href="url to configure reverse proxy"];
-  filtron [label="Filtron",       href="https://github.com/asciimoo/filtron"];
-  morty   [label="Morty",         href="https://github.com/asciimoo/morty"];
+  rp      [label="Reverse Proxy", href="https://asciimoo.github.io/searx/utils/filtron.sh.html#public-reverse-proxy"];
+  filtron [label="Filtron",       href="https://asciimoo.github.io/searx/utils/filtron.sh.html"];
+  morty   [label="Morty",         href="https://asciimoo.github.io/searx/utils/morty.sh.html"];
   static  [label="Static files",  href="url to configure static files"];
-  uwsgi   [label="uwsgi",         href="url to configure uwsgi"]
+  uwsgi   [label="uwsgi",         href="https://asciimoo.github.io/searx/utils/searx.sh.html"]
   searx1  [label="Searx #1"];
   searx2  [label="Searx #2"];
   searx3  [label="Searx #3"];
diff --git a/docs/admin/architecture.rst b/docs/admin/architecture.rst
index 7064a294b..fbc3bf483 100644
--- a/docs/admin/architecture.rst
+++ b/docs/admin/architecture.rst
@@ -4,17 +4,19 @@
 Architecture
 ============
 
-.. sidebar:: Needs work!
+.. sidebar:: Tooling box
 
-   This article needs some work / Searx is a collaborative effort.  If you have
-   any contribution, feel welcome to send us your :pull:`PR <../pulls>`, see
-   :ref:`how to contribute`.
+   - :ref:`searx & uwsgi <searx.sh>`
+   - :ref:`filtron <filtron.sh>`
+   - :ref:`reverse proxy`
+   - :ref:`morty <morty.sh>`
 
 Herein you will find some hints and suggestions about typical architectures of
 searx infrastructures.
 
 We start with a contribution from :pull:`@dalf <1776#issuecomment-567917320>`.
-It shows a *reference* setup for public searx instances.
+It shows a *reference* setup for public searx instances which can build up and
+maintained by the scripts from our :ref:`toolboxing`.
 
 .. _arch public:
 
diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst
index 15800fc01..bff3e44d9 100644
--- a/docs/admin/installation.rst
+++ b/docs/admin/installation.rst
@@ -7,9 +7,15 @@ Installation
 .. contents::
    :depth: 3
 
+.. _installation basic:
+
 Basic installation
 ==================
 
+.. sidebar:: further reading
+
+   - :ref:`searx.sh`
+
 Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure
 to have enable universe repository.
 
diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst
index 8e54aef48..ed9942f4c 100644
--- a/docs/dev/makefile.rst
+++ b/docs/dev/makefile.rst
@@ -39,15 +39,17 @@ Calling the ``help`` target gives a first overview::
 
 .. _makefile setup:
 
-Setup
-=====
+Makefile setup
+==============
 
 .. _git stash: https://git-scm.com/docs/git-stash
 
-The main setup is done in the :origin:`Makefile`::
+The main setup is done in the :origin:`.config.sh` (read :ref:`toolboxing
+setup`)::
 
-  export GIT_URL=https://github.com/asciimoo/searx
   export SEARX_URL=https://searx.me
+
+  export GIT_URL=https://github.com/asciimoo/searx
   export DOCS_URL=https://asciimoo.github.io/searx
 
 .. sidebar:: fork & upstream
diff --git a/docs/utils/filtron.sh.rst b/docs/utils/filtron.sh.rst
index d93e38105..356359753 100644
--- a/docs/utils/filtron.sh.rst
+++ b/docs/utils/filtron.sh.rst
@@ -8,6 +8,7 @@
 .. sidebar:: further reading
 
    - :ref:`searx_filtron`
+   - :ref:`architecture`
 
 .. _Go: https://golang.org/
 .. _filtron: https://github.com/asciimoo/filtron
@@ -34,11 +35,42 @@ into this user account:
    <utils/templates/lib/systemd/system/filtron.service>`
    (``/lib/systemd/system/filtron.service``).
 
+.. _reverse proxy:
+
+Public Reverse Proxy
+====================
+
+.. tabs::
+
+To install searx in your public HTTP server use:
+
+.. code::  bash
+
+   sudo -H ./utils/filtron.sh apache install
+
+.. tabs::
+
+   .. group-tab:: apache
+
+      .. literalinclude:: ../../utils/templates/etc/apache2/sites-available/searx.conf:filtron
+	 :language: apache
+
+      .. tabs::
+
+	 .. group-tab:: Ubuntu / debian
+
+	       .. code-block:: sh
+
+		  $ sudo -H a2enmod headers
+		  $ sudo -H a2enmod proxy
+		  $ sudo -H a2enmod proxy_http
+
 
 Overview
 ========
 
-The ``--help`` output of the script is largely self-explanatory:
+The ``--help`` output of the script is largely self-explanatory
+(:ref:`toolboxing common`):
 
 .. program-output:: ../utils/filtron.sh --help
 
diff --git a/docs/utils/index.rst b/docs/utils/index.rst
index 4836ac652..9905d755f 100644
--- a/docs/utils/index.rst
+++ b/docs/utils/index.rst
@@ -1,9 +1,10 @@
 
 .. _searx_utils:
+.. _toolboxing:
 
-======================
-Tooling box ``utils/``
-======================
+=======================
+Tooling box ``utils/*``
+=======================
 
 In the folder :origin:`utils/` we maintain some tools useful for admins and
 developers.
@@ -15,9 +16,37 @@ developers.
    filtron.sh
    morty.sh
 
-.. hint::
+.. admonition:: Work needed!
 
-   ATM :ref:`filtron.sh` and :ref:`searx.sh` do supports only systemd init
-   process used by debian, ubuntu and many other dists.  If you have working
-   init.d files to start/stop services, please contribute / thanks!
+   Our scripts to maintain services do most support only systemd init process
+   used by debian, ubuntu and many other dists.  In general our scripts are only
+   partially usable on debian systems.  We are working on this limitation, if
+   you have any contribution, please send us your :pull:`PR <../pulls>`, see
+   :ref:`how to contribute`.
 
+.. _toolboxing common:
+
+Common commands
+===============
+
+Scripts to maintain services often dispose of common commands and environments.
+
+``shell``:
+  Opens a shell from the service user ``${SERVICE_USSR}``, very helpful for
+  troubleshooting.
+
+``inspect service``:
+  Shows status and log of the service, most often you have a option to enable
+  more verbose debug logs.  Very helpful for debugging, but be careful not to
+  enable debugging in a production environment!
+
+.. _toolboxing setup:
+
+Tooling box setup
+=================
+
+The main setup is done in the :origin:`.config.sh` (read also :ref:`makefile
+setup`).
+
+.. literalinclude:: ../../.config.sh
+   :language: bash
diff --git a/docs/utils/morty.sh.rst b/docs/utils/morty.sh.rst
index 64ebda574..988b16935 100644
--- a/docs/utils/morty.sh.rst
+++ b/docs/utils/morty.sh.rst
@@ -1,13 +1,17 @@
 
-.. _morty.sh:
-
 .. _morty: https://github.com/asciimoo/morty
 .. _morty's README: https://github.com/asciimoo/morty
 
+.. _morty.sh:
+
 ==================
 ``utils/morty.sh``
 ==================
 
+.. sidebar:: further reading
+
+   - :ref:`architecture`
+
 To simplify installation and maintenance of a morty_ instance you can use the
 script :origin:`utils/morty.sh`.  In most cases you will install morty_ simply by
 running the command:
@@ -24,8 +28,11 @@ into this user account.
    To add morty to your searx instance read chapter :reF:`searx_morty`.
 
 
-The ``--help`` output of the script is largely
-self-explanatory:
+Overview
+========
+
+The ``--help`` output of the script is largely self-explanatory
+(:ref:`toolboxing common`):
 
 .. program-output:: ../utils/morty.sh --help
 
diff --git a/docs/utils/searx.sh.rst b/docs/utils/searx.sh.rst
index fb606c0b0..1e3f954bb 100644
--- a/docs/utils/searx.sh.rst
+++ b/docs/utils/searx.sh.rst
@@ -5,6 +5,11 @@
 ``utils/searx.sh``
 ==================
 
+.. sidebar:: further reading
+
+   - :ref:`installation`
+   - :ref:`architecture`
+
 To simplify installation and maintenance of a searx instance you can use the
 script :origin:`utils/searx.sh`.  In most cases you will install searx simply by
 running the command:
@@ -14,8 +19,50 @@ running the command:
    sudo -H ./utils/searx.sh install all
 
 The script adds a ``${SERVICE_USER}`` (default:``searx``) and installs searx
-into this user account.  The ``--help`` output of the script is largely
-self-explanatory:
+into this user account.  The installation is described in chapter
+:ref:`installation basic`.
 
-.. program-output:: ../utils/searx.sh --help
+.. _intranet reverse proxy:
+
+Intranet Reverse Proxy
+======================
+
+.. warning::
+
+   This setup is **not** suitable **for public instances**, go on with
+   :ref:`reverse proxy`!
+
+To install searx in your intranet HTTP server use:
+
+.. code::  bash
+
+   sudo -H ./utils/searx.sh apache install
+
+.. tabs::
+
+   .. group-tab:: apache
 
+      .. literalinclude:: ../../utils/templates/etc/apache2/sites-available/searx.conf:uwsgi
+	 :language: apache
+
+      .. tabs::
+
+	 .. group-tab:: Ubuntu / debian
+
+	       .. code-block:: sh
+
+		  $ sudo -H apt install libapache2-mod-uwsgi
+
+	 .. group-tab:: Arch Linux
+
+	    .. code-block:: sh
+
+	       $ sudo pacman -S uwsgi
+
+Overview
+========
+
+The ``--help`` output of the script is largely self-explanatory
+(:ref:`toolboxing common`):
+
+.. program-output:: ../utils/searx.sh --help