4 files changed, 240 insertions, 0 deletions
diff --git a/docs/utils/filtron.sh.rst b/docs/utils/filtron.sh.rst
new file mode 100644
index 000000000..1bba1b3e4
--- /dev/null
+++ b/docs/utils/filtron.sh.rst
@@ -0,0 +1,75 @@
+
+.. _filtron.sh:
+
+====================
+``utils/filtron.sh``
+====================
+
+.. sidebar:: further reading
+
+   - :ref:`installation`
+   - :ref:`searx_filtron`
+   - :ref:`architecture`
+
+.. _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``).
+
+.. _reverse proxy:
+
+Public Reverse Proxy
+====================
+
+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
+(:ref:`toolboxing common`):
+
+.. program-output:: ../utils/filtron.sh --help
+
diff --git a/docs/utils/index.rst b/docs/utils/index.rst
new file mode 100644
index 000000000..338914715
--- /dev/null
+++ b/docs/utils/index.rst
@@ -0,0 +1,53 @@
+
+.. _searx_utils:
+.. _toolboxing:
+
+=======================
+Tooling box ``utils/*``
+=======================
+
+In the folder :origin:`utils/` we maintain some tools useful for admins and
+developers.
+
+.. sidebar:: Work needed!
+
+   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`.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   searx.sh
+   filtron.sh
+   morty.sh
+
+.. _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
new file mode 100644
index 000000000..9997ffec5
--- /dev/null
+++ b/docs/utils/morty.sh.rst
@@ -0,0 +1,39 @@
+
+.. _morty: https://github.com/asciimoo/morty
+.. _morty's README: https://github.com/asciimoo/morty
+
+.. _morty.sh:
+
+==================
+``utils/morty.sh``
+==================
+
+.. sidebar:: further reading
+
+   - :ref:`installation`
+   - :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:
+
+.. 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`.
+
+
+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
new file mode 100644
index 000000000..988c08438
--- /dev/null
+++ b/docs/utils/searx.sh.rst
@@ -0,0 +1,73 @@
+
+.. _searx.sh:
+
+==================
+``utils/searx.sh``
+==================
+
+.. sidebar:: further reading
+
+   - :ref:`installation`
+   - :ref:`architecture`
+   - :ref:`filtron.sh`
+
+To simplify installation and maintenance of a searx instance you can use the
+script :origin:`utils/searx.sh`.
+
+Install
+=======
+
+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 installation is described in chapter
+:ref:`installation basic`.
+
+.. _intranet reverse proxy:
+
+Intranet Reverse Proxy
+======================
+
+To install searx in your intranet HTTP server use:
+
+.. code::  bash
+
+   sudo -H ./utils/searx.sh apache install
+
+.. warning::
+
+   This setup is **not** suitable **for public instances**, go on with
+   :ref:`reverse proxy`!
+
+.. 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