From 94ac560dcc85e2e75d3b14706a65eb9488643eb4 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 3 Feb 2020 13:25:51 +0100 Subject: [PATCH] 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 --- docs/admin/filtron.rst | 36 ++++++++++---------------------- docs/admin/morty.rst | 3 +++ docs/index.rst | 1 + docs/utils/filtron.sh.rst | 44 +++++++++++++++++++++++++++++++++++++++ docs/utils/index.rst | 23 ++++++++++++++++++++ docs/utils/morty.sh.rst | 31 +++++++++++++++++++++++++++ docs/utils/searx.sh.rst | 21 +++++++++++++++++++ utils/filtron.sh | 1 + utils/lib.sh | 5 ++++- utils/morty.sh | 1 + utils/searx.sh | 1 + 11 files changed, 141 insertions(+), 26 deletions(-) create mode 100644 docs/utils/filtron.sh.rst create mode 100644 docs/utils/index.rst create mode 100644 docs/utils/morty.sh.rst create mode 100644 docs/utils/searx.sh.rst diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst index e8a2bfb1..332c2720 100644 --- a/docs/admin/filtron.rst +++ b/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] - ` (``/etc/filtron/rules.json``). -#. Setup a systemd service unit :origin:`[ref] - ` - (``/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 diff --git a/docs/admin/morty.rst b/docs/admin/morty.rst index 7d7b3449..9af9b6ae 100644 --- a/docs/admin/morty.rst +++ b/docs/admin/morty.rst @@ -1,3 +1,6 @@ + +.. _searx_morty: + ========================= How to setup result proxy ========================= diff --git a/docs/index.rst b/docs/index.rst index d9503fef..95202f39 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/utils/filtron.sh.rst b/docs/utils/filtron.sh.rst new file mode 100644 index 00000000..d93e3810 --- /dev/null +++ b/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] + ` (``/etc/filtron/rules.json``). +#. Setup a systemd service unit :origin:`[ref] + ` + (``/lib/systemd/system/filtron.service``). + + +Overview +======== + +The ``--help`` output of the script is largely self-explanatory: + +.. program-output:: ../utils/filtron.sh --help + diff --git a/docs/utils/index.rst b/docs/utils/index.rst new file mode 100644 index 00000000..4836ac65 --- /dev/null +++ b/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! + diff --git a/docs/utils/morty.sh.rst b/docs/utils/morty.sh.rst new file mode 100644 index 00000000..64ebda57 --- /dev/null +++ b/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 + diff --git a/docs/utils/searx.sh.rst b/docs/utils/searx.sh.rst new file mode 100644 index 00000000..fb606c0b --- /dev/null +++ b/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 + diff --git a/utils/filtron.sh b/utils/filtron.sh index dd49a3d1..2a68f172 100755 --- a/utils/filtron.sh +++ b/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" diff --git a/utils/lib.sh b/utils/lib.sh index 818477fc..78641cc0 100755 --- a/utils/lib.sh +++ b/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 # ---- diff --git a/utils/morty.sh b/utils/morty.sh index 4f689e2b..be741c2a 100755 --- a/utils/morty.sh +++ b/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:: diff --git a/utils/searx.sh b/utils/searx.sh index 204386fa..ec4eaacc 100755 --- a/utils/searx.sh +++ b/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"