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>
This commit is contained in:
Markus Heiser 2020-02-03 13:25:51 +01:00
parent e7401796f6
commit 94ac560dcc
11 changed files with 141 additions and 26 deletions

View file

@ -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

View file

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

View file

@ -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

44
docs/utils/filtron.sh.rst Normal file
View file

@ -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

23
docs/utils/index.rst Normal file
View file

@ -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!

31
docs/utils/morty.sh.rst Normal file
View file

@ -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

21
docs/utils/searx.sh.rst Normal file
View file

@ -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

View file

@ -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"

View file

@ -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
# ----

View file

@ -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::

View file

@ -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"