From 9278f0fb45bab21247085a709c0e4bef743752db Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 4 Feb 2020 13:13:17 +0100 Subject: [PATCH] docs: add some documentation about the tooling box ./utils/* Signed-off-by: Markus Heiser --- docs/admin/arch_public.dot | 8 +++--- docs/admin/architecture.rst | 12 +++++---- docs/admin/installation.rst | 6 +++++ docs/dev/makefile.rst | 10 ++++--- docs/utils/filtron.sh.rst | 34 +++++++++++++++++++++++- docs/utils/index.rst | 43 +++++++++++++++++++++++++----- docs/utils/morty.sh.rst | 15 ++++++++--- docs/utils/searx.sh.rst | 53 ++++++++++++++++++++++++++++++++++--- 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 ` + - :ref:`filtron ` + - :ref:`reverse proxy` + - :ref:`morty ` 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 SEARX_URL=https://searx.me export GIT_URL=https://github.com/asciimoo/searx - export SEARX_URL=https://searx.me 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: ` (``/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`. + +.. _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 -