[doc] recommend to use 'use_default_settings=True'

Since #2291 is merged, it is recommend to use::

  use_default_settings=True

1. Add a template file use_default_settings.yml::

    SEARX_SETTINGS_TEMPLATE="${REPO_ROOT}/utils/templates/etc/searx/use_default_settings.yml"

2. In Chapter "Configuration" recommend to make use of
   'use_default_settings=True' and describe it

3. Rewrite of docs/admin/settings.rst
   - move chapter 'settings.yml location' to the top
   - update and split chapter 'Global Settings'

4. Add environment SEARX_SETTINGS_TEMPLATE to .config.sh

5. Use environment $SEARX_SETTINGS_TEMPLATE in the utils/searx.sh script

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

.config.sh

@@ -26,6 +26,7 @@ fi
 # ---------
 
 # SEARX_INTERNAL_URL="127.0.0.1:8888"
+# SEARX_SETTINGS_TEMPLATE="${REPO_ROOT}/utils/templates/etc/searx/use_default_settings.yml"
 
 # Only change, if you maintain a searx brand in your searx fork.
 # GIT_BRANCH="${GIT_BRANCH:-master}"

docs/admin/installation-searx.rst

@@ -64,17 +64,38 @@ from the login (*~/.profile*):
    Open a second terminal for the configuration tasks and left the ``(searx)$``
    terminal open for the tasks below.
 
-Configuration
-==============
 
-Create a copy of the :origin:`searx/settings.yml` configuration file in system's
+.. _use_default_settings.yml:
-*/etc* folder.  Configure like shown below -- replace ``searx@\$(uname -n)`` with
+
-a name of your choice -- *and/or* edit ``/etc/searx/settings.yml`` if necessary.
+Configuration
+=============
+
+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
+: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
+``/etc/searx/settings.yml`` to your needs.
 
 .. kernel-include:: $DOCS_BUILD/includes/searx.rst
    :start-after: START searx config
    :end-before: END searx config
 
+.. tabs::
+
+  .. group-tab:: Use default settings
+
+    .. literalinclude:: ../../utils/templates/etc/searx/use_default_settings.yml
+       :language: yaml
+
+  .. group-tab:: searx/settings.yml
+
+    .. literalinclude:: ../../searx/settings.yml
+       :language: yaml
+
+
 Check
 =====
 

docs/admin/settings.rst

@@ -9,6 +9,7 @@ file.
 
 .. sidebar:: Further reading ..
 
+   - :ref:`use_default_settings.yml`
    - :ref:`search API`
 
 .. contents:: Contents
@@ -16,47 +17,130 @@ file.
    :local:
    :backlinks: entry
 
+.. _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 global:
 
 Global Settings
 ===============
 
+.. code:: yaml
+
+   general:
+       debug : False # Debug mode, only for development
+       instance_name : "searx" # displayed name
+
+``debug`` :
+  Allow a more detailed log if you run searx directly. Display *detailed* error
+  messages in the browser too, so this must be deactivated in production.
+
 .. code:: yaml
 
    server:
        port : 8888
+       bind_address : "127.0.0.1"      # address to listen on
        secret_key : "ultrasecretkey"   # change this!
-       debug : False                 # debug mode, only for development
-       request_timeout : 2.0         # seconds
        base_url : False                # set custom base_url (or False)
-       themes_path : ""              # custom ui themes path
-       default_theme : oscar         # ui theme
-       useragent_suffix : ""         # suffix of searx_useragent, could contain
-                                     # informations like admins email address
        image_proxy : False             # proxying image results through searx
        default_locale : ""             # default interface locale
+       default_theme : oscar           # ui theme
+       default_http_headers:
+           X-Content-Type-Options : nosniff
+           X-XSS-Protection : 1; mode=block
+           X-Download-Options : noopen
+           X-Robots-Tag : noindex, nofollow
+           Referrer-Policy : no-referrer
+
+``port`` & ``bind_address``:
+  Port number and *bind address* of the searx web application if you run it
+  directly using ``python searx/webapp.py``.  Doesn't apply to searx running on
+  Apache or Nginx.
+
+``secret_key`` :
+  Used for cryptography purpose.
+
+``base_url`` :
+  The base URL where searx is deployed.  Used to create correct inbound links.
+
+``image_proxy`` :
+  Allow your instance of searx of being able to proxy images.  Uses memory space.
+
+``default_locale`` :
+  Searx interface language.  If blank, the locale is detected by using the
+  browser language.  If it doesn't work, or you are deploying a language
+  specific instance of searx, a locale can be defined using an ISO language
+  code, like ``fr``, ``en``, ``de``.
+
+``default_theme`` :
+  Name of the theme you want to use by default on your searx instance.
+
+.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
+
+``default_http_headers``:
+  Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__
+
+
+.. code:: yaml
 
    outgoing: # communication with search engines
        request_timeout : 2.0        # default timeout in seconds, can be override by engine
        # max_request_timeout: 10.0  # the maximum timeout in seconds
