[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 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 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 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. :origin:`searx/settings.yml` and is recommended since :pull:`2291` is merged.
For minimal Setup, configure like shown below replace ``searx@\$(uname -n)`` For a *minimal setup*, configure like shown below replace ``searx@$(uname
with a name of your choice, set ``ultrasecretkey`` -- *and/or* edit -n)`` with a name of your choice, set ``ultrasecretkey`` -- *and/or* edit
``/etc/searx/settings.yml`` to your needs. ``/etc/searx/settings.yml`` to your needs.
.. kernel-include:: $DOCS_BUILD/includes/searx.rst .. 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. 1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
2. ``/etc/searx/settings.yml`` 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: .. _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 Global Settings
=============== ===============
``general:``
------------
.. code:: yaml .. code:: yaml
general: general:
@ -54,7 +58,7 @@ Global Settings
messages in the browser too, so this must be deactivated in production. messages in the browser too, so this must be deactivated in production.
``contact_url``: ``contact_url``:
Contact mail address or WEB form. Contact ``mailto:`` address or WEB form.
``git_url`` and ``git_branch``: ``git_url`` and ``git_branch``:
Changes this, to point to your searx fork (branch). Changes this, to point to your searx fork (branch).
@ -69,6 +73,9 @@ Global Settings
Link to your tweets (or ``False``) Link to your tweets (or ``False``)
``server:``
-----------
.. code:: yaml .. code:: yaml
server: server:
@ -114,6 +121,8 @@ Global Settings
``default_http_headers``: ``default_http_headers``:
Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__ Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
``outgoing:``
-------------
.. code:: yaml .. code:: yaml
@ -163,6 +172,10 @@ Global Settings
If you use multiple network interfaces, define from which IP the requests must If you use multiple network interfaces, define from which IP the requests must
be made. This parameter is ignored when ``proxies`` is set. be made. This parameter is ignored when ``proxies`` is set.
``locales:``
------------
.. code:: yaml .. code:: yaml
locales: locales:
@ -268,13 +281,21 @@ Engine settings
use_default_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 .. code-block:: yaml
@ -283,9 +304,11 @@ In the following example, the actual settings are the default settings defined i
secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA"
bind_address: "0.0.0.0" 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``. ``engines:``
With ``use_default_settings: True``, each settings can be override in a
In this example, searx will load all the engine and the arch linux wiki engine has a :ref:`token<private engines>`: 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 .. 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 - name: arch linux wiki
tokens: ['$ecretValue'] 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 .. 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 - name: arch linux wiki
tokens: ['$ecretValue'] 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 .. code-block:: yaml