[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>
This commit is contained in:
Markus Heiser 2020-12-08 20:19:10 +01:00
parent c1a9732268
commit a70b9b9f61
6 changed files with 186 additions and 106 deletions

View File

@ -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}"

View File

@ -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 <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
=====

View File

@ -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 <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
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 <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
@ -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
====================

View File

@ -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\"

View File

@ -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

View File

@ -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"