-       useragent_suffix : "" # suffix of searx_useragent, could contain informations like an email address to the administrator
+       useragent_suffix : ""        # informations like an email address to the administrator
        pool_connections : 100       # Number of different hosts
        pool_maxsize : 10            # Number of simultaneous requests by host
-
+   # uncomment below section if you want to use a proxy
-       #proxies:
+   #    proxies:
    #        http:
    #            - http://proxy1:8080
    #            - http://proxy2:8080
    #        https:
    #            - http://proxy1:8080
    #            - http://proxy2:8080
-       #        - socks5://user:password@proxy3:1080
+   # uncomment below section only if you have more than one network interface
-       #        - socks5h://user:password@proxy4:1080
+   # which can be the source of outgoing search requests
-
+   #    source_ips:
-       #source_ips:
    #        - 1.1.1.1
    #        - 1.1.1.2
 
+
+``request_timeout`` :
+  Global timeout of the requests made to others engines in seconds.  A bigger
+  timeout will allow to wait for answers from slow engines, but in consequence
+  will slow searx reactivity (the result page may take the time specified in the
+  timeout to load). Can be override by :ref:`settings engine`
+
+``useragent_suffix`` :
+  Suffix to the user-agent searx uses to send requests to others engines.  If an
+  engine wish to block you, a contact info here may be useful to avoid that.
+
+.. _requests proxies: https://requests.readthedocs.io/en/latest/user/advanced/#proxies
+.. _PySocks: https://pypi.org/project/PySocks/
+
+``proxies`` :
+  Define one or more proxies you wish to use, see `requests proxies`_.
+  If there are more than one proxy for one protocol (http, https),
+  requests to the engines are distributed in a round-robin fashion.
+
+  - Proxy: `see <https://2.python-requests.org/en/latest/user/advanced/#proxies>`__.
+  - SOCKS proxies are also supported: `see <https://2.python-requests.org/en/latest/user/advanced/#socks>`__
+
+``source_ips`` :
+  If you use multiple network interfaces, define from which IP the requests must
+  be made. This parameter is ignored when ``proxies`` is set.
+
+.. code:: yaml
+
    locales:
        en : English
        de : Deutsch
@@ -71,59 +155,6 @@ Global Settings
        ru : Russian
        ro : Romanian
 
-
-``port`` :
-  Port number of the searx web application if you run it directly using ``python
-  searx/webapp.py``.  Doesn't apply to searx running on Apache or Nginx.
-
-``secret_key`` :
-  Used for cryptography purpose.
-
-``debug`` :
-  Allow a more detailed log if you run searx directly. Display *detailed* error
-  messages in the browser too, so this must be deactivated in production.
-
-``request_timeout`` :
-  Global timeout of the requests made to others engines in seconds.  A bigger
-  timeout will allow to wait for answers from slow engines, but in consequence
-  will slow searx reactivity (the result page may take the time specified in the
-  timeout to load)
-
-``base_url`` :
-  The base URL where searx is deployed.  Used to create correct inbound links.
-
-``themes_path`` :
-  Path to where the themes are located.  If you didn't develop anything, leave it
-  blank.
-
-``default_theme`` :
-  Name of the theme you want to use by default on your searx instance.
-
-``useragent_suffix`` :
-  Suffix to the user-agent searx uses to send requests to others engines.  If an
-  engine wish to block you, a contact info here may be useful to avoid that.
-
-``image_proxy`` :
-  Allow your instance of searx of being able to proxy images.  Uses memory space.
-
-``default_locale`` :
-  Searx interface language.  If blank, the locale is detected by using the
-  browser language.  If it doesn't work, or you are deploying a language
-  specific instance of searx, a locale can be defined using an ISO language
-  code, like ``fr``, ``en``, ``de``.
-
-.. _requests proxies: https://requests.readthedocs.io/en/latest/user/advanced/#proxies
-.. _PySocks: https://pypi.org/project/PySocks/
-
-``proxies`` :
-  Define one or more proxies you wish to use, see `requests proxies`_.
-  If there are more than one proxy for one protocol (http, https),
-  requests to the engines are distributed in a round-robin fashion.
-
-``source_ips`` :
-  If you use multiple network interfaces, define from which IP the requests must
-  be made. This parameter is ignored when ``proxies`` is set.
-
 ``locales`` :
   Locales codes and their names.  Available translations of searx interface.
 
@@ -208,19 +239,7 @@ Engine settings
    engines, and so won't be described here.
 
 
-.. _settings location:
+.. _settings use_default_settings:
-
-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
 ====================

docs/build-templates/searx.rst

@@ -128,12 +128,28 @@ ${fedora_build}
 
 .. tabs::
 
-  .. group-tab:: bash
+  .. group-tab:: Use default settings
 
     .. code-block:: sh
 
        $ sudo -H mkdir -p \"$(dirname ${SEARX_SETTINGS_PATH})\"
