From 4853a2980322ccd84597a6502dce3ca7f5c76af0 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Sat, 2 Jan 2021 19:56:26 +0100 Subject: [PATCH] [mod] improve settings documentation Signed-off-by: Markus Heiser --- docs/admin/installation-searx.rst | 13 +++- docs/admin/settings.rst | 118 ++++++++++++++++++------------ 2 files changed, 83 insertions(+), 48 deletions(-) diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst index 3f8904a1d..512a185a7 100644 --- a/docs/admin/installation-searx.rst +++ b/docs/admin/installation-searx.rst @@ -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 ` + 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 ` from +:ref:`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 diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst index cc4007d2f..7cf055dbf 100644 --- a/docs/admin/settings.rst +++ b/docs/admin/settings.rst @@ -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 `__ +``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,61 +281,76 @@ 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 ` -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`` -.. code-block:: yaml +``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``: - use_default_settings: True - server: - secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" - bind_address: "0.0.0.0" + .. code-block:: yaml -With ``use_default_settings: True``, each settings can be override in a similar way, the ``engines`` section is merged according to the engine ``name``. + use_default_settings: True + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + bind_address: "0.0.0.0" -In this example, searx will load all the engine and the arch linux wiki engine has a :ref:`token`: +``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`: -.. code-block:: yaml + .. code-block:: yaml - use_default_settings: True - server: - secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" - engines: - - name: arch linux wiki - tokens: ['$ecretValue'] + use_default_settings: True + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + engines: + - 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 + .. code-block:: yaml - use_default_settings: - engines: - remove: - - google - server: - secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" - engines: - - name: arch linux wiki - tokens: ['$ecretValue'] + use_default_settings: + engines: + remove: + - google + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + engines: + - 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 + .. code-block:: yaml - use_default_settings: - engines: - keep_only: - - google - - duckduckgo - server: - secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" - engines: - - name: google - tokens: ['$ecretValue'] - - name: duckduckgo - tokens: ['$ecretValue'] + use_default_settings: + engines: + keep_only: + - google + - duckduckgo + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + engines: + - name: google + tokens: ['$ecretValue'] + - name: duckduckgo + tokens: ['$ecretValue']