From a70b9b9f616d75507bd404f036b95ce91cefefa4 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 8 Dec 2020 20:19:10 +0100 Subject: [PATCH] [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 --- .config.sh | 1 + docs/admin/installation-searx.rst | 31 ++- docs/admin/settings.rst | 205 ++++++++++-------- docs/build-templates/searx.rst | 20 +- utils/searx.sh | 13 +- .../etc/searx/use_default_settings.yml | 22 ++ 6 files changed, 186 insertions(+), 106 deletions(-) create mode 100644 utils/templates/etc/searx/use_default_settings.yml diff --git a/.config.sh b/.config.sh index 4eff5f4c..f9bac738 100644 --- a/.config.sh +++ b/.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}" diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst index a368bfe8..3f8904a1 100644 --- a/docs/admin/installation-searx.rst +++ b/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 -*/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. +.. _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 ` 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 ===== diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst index 7bd990fb..985c16f8 100644 --- a/docs/admin/settings.rst +++ b/docs/admin/settings.rst @@ -9,6 +9,7 @@ file. .. sidebar:: Further reading .. + - :ref:`use_default_settings.yml` - :ref:`search API` .. contents:: Contents @@ -16,46 +17,129 @@ 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 - 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 + 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. + +``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 `__ + + +.. 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 - pool_connections : 100 # Number of different hosts - pool_maxsize : 10 # Number of simultaneous requests by host + 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 - #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 +``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 `__. + - SOCKS proxies are also supported: `see `__ + +``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 @@ -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.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 ==================== diff --git a/docs/build-templates/searx.rst b/docs/build-templates/searx.rst index 080de293..fe82ec3d 100644 --- a/docs/build-templates/searx.rst +++ b/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\" diff --git a/utils/searx.sh b/utils/searx.sh index 386b2861..06b3c2df 100755 --- a/utils/searx.sh +++ b/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 < ${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 diff --git a/utils/templates/etc/searx/use_default_settings.yml b/utils/templates/etc/searx/use_default_settings.yml new file mode 100644 index 00000000..e019a25b --- /dev/null +++ b/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"