-       $ sudo -H cp \"$SEARX_SRC/searx/settings.yml\" \"${SEARX_SETTINGS_PATH}\"
+       $ sudo -H cp \"$SEARX_SRC/utils/templates/etc/searx/use_default_settings.yml\" \\
+                    \"${SEARX_SETTINGS_PATH}\"
+
+  .. group-tab:: searx/settings.yml
+
+    .. code-block:: sh
+
+       $ sudo -H mkdir -p \"$(dirname ${SEARX_SETTINGS_PATH})\"
+       $ sudo -H cp \"$SEARX_SRC/searx/settings.yml\" \\
+                    \"${SEARX_SETTINGS_PATH}\"
+
+.. tabs::
+
+  .. group-tab:: minimal setup
+
+    .. code-block:: sh
+
        $ sudo -H sed -i -e \"s/ultrasecretkey/\$(openssl rand -hex 16)/g\" \"$SEARX_SETTINGS_PATH\"
        $ sudo -H sed -i -e \"s/{instance_name}/searx@\$(uname -n)/g\" \"$SEARX_SETTINGS_PATH\"
 

utils/searx.sh

@@ -36,6 +36,7 @@ GIT_BRANCH="${GIT_BRANCH:-master}"
 SEARX_PYENV="${SERVICE_HOME}/searx-pyenv"
 SEARX_SRC="${SERVICE_HOME}/searx-src"
 SEARX_SETTINGS_PATH="/etc/searx/settings.yml"
+SEARX_SETTINGS_TEMPLATE="${REPO_ROOT}/utils/templates/etc/searx/use_default_settings.yml"
 SEARX_UWSGI_APP="searx.ini"
 # shellcheck disable=SC2034
 SEARX_UWSGI_SOCKET="/run/uwsgi/app/searx/socket"
@@ -139,7 +140,7 @@ usage() {
     cat <<EOF
 usage::
   $(basename "$0") shell
-  $(basename "$0") install    [all|user|searx-src|pyenv|uwsgi|packages|buildhost]
+  $(basename "$0") install    [all|user|searx-src|pyenv|uwsgi|packages|settings|buildhost]
   $(basename "$0") update     [searx]
   $(basename "$0") remove     [all|user|pyenv|searx-src]
   $(basename "$0") activate   [service]
@@ -413,14 +414,14 @@ install_settings() {
     if [[ ! -f ${SEARX_SETTINGS_PATH} ]]; then
         info_msg "install settings ${REPO_ROOT}/searx/settings.yml"
         info_msg "  --> ${SEARX_SETTINGS_PATH}"
-        cp "${REPO_ROOT}/searx/settings.yml" "${SEARX_SETTINGS_PATH}"
+        cp "${SEARX_SETTINGS_TEMPLATE}" "${SEARX_SETTINGS_PATH}"
         configure_searx
         return
     fi
 
     rst_para "Diff between origin's setting file (+) and current (-):"
-    echo
+    echo "${SEARX_SETTINGS_PATH}" "${SEARX_SETTINGS_TEMPLATE}"
-    $DIFF_CMD "${SEARX_SETTINGS_PATH}" "${SEARX_SRC}/searx/settings.yml"
+    $DIFF_CMD "${SEARX_SETTINGS_PATH}" "${SEARX_SETTINGS_TEMPLATE}"
 
     local action
     choose_one action "What should happen to the settings file? " \
@@ -434,7 +435,7 @@ install_settings() {
         "use origin settings")
             backup_file "${SEARX_SETTINGS_PATH}"
             info_msg "install origin settings"
-            cp "${SEARX_SRC}/searx/settings.yml" "${SEARX_SETTINGS_PATH}"
+            cp "${SEARX_SETTINGS_TEMPLATE}" "${SEARX_SETTINGS_PATH}"
             ;;
         "start interactiv shell")
             backup_file "${SEARX_SETTINGS_PATH}"
@@ -442,7 +443,7 @@ install_settings() {
             sudo -H -i
             rst_para 'Diff between new setting file (-) and current (+):'
             echo
-            $DIFF_CMD "${SEARX_SRC}/searx/settings.yml" "${SEARX_SETTINGS_PATH}"
+            $DIFF_CMD "${SEARX_SETTINGS_TEMPLATE}" "${SEARX_SETTINGS_PATH}"
             wait_key
             ;;
     esac

utils/templates/etc/searx/use_default_settings.yml

@@ -0,0 +1,22 @@
+use_default_settings: True
+
+general:
+    debug : False # Debug mode, only for development
+    instance_name : "searx" # displayed name
+
+search:
+    safe_search : 0 # Filter results. 0: None, 1: Moderate, 2: Strict
+    autocomplete : "" # Existing autocomplete backends: "dbpedia", "duckduckgo", "google", "startpage", "swisscows", "qwant", "wikipedia" - leave blank to turn it off by default
+    default_lang : "" # Default search language - leave blank to detect from browser information or use codes from 'languages.py'
+
+server:
+    port : 8888
+    bind_address : "127.0.0.1" # address to listen on
+    secret_key : "ultrasecretkey" # change this!
+    base_url : False # Set custom base_url. Possible values: False or "https://your.custom.host/location/"
+    image_proxy : False # Proxying image results through searx
+
+# uncomment below section if you have running morty proxy
+#result_proxy:
+#    url : http://127.0.0.1:3000/
+#    key : !!binary "your_morty_proxy_key"