git.iko.soy/searx
on master help sign in
docs: add some documentation about the tooling box ./utils/*

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

commit9278f0fb45bab21247085a709c0e4bef743752db authorMarkus Heiser <markus.heiser@darmarit.de> dateTue 4 Feb 2020, 13:13 (7 years ago) parent8ca86f4
8 files changed+153−28
compare with master
unifiedsplit
docs/admin/arch_public.dot+4−4 docs/admin/architecture.rst+7−5 docs/admin/installation.rst+6 docs/dev/makefile.rst+6−4 docs/utils/filtron.sh.rst+33−1 docs/utils/index.rst+36−7 docs/utils/morty.sh.rst+11−4 docs/utils/searx.sh.rst+50−3
docs/admin/arch_public.dot+4−4
@@ -4,11 +4,11 @@ digraph G {
44 edge [fontname="Sans"];
55
66 browser [label="Browser", shape=Mdiamond];
7− rp [label="Reverse Proxy", href="url to configure reverse proxy"];
8− filtron [label="Filtron", href="https://github.com/asciimoo/filtron"];
9− morty [label="Morty", href="https://github.com/asciimoo/morty"];
7+ rp [label="Reverse Proxy", href="https://asciimoo.github.io/searx/utils/filtron.sh.html#public-reverse-proxy"];
8+ filtron [label="Filtron", href="https://asciimoo.github.io/searx/utils/filtron.sh.html"];
9+ morty [label="Morty", href="https://asciimoo.github.io/searx/utils/morty.sh.html"];
1010 static [label="Static files", href="url to configure static files"];
11− uwsgi [label="uwsgi", href="url to configure uwsgi"]
11+ uwsgi [label="uwsgi", href="https://asciimoo.github.io/searx/utils/searx.sh.html"]
1212 searx1 [label="Searx #1"];
1313 searx2 [label="Searx #2"];
1414 searx3 [label="Searx #3"];
docs/admin/architecture.rst+7−5
@@ -4,17 +4,19 @@
44Architecture
55============
66
7−.. sidebar:: Needs work!
7+.. sidebar:: Tooling box
88
9− This article needs some work / Searx is a collaborative effort. If you have
10− any contribution, feel welcome to send us your :pull:`PR <../pulls>`, see
11− :ref:`how to contribute`.
9+ - :ref:`searx & uwsgi <searx.sh>`
10+ - :ref:`filtron <filtron.sh>`
11+ - :ref:`reverse proxy`
12+ - :ref:`morty <morty.sh>`
1213
1314Herein you will find some hints and suggestions about typical architectures of
1415searx infrastructures.
1516
1617We start with a contribution from :pull:`@dalf <1776#issuecomment-567917320>`.
17−It shows a *reference* setup for public searx instances.
18+It shows a *reference* setup for public searx instances which can build up and
19+maintained by the scripts from our :ref:`toolboxing`.
1820
1921.. _arch public:
2022
docs/admin/installation.rst+6
@@ -7,9 +7,15 @@ Installation
77.. contents::
88 :depth: 3
99
10+.. _installation basic:
11+
1012Basic installation
1113==================
1214
15+.. sidebar:: further reading
16+
17+ - :ref:`searx.sh`
18+
1319Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure
1420to have enable universe repository.
1521
docs/dev/makefile.rst+6−4
@@ -39,15 +39,17 @@ Calling the ``help`` target gives a first overview::
3939
4040.. _makefile setup:
4141
42−Setup
43−=====
42+Makefile setup
43+==============
4444
4545.. _git stash: https://git-scm.com/docs/git-stash
4646
47−The main setup is done in the :origin:`Makefile`::
47+The main setup is done in the :origin:`.config.sh` (read :ref:`toolboxing
48+setup`)::
4849
49− export GIT_URL=https://github.com/asciimoo/searx
5050 export SEARX_URL=https://searx.me
51+
52+ export GIT_URL=https://github.com/asciimoo/searx
5153 export DOCS_URL=https://asciimoo.github.io/searx
5254
5355.. sidebar:: fork & upstream
docs/utils/filtron.sh.rst+33−1
@@ -8,6 +8,7 @@
88.. sidebar:: further reading
99
1010 - :ref:`searx_filtron`
11+ - :ref:`architecture`
1112
1213.. _Go: https://golang.org/
1314.. _filtron: https://github.com/asciimoo/filtron
@@ -34,11 +35,42 @@ into this user account:
3435 <utils/templates/lib/systemd/system/filtron.service>`
3536 (``/lib/systemd/system/filtron.service``).
3637
38+.. _reverse proxy:
39+
40+Public Reverse Proxy
41+====================
42+
43+.. tabs::
44+
45+To install searx in your public HTTP server use:
46+
47+.. code:: bash
48+
49+ sudo -H ./utils/filtron.sh apache install
50+
51+.. tabs::
52+
53+ .. group-tab:: apache
54+
55+ .. literalinclude:: ../../utils/templates/etc/apache2/sites-available/searx.conf:filtron
56+ :language: apache
57+
58+ .. tabs::
59+
60+ .. group-tab:: Ubuntu / debian
61+
62+ .. code-block:: sh
63+
64+ $ sudo -H a2enmod headers
65+ $ sudo -H a2enmod proxy
66+ $ sudo -H a2enmod proxy_http
67+
3768
3869Overview
3970========
4071
41−The ``--help`` output of the script is largely self-explanatory:
72+The ``--help`` output of the script is largely self-explanatory
73+(:ref:`toolboxing common`):
4274
4375.. program-output:: ../utils/filtron.sh --help
4476
docs/utils/index.rst+36−7
@@ -1,9 +1,10 @@
11
22.. _searx_utils:
3+.. _toolboxing:
34
4−======================
5−Tooling box ``utils/``
6−======================
5+=======================
6+Tooling box ``utils/*``
7+=======================
78
89In the folder :origin:`utils/` we maintain some tools useful for admins and
910developers.
@@ -15,9 +16,37 @@ developers.
1516 filtron.sh
1617 morty.sh
1718
18−.. hint::
19+.. admonition:: Work needed!
1920
20− ATM :ref:`filtron.sh` and :ref:`searx.sh` do supports only systemd init
21− process used by debian, ubuntu and many other dists. If you have working
22− init.d files to start/stop services, please contribute / thanks!
21+ Our scripts to maintain services do most support only systemd init process
22+ used by debian, ubuntu and many other dists. In general our scripts are only
23+ partially usable on debian systems. We are working on this limitation, if
24+ you have any contribution, please send us your :pull:`PR <../pulls>`, see
25+ :ref:`how to contribute`.
2326
27+.. _toolboxing common:
28+
29+Common commands
30+===============
31+
32+Scripts to maintain services often dispose of common commands and environments.
33+
34+``shell``:
35+ Opens a shell from the service user ``${SERVICE_USSR}``, very helpful for
36+ troubleshooting.
37+
38+``inspect service``:
39+ Shows status and log of the service, most often you have a option to enable
40+ more verbose debug logs. Very helpful for debugging, but be careful not to
41+ enable debugging in a production environment!
42+
43+.. _toolboxing setup:
44+
45+Tooling box setup
46+=================
47+
48+The main setup is done in the :origin:`.config.sh` (read also :ref:`makefile
49+setup`).
50+
51+.. literalinclude:: ../../.config.sh
52+ :language: bash
docs/utils/morty.sh.rst+11−4
@@ -1,13 +1,17 @@
11
2−.. _morty.sh:
3−
42.. _morty: https://github.com/asciimoo/morty
53.. _morty's README: https://github.com/asciimoo/morty
64
5+.. _morty.sh:
6+
77==================
88``utils/morty.sh``
99==================
1010
11+.. sidebar:: further reading
12+
13+ - :ref:`architecture`
14+
1115To simplify installation and maintenance of a morty_ instance you can use the
1216script :origin:`utils/morty.sh`. In most cases you will install morty_ simply by
1317running the command:
@@ -24,8 +28,11 @@ into this user account.
2428 To add morty to your searx instance read chapter :reF:`searx_morty`.
2529
2630
27−The ``--help`` output of the script is largely
28−self-explanatory:
31+Overview
32+========
33+
34+The ``--help`` output of the script is largely self-explanatory
35+(:ref:`toolboxing common`):
2936
3037.. program-output:: ../utils/morty.sh --help
3138
docs/utils/searx.sh.rst+50−3
@@ -5,6 +5,11 @@
55``utils/searx.sh``
66==================
77
8+.. sidebar:: further reading
9+
10+ - :ref:`installation`
11+ - :ref:`architecture`
12+
813To simplify installation and maintenance of a searx instance you can use the
914script :origin:`utils/searx.sh`. In most cases you will install searx simply by
1015running the command:
@@ -14,8 +19,50 @@ running the command:
1419 sudo -H ./utils/searx.sh install all
1520
1621The script adds a ``${SERVICE_USER}`` (default:``searx``) and installs searx
17−into this user account. The ``--help`` output of the script is largely
18−self-explanatory:
22+into this user account. The installation is described in chapter
23+:ref:`installation basic`.
1924
20−.. program-output:: ../utils/searx.sh --help
25+.. _intranet reverse proxy:
26+
27+Intranet Reverse Proxy
28+======================
29+
30+.. warning::
31+
32+ This setup is **not** suitable **for public instances**, go on with
33+ :ref:`reverse proxy`!
34+
35+To install searx in your intranet HTTP server use:
36+
37+.. code:: bash
38+
39+ sudo -H ./utils/searx.sh apache install
40+
41+.. tabs::
42+
43+ .. group-tab:: apache
2144
45+ .. literalinclude:: ../../utils/templates/etc/apache2/sites-available/searx.conf:uwsgi
46+ :language: apache
47+
48+ .. tabs::
49+
50+ .. group-tab:: Ubuntu / debian
51+
52+ .. code-block:: sh
53+
54+ $ sudo -H apt install libapache2-mod-uwsgi
55+
56+ .. group-tab:: Arch Linux
57+
58+ .. code-block:: sh
59+
60+ $ sudo pacman -S uwsgi
61+
62+Overview
63+========
64+
65+The ``--help`` output of the script is largely self-explanatory
66+(:ref:`toolboxing common`):
67+
68+.. program-output:: ../utils/searx.sh --help