diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/admin/buildhosts.rst | 2 | ||||
| -rw-r--r-- | docs/admin/installation-nginx.rst | 2 | ||||
| -rw-r--r-- | docs/admin/installation-searx.rst | 29 | ||||
| -rw-r--r-- | docs/admin/settings.rst | 187 | ||||
| -rw-r--r-- | docs/build-templates/searx.rst | 20 | ||||
| -rw-r--r-- | docs/conf.py | 6 | ||||
| -rw-r--r-- | docs/dev/contribution_guide.rst | 4 | ||||
| -rw-r--r-- | docs/dev/engine_overview.rst | 2 | ||||
| -rw-r--r-- | docs/dev/quickstart.rst | 2 | ||||
| -rw-r--r-- | docs/dev/reST.rst | 24 |
10 files changed, 167 insertions, 111 deletions
diff --git a/docs/admin/buildhosts.rst b/docs/admin/buildhosts.rst index a727d25b9..1f6eb472e 100644 --- a/docs/admin/buildhosts.rst +++ b/docs/admin/buildhosts.rst @@ -67,7 +67,7 @@ to ``imgmath``: If your docs build (``make docs``) shows warnings like this:: WARNING: dot(1) not found, for better output quality install \ - graphviz from http://www.graphviz.org + graphviz from https://www.graphviz.org .. WARNING: LaTeX command 'latex' cannot be run (needed for math \ display), check the imgmath_latex setting diff --git a/docs/admin/installation-nginx.rst b/docs/admin/installation-nginx.rst index 65fd73573..589c40ada 100644 --- a/docs/admin/installation-nginx.rst +++ b/docs/admin/installation-nginx.rst @@ -9,7 +9,7 @@ Install with nginx .. _nginx server configuration: https://docs.nginx.com/nginx/admin-guide/web-server/web-server/#setting-up-virtual-servers .. _nginx beginners guide: - http://nginx.org/en/docs/beginners_guide.html + https://nginx.org/en/docs/beginners_guide.html .. _Getting Started wiki: https://www.nginx.com/resources/wiki/start/ .. _uWSGI support from nginx: diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst index a368bfe8c..3f8904a1d 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. + +.. _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 ===== diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst index 532b99752..985c16f85 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,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,7 +82,49 @@ Global Settings specific instance of searx, a locale can be defined using an ISO language code, like ``fr``, ``en``, ``de``. -.. _requests proxies: http://requests.readthedocs.io/en/latest/user/advanced/#proxies +``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/ ``proxies`` : @@ -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 ==================== diff --git a/docs/build-templates/searx.rst b/docs/build-templates/searx.rst index 080de293f..fe82ec3d0 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/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\" diff --git a/docs/conf.py b/docs/conf.py index 4b348ae0e..d6fde9bec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,11 +49,11 @@ extlinks['man'] = ('https://manpages.debian.org/jump?q=%s', '') #extlinks['role'] = ( # 'https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-%s', '') extlinks['duref'] = ( - 'http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '') + 'https://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#%s', '') extlinks['durole'] = ( - 'http://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '') + 'https://docutils.sourceforge.net/docs/ref/rst/roles.html#%s', '') extlinks['dudir'] = ( - 'http://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '') + 'https://docutils.sourceforge.net/docs/ref/rst/directives.html#%s', '') extlinks['ctan'] = ( 'https://ctan.org/pkg/%s', 'CTAN: ') diff --git a/docs/dev/contribution_guide.rst b/docs/dev/contribution_guide.rst index 26f8d2bb7..90b22670c 100644 --- a/docs/dev/contribution_guide.rst +++ b/docs/dev/contribution_guide.rst @@ -117,8 +117,8 @@ Translation currently takes place on :ref:`transifex <translation>`. Documentation ============= -.. _Sphinx: http://www.sphinx-doc.org -.. _reST: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html +.. _Sphinx: https://www.sphinx-doc.org +.. _reST: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. sidebar:: The reST sources diff --git a/docs/dev/engine_overview.rst b/docs/dev/engine_overview.rst index 0b5f9857f..99726a456 100644 --- a/docs/dev/engine_overview.rst +++ b/docs/dev/engine_overview.rst @@ -265,7 +265,7 @@ latitude latitude of result (in decimal format) longitude longitude of result (in decimal format) boundingbox boundingbox of result (array of 4. values ``[lat-min, lat-max, lon-min, lon-max]``) -geojson geojson of result (http://geojson.org) +geojson geojson of result (https://geojson.org/) osm.type type of osm-object (if OSM-Result) osm.id id of osm-object (if OSM-Result) address.name name of object diff --git a/docs/dev/quickstart.rst b/docs/dev/quickstart.rst index 3e1a5e344..14af03fa6 100644 --- a/docs/dev/quickstart.rst +++ b/docs/dev/quickstart.rst @@ -60,7 +60,7 @@ read :ref:`make test`. How to compile styles and javascript ==================================== -.. _less: http://lesscss.org/ +.. _less: https://lesscss.org/ .. _NodeJS: https://nodejs.org How to build styles diff --git a/docs/dev/reST.rst b/docs/dev/reST.rst index 906a0e9af..963378748 100644 --- a/docs/dev/reST.rst +++ b/docs/dev/reST.rst @@ -1391,27 +1391,27 @@ The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac`` .. _readability: https://docs.python-guide.org/writing/style/ .. _Sphinx-Primer: - http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html + https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _reST: https://docutils.sourceforge.io/rst.html .. _Sphinx Roles: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html -.. _Sphinx: http://www.sphinx-doc.org -.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html +.. _Sphinx: https://www.sphinx-doc.org +.. _`sphinx-doc FAQ`: https://www.sphinx-doc.org/en/stable/faq.html .. _Sphinx markup constructs: - http://www.sphinx-doc.org/en/stable/markup/index.html + https://www.sphinx-doc.org/en/stable/markup/index.html .. _`sphinx cross references`: - http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations + https://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations .. _sphinx.ext.extlinks: https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html -.. _intersphinx: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html -.. _sphinx config: http://www.sphinx-doc.org/en/stable/config.html -.. _Sphinx's autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html +.. _intersphinx: https://www.sphinx-doc.org/en/stable/ext/intersphinx.html +.. _sphinx config: https://www.sphinx-doc.org/en/stable/config.html +.. _Sphinx's autodoc: https://www.sphinx-doc.org/en/stable/ext/autodoc.html .. _Sphinx's Python domain: - http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain + https://www.sphinx-doc.org/en/stable/domains.html#the-python-domain .. _Sphinx's C domain: - http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs + https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-c-constructs .. _doctree: - http://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases + https://www.sphinx-doc.org/en/master/extdev/tutorial.html?highlight=doctree#build-phases .. _docutils: http://docutils.sourceforge.net/docs/index.html .. _docutils FAQ: http://docutils.sourceforge.net/FAQ.html .. _linuxdoc: https://return42.github.io/linuxdoc @@ -1424,5 +1424,5 @@ The next example shows the difference of ``\tfrac`` (*textstyle*) and ``\dfrac`` .. _ImageMagick: https://www.imagemagick.org .. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode -.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables +.. _`Online Tables Generator`: https://www.tablesgenerator.com/text_tables .. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html |