[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.
 
+
+.. _use_default_settings.yml:
+
 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.
 
-Create a copy of the :origin:`searx/settings.yml` configuration file in system's
-*/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.
+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,92 +17,61 @@ file.
    :local:
    :backlinks: entry
 
-.. _settings global:
+.. _settings location:
 
-Global Settings
-===============
+settings.yml location
+=====================
 
-.. code:: yaml
+First, searx will try to load settings.yml from these locations:
 
-   server:
-       port : 8888
-       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
+1. the full path specified in the ``SEARX_SETTINGS_PATH`` environment variable.
+2. ``/etc/searx/settings.yml``
 
-   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
-       pool_connections : 100 # Number of different hosts
-       pool_maxsize : 10 # Number of simultaneous requests by host
-
-       #proxies:
-       #    http:
-       #        - http://proxy1:8080
-       #        - http://proxy2:8080
-       #    https:
-       #        - http://proxy1:8080
-       #        - http://proxy2:8080
-       #        - socks5://user:password@proxy3:1080
-       #        - socks5h://user:password@proxy4:1080
-
-       #source_ips:
-       #    - 1.1.1.1
-       #    - 1.1.1.2
+If these files don't exist (or are empty or can't be read), searx uses the :origin:`searx/settings.yml` file.
 
-   locales:
-       en : English
-       de : Deutsch
-       he : Hebrew
-       hu : Magyar
-       fr : Français
-       es : Español
-       it : Italiano
-       nl : Nederlands
-       ja : 日本語 (Japanese)
-       tr : Türkçe
-       ru : Russian
-       ro : Romanian
 
+.. _settings global:
 
-``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.
+Global Settings
+===============
 
-``secret_key`` :
-  Used for cryptography purpose.
+.. 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.
 
-``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.
+.. code:: yaml
 
-``themes_path`` :
-  Path to where the themes are located.  If you didn't develop anything, leave it
-  blank.
+   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 (or False)
+       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.
 
-``default_theme`` :
-  Name of the theme you want to use by default on your searx instance.
+``secret_key`` :
+  Used for cryptography purpose.
 
-``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.
+``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.
@@ -112,6 +82,48 @@ Global Settings
   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 : ""        # 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:
+   #        http:
+   #            - http://proxy1:8080
+   #            - http://proxy2:8080
+   #        https:
+   #            - http://proxy1:8080
+   #            - http://proxy2:8080
+   # uncomment below section only if you have more than one network interface
+   # which can be the source of outgoing search requests
+   #    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/
 
@@ -120,10 +132,29 @@ Global Settings
   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
+       he : Hebrew
+       hu : Magyar
+       fr : Français
+       es : Español
+       it : Italiano
+       nl : Nederlands
+       ja : 日本語 (Japanese)
+       tr : Türkçe
+       ru : Russian
+       ro : Romanian
+
 ``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.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:
+.. _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/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}\"
+       $ 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
-    $DIFF_CMD "${SEARX_SETTINGS_PATH}" "${SEARX_SRC}/searx/settings.yml"
+    echo "${SEARX_SETTINGS_PATH}" "${SEARX_SETTINGS_TEMPLATE}"
+    $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"