docs: add some documentation about the tooling box ./utils/*

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2020-02-04 13:13:17 +01:00
parent 8ca86f46d3
commit 9278f0fb45
8 changed files with 153 additions and 28 deletions

View file

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

View file

@ -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 <searx.sh>`
- :ref:`filtron <filtron.sh>`
- :ref:`reverse proxy`
- :ref:`morty <morty.sh>`
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:

View file

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

View file

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

View file

@ -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:
<utils/templates/lib/systemd/system/filtron.service>`
(``/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

View file

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

View file

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

View file

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