doc: add descriptions of our tooling box in ./utils

Initial started with the scripts for searx, filtron and morty installations.

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

docs/admin/filtron.rst

@@ -1,14 +1,22 @@
+
+.. _searx_filtron:
+
 ==========================
 How to protect an instance
 ==========================
 
+.. sidebar:: further reading
+
+   - :ref:`filtron.sh`
+
 .. _filtron: https://github.com/asciimoo/filtron
 
 Searx depens on external search services.  To avoid the abuse of these services
 it is advised to limit the number of requests processed by searx.
 
 An application firewall, filtron_ solves exactly this problem.  Filtron is just
-a middleware between your web server (nginx, apache, ...) and searx.
+a middleware between your web server (nginx, apache, ...) and searx, we describe
+such infratructures in chapter: :ref:`architecture`.
 
 
 filtron & go
@@ -17,32 +25,10 @@ filtron & go
 .. _Go: https://golang.org/
 .. _filtron README: https://github.com/asciimoo/filtron/blob/master/README.md
 
-
-.. sidebar:: init system
-
-   ATM the ``filtron.sh`` supports only systemd init process used by debian,
-   ubuntu and many other dists.  If you have a working init.d file to start/stop
-   filtron service, please contribute.
-
 Filtron needs Go_ installed.  If Go_ is preinstalled, filtron_ is simply
 installed by ``go get`` package management (see `filtron README`_).  If you use
-filtron as middleware, a more isolated setup is recommended.
-
-#. Create a separated user account (``filtron``).
-#. Download and install Go_ binary in users $HOME (``~filtron``).
-#. Install filtron with the package management of Go_ (``go get -v -u
-   github.com/asciimoo/filtron``)
-#. Setup a proper rule configuration :origin:`[ref]
-   <utils/templates/etc/filtron/rules.json>` (``/etc/filtron/rules.json``).
-#. Setup a systemd service unit :origin:`[ref]
-   <utils/templates/lib/systemd/system/filtron.service>`
-   (``/lib/systemd/system/filtron.service``).
-
-To simplify such a installation and the maintenance of; use our script
-``utils/filtron.sh``:
-
-.. program-output:: ../utils/filtron.sh --help
-   :ellipsis: 0,5
+filtron as middleware, a more isolated setup is recommended.  To simplify such
+an installation and the maintenance of, use our script :ref:`filtron.sh`.
 
 
 Sample configuration of filtron

docs/admin/morty.rst

@@ -1,3 +1,6 @@
+
+.. _searx_morty:
+
 =========================
 How to setup result proxy
 =========================

docs/index.rst

@@ -29,4 +29,5 @@ don't trust anyone, you can set up your own, see :ref:`installation`.
    user/index
    admin/index
    dev/index
+   utils/index
    blog/index

docs/utils/filtron.sh.rst

@@ -0,0 +1,44 @@
+
+.. _filtron.sh:
+
+====================
+``utils/filtron.sh``
+====================
+
+.. sidebar:: further reading
+
+   - :ref:`searx_filtron`
+
+.. _Go: https://golang.org/
+.. _filtron: https://github.com/asciimoo/filtron
+.. _filtron README: https://github.com/asciimoo/filtron/blob/master/README.md
+
+To simplify installation and maintenance of a filtron instance you can use the
+script :origin:`utils/filtron.sh`.  In most cases you will install filtron_
+simply by running the command:
+
+.. code::  bash
+
+   sudo -H ./utils/filtron.sh install all
+
+The script adds a ``${SERVICE_USER}`` (default:``filtron``) and installs filtron_
+into this user account:
+
+#. Create a separated user account (``filtron``).
+#. Download and install Go_ binary in users $HOME (``~filtron``).
+#. Install filtron with the package management of Go_ (``go get -v -u
+   github.com/asciimoo/filtron``)
+#. Setup a proper rule configuration :origin:`[ref]
+   <utils/templates/etc/filtron/rules.json>` (``/etc/filtron/rules.json``).
+#. Setup a systemd service unit :origin:`[ref]
+   <utils/templates/lib/systemd/system/filtron.service>`
+   (``/lib/systemd/system/filtron.service``).
+
+
+Overview
+========
+
+The ``--help`` output of the script is largely self-explanatory:
+
+.. program-output:: ../utils/filtron.sh --help
+

docs/utils/index.rst

@@ -0,0 +1,23 @@
+
+.. _searx_utils:
+
+======================
+Tooling box ``utils/``
+======================
+
+In the folder :origin:`utils/` we maintain some tools useful for admins and
+developers.
+
+.. toctree::
+   :maxdepth: 1
+
+   searx.sh
+   filtron.sh
+   morty.sh
+
+.. hint::
+
+   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!
+

docs/utils/morty.sh.rst

@@ -0,0 +1,31 @@
+
+.. _morty.sh:
+
+.. _morty: https://github.com/asciimoo/morty
+.. _morty's README: https://github.com/asciimoo/morty
+
+==================
+``utils/morty.sh``
+==================
+
+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:
+
+.. code::  bash
+
+   sudo -H ./utils/morty.sh install all
+
+The script adds a ``${SERVICE_USER}`` (default:``morty``) and installs morty_
+into this user account.
+
+.. hint::
+
+   To add morty to your searx instance read chapter :reF:`searx_morty`.
+
+
+The ``--help`` output of the script is largely
+self-explanatory:
+
+.. program-output:: ../utils/morty.sh --help
+

docs/utils/searx.sh.rst

@@ -0,0 +1,21 @@
+
+.. _searx.sh:
+
+==================
+``utils/searx.sh``
+==================
+
+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:
+
+.. code::  bash
+
+   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:
+
+.. program-output:: ../utils/searx.sh --help
+

utils/filtron.sh

@@ -89,6 +89,7 @@ If needed, set PUBLIC_URL of your WEB service in the '${DOT_CONFIG#"$REPO_ROOT/"
 
   PUBLIC_URL   : ${PUBLIC_URL}
   PUBLIC_HOST  : ${PUBLIC_HOST}
+  SERVICE_USER : ${SERVICE_USER}
 
 EOF
     [ ! -z ${1+x} ] &&  echo -e "$1"

utils/lib.sh

@@ -97,7 +97,10 @@ set_terminal_colors() {
     _BPurple='\e[1;35m'
     _BCyan='\e[1;36m'
 }
-set_terminal_colors
+
+if [ ! -p /dev/stdout ]; then
+    set_terminal_colors
+fi
 
 # reST
 # ----

utils/morty.sh

@@ -77,6 +77,7 @@ If needed, set the environment variable MORTY_LISTEN in the
 ${DOT_CONFIG#"$REPO_ROOT/"} file::
 
   MORTY_LISTEN :   ${MORTY_LISTEN}
+  SERVICE_USER : ${SERVICE_USER}
 
 To activate morty in searx, add result_proxy to your settings.yml::
 

utils/searx.sh

@@ -104,6 +104,7 @@ If needed, set PUBLIC_URL of your WEB service in the '${DOT_CONFIG#"$REPO_ROOT/"
   PUBLIC_URL          : ${PUBLIC_URL}
   PUBLIC_HOST         : ${PUBLIC_HOST}
   SEARX_INSTANCE_NAME : ${SEARX_INSTANCE_NAME}
+  SERVICE_USER        : ${SERVICE_USER}
 
 EOF
     [ ! -z ${1+x} ] &&  echo -e "$1"