From 1cfe7f2a7543b2994a1afd0d81da1962d04423b0 Mon Sep 17 00:00:00 2001 From: Alexandre Flament Date: Tue, 3 Nov 2020 15:29:59 +0100 Subject: [enh] settings.yml: add use_default_settings option This change is backward compatible with the existing configurations. If a settings.yml loaded from an user defined location (SEARX_SETTINGS_PATH or /etc/searx/settings.yml), then this settings can relied on the default settings.yml with this option: user_default_settings:True --- docs/admin/settings.rst | 94 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) (limited to 'docs/admin') diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst index 58bce3541..cd944cc4c 100644 --- a/docs/admin/settings.rst +++ b/docs/admin/settings.rst @@ -206,3 +206,97 @@ Engine settings A few more options are possible, but they are pretty specific to some engines, and so won't be described here. + + +.. _settings location: + +settings.yml location +===================== + +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. + +.. _ settings use_default_settings: + +use_default_settings +==================== + +.. note:: + + If searx is cloned from a git repository, most probably there is no need to have an user settings. + +The user defined settings.yml can relied on the default configuration :origin:`searx/settings.yml` using ``use_default_settings: True``. + +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 + + use_default_settings: true + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + server: + bind_address: "0.0.0.0" + +With ``use_default_settings: True``, each settings can be override in a similar way with one exception, the ``engines`` section: + +* If the ``engines`` section is not defined in the user settings, searx uses the engines from the default setttings (the above example). +* If the ``engines`` section is defined then: + + * searx loads only the engines declare in the user setttings. + * searx merges the configuration according to the engine name. + +In the following example, only three engines are available. Each engine configuration is merged with the default configuration. + +.. code-block:: yaml + + use_default_settings: true + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + engines: + - name: wikipedia + - name: wikidata + - name: ddg definitions + +Another example where four engines are available. The arch linux wiki engine has a :ref:`token`. + +.. code-block:: yaml + + use_default_settings: true + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + engines: + - name: arch linux wiki + tokens: ['$ecretValue'] + - name: wikipedia + - name: wikidata + - name: ddg definitions + +automatic update +---------------- + +The following comand creates or updates a minimal user settings (a secret key is defined if it is not already the case): + +.. code-block:: sh + + make SEARX_SETTINGS_PATH=/etc/searx/settings.yml user-settings.update + +Set ``SEARX_SETTINGS_PATH`` to your user settings path. + +As soon the user settings contains an ``engines`` section, it becomes difficult to keep the engine list updated. +The following command creates or updates the user settings including the ``engines`` section: + +.. code-block:: sh + + make SEARX_SETTINGS_PATH=/etc/searx/settings.yml user-settings.update.engines + +After that ``/etc/searx/settings.yml`` + +* has a ``secret key`` +* has a ``engine`` section if it is not already the case, moreover the command: + + * has deleted engines that do not exist in the default settings. + * has added engines that exist in the default settings but are not declare in the user settings. -- cgit v1.2.3 From b4b81a5e1a74f03926e3c2e6f8c5fade99f7eabb Mon Sep 17 00:00:00 2001 From: Alexandre Flament Date: Fri, 27 Nov 2020 19:32:45 +0100 Subject: [enh] settings.yml: add use_default_settings option (2nd version) --- docs/admin/settings.rst | 67 ++++++++++++++++++------------------------------- 1 file changed, 25 insertions(+), 42 deletions(-) (limited to 'docs/admin') diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst index cd944cc4c..532b99752 100644 --- a/docs/admin/settings.rst +++ b/docs/admin/settings.rst @@ -235,68 +235,51 @@ In the following example, the actual settings are the default settings defined i .. code-block:: yaml - use_default_settings: true + use_default_settings: True server: secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" - server: bind_address: "0.0.0.0" -With ``use_default_settings: True``, each settings can be override in a similar way with one exception, the ``engines`` section: - -* If the ``engines`` section is not defined in the user settings, searx uses the engines from the default setttings (the above example). -* If the ``engines`` section is defined then: - - * searx loads only the engines declare in the user setttings. - * searx merges the configuration according to the engine name. +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 the following example, only three engines are available. Each engine configuration is merged with the default configuration. +In this example, searx will load all the engine and the arch linux wiki engine has a :ref:`token`: .. code-block:: yaml - use_default_settings: true + use_default_settings: True server: secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" engines: - - name: wikipedia - - name: wikidata - - name: ddg definitions + - name: arch linux wiki + tokens: ['$ecretValue'] -Another example where four engines are available. The arch linux wiki engine has a :ref:`token`. +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 - use_default_settings: true + use_default_settings: + engines: + remove: + - google server: secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" engines: - name: arch linux wiki tokens: ['$ecretValue'] - - name: wikipedia - - name: wikidata - - name: ddg definitions - -automatic update ----------------- - -The following comand creates or updates a minimal user settings (a secret key is defined if it is not already the case): - -.. code-block:: sh - - make SEARX_SETTINGS_PATH=/etc/searx/settings.yml user-settings.update - -Set ``SEARX_SETTINGS_PATH`` to your user settings path. -As soon the user settings contains an ``engines`` section, it becomes difficult to keep the engine list updated. -The following command creates or updates the user settings including the ``engines`` section: +As an alternative, it is possible to specify the engines to keep. In the following example, searx has only two engines: -.. code-block:: sh - - make SEARX_SETTINGS_PATH=/etc/searx/settings.yml user-settings.update.engines - -After that ``/etc/searx/settings.yml`` - -* has a ``secret key`` -* has a ``engine`` section if it is not already the case, moreover the command: +.. code-block:: yaml - * has deleted engines that do not exist in the default settings. - * has added engines that exist in the default settings but are not declare in the user settings. + use_default_settings: + engines: + keep_only: + - google + - duckduckgo + server: + secret_key: "uvys6bRhKHUdFF5CqbJonSDSRN8H0sCBziNSrDGNVdpz7IeZhveVart3yvghoKHA" + engines: + - name: google + tokens: ['$ecretValue'] + - name: duckduckgo + tokens: ['$ecretValue'] -- cgit v1.2.3