[mod] improve settings documentation

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2021-01-02 19:56:26 +01:00
parent d0338cb504
commit 4853a29803
2 changed files with 83 additions and 48 deletions

View file

@ -70,13 +70,20 @@ from the login (*~/.profile*):
Configuration
=============
.. sidebar:: ``use_default_settings: True``
- :ref:`settings global`
- :ref:`settings location`
- :ref:`settings use_default_settings`
- :origin:`/etc/searx/settings.yml <utils/templates/etc/searx/use_default_settings.yml>`
To create a initial ``/etc/searx/settings.yml`` you can start with a copy of the
file :origin:`utils/templates/etc/searx/use_default_settings.yml`. This setup
:option:ref:`use default settings <settings use_default_settings>` from
:ref:`use default settings <settings use_default_settings>` from
:origin:`searx/settings.yml` and is recommended since :pull:`2291` is merged.
For minimal Setup, configure like shown below replace ``searx@\$(uname -n)``
with a name of your choice, set ``ultrasecretkey`` -- *and/or* edit
For a *minimal setup*, configure like shown below replace ``searx@$(uname
-n)`` with a name of your choice, set ``ultrasecretkey`` -- *and/or* edit
``/etc/searx/settings.yml`` to your needs.
.. kernel-include:: $DOCS_BUILD/includes/searx.rst

View file

@ -27,7 +27,8 @@ First, searx will try to load settings.yml from these locations:
1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
2. ``/etc/searx/settings.yml``
If these files don't exist (or are empty or can't be read), searx uses the :origin:`searx/settings.yml` file.
If these files don't exist (or are empty or can't be read), searx uses the
:origin:`searx/settings.yml` file.
.. _settings global:
@ -35,6 +36,9 @@ If these files don't exist (or are empty or can't be read), searx uses the :orig
Global Settings
===============
``general:``
------------
.. code:: yaml
general:
@ -54,7 +58,7 @@ Global Settings
messages in the browser too, so this must be deactivated in production.
``contact_url``:
Contact mail address or WEB form.
Contact ``mailto:`` address or WEB form.
``git_url`` and ``git_branch``:
Changes this, to point to your searx fork (branch).
@ -69,6 +73,9 @@ Global Settings
Link to your tweets (or ``False``)
``server:``
-----------
.. code:: yaml
server:
@ -114,6 +121,8 @@ Global Settings
``default_http_headers``:
Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
``outgoing:``
-------------
.. code:: yaml
@ -163,6 +172,10 @@ Global Settings
If you use multiple network interfaces, define from which IP the requests must
be made. This parameter is ignored when ``proxies`` is set.
``locales:``
------------
.. code:: yaml
locales:
@ -268,13 +281,21 @@ Engine settings
use_default_settings
====================
.. note::
.. sidebar:: ``use_default_settings: True``
If searx is cloned from a git repository, most probably there is no need to have an user settings.
- :ref:`settings location`
- :ref:`use_default_settings.yml`
- :origin:`/etc/searx/settings.yml <utils/templates/etc/searx/use_default_settings.yml>`
The user defined settings.yml can relied on the default configuration :origin:`searx/settings.yml` using ``use_default_settings: True``.
The user defined ``settings.yml`` is loaded from the :ref:`settings location`
and can relied on the default configuration :origin:`searx/settings.yml` using:
In the following example, the actual settings are the default settings defined in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and the ``bind_address``:
``use_default_settings: True``
``server:``
In the following example, the actual settings are the default settings defined
in :origin:`searx/settings.yml` with the exception of the ``secret_key`` and
the ``bind_address``:
.. code-block:: yaml
@ -283,9 +304,11 @@ In the following example, the actual settings are the default settings defined i
secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
bind_address: "0.0.0.0"
With ``use_default_settings: True``, each settings can be override in a similar way, the ``engines`` section is merged according to the engine ``name``.
In this example, searx will load all the engine and the arch linux wiki engine has a :ref:`token<private engines>`:
``engines:``
With ``use_default_settings: True``, each settings can be override in a
similar way, the ``engines`` section is merged according to the engine
``name``. In this example, searx will load all the engine and the arch linux
wiki engine has a :ref:`token<private engines>`:
.. code-block:: yaml
@ -296,7 +319,10 @@ In this example, searx will load all the engine and the arch linux wiki engine h
- name: arch linux wiki
tokens: ['$ecretValue']
It is possible to remove some engines from the default settings. The following example is similar to the above one, but searx doesn't load the the google engine:
``engines:`` / ``remove:``
It is possible to remove some engines from the default settings. The following
example is similar to the above one, but searx doesn't load the the google
engine:
.. code-block:: yaml
@ -310,7 +336,9 @@ It is possible to remove some engines from the default settings. The following e
- name: arch linux wiki
tokens: ['$ecretValue']
As an alternative, it is possible to specify the engines to keep. In the following example, searx has only two engines:
``engines:`` / ``keep_only:``
As an alternative, it is possible to specify the engines to keep. In the
following example, searx has only two engines:
.. code-block:: yaml