Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a70b9b9f authored by Markus Heiser's avatar Markus Heiser
Browse files

[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: default avatarMarkus Heiser <markus.heiser@darmarit.de>
parent c1a97322

.config.sh

+1 −0
Original line number Diff line number Diff line
@@ -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

+25 −4
Original line number Diff line number Diff line
@@ -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

+102 −83
Original line number Diff line number Diff line
@@ -9,6 +9,7 @@ file. 


.. sidebar:: Further reading ..



   - :ref:`use_default_settings.yml`

   - :ref:`search API`



.. contents:: Contents
@@ -16,33 +17,89 @@ 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:

   #        http:

   #            - http://proxy1:8080
@@ -50,68 +107,23 @@ Global Settings 
   #        https:

   #            - http://proxy1:8080

   #            - http://proxy2:8080

       #        - socks5://user:password@proxy3:1080

       #        - socks5h://user:password@proxy4:1080



   # 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



   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





``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.

  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.



``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/
@@ -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,18 +239,6 @@ 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:



use_default_settings

docs/build-templates/searx.rst

+18 −2
Original line number Diff line number Diff line
@@ -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

+7 −6
Original line number Diff line number Diff line
@@ -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