diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/admin/engines/settings.rst | 142 | ||||
| -rw-r--r-- | docs/admin/filtron.rst | 14 | ||||
| -rw-r--r-- | docs/conf.py | 5 | ||||
| -rw-r--r-- | docs/dev/makefile.rst | 8 | ||||
| -rw-r--r-- | docs/dev/translation.rst | 1 | ||||
| -rw-r--r-- | docs/src/searx.babel_extract.rst | 8 | ||||
| -rw-r--r-- | docs/src/searx.plugins.limiter.rst | 4 |
7 files changed, 156 insertions, 26 deletions
diff --git a/docs/admin/engines/settings.rst b/docs/admin/engines/settings.rst index 1c7ee4a86..85feddd6a 100644 --- a/docs/admin/engines/settings.rst +++ b/docs/admin/engines/settings.rst @@ -37,10 +37,10 @@ see how you can simplify your *user defined* ``settings.yml``. Global Settings =============== -.. _settings global brand: +.. _settings brand: ``brand:`` ------------- +---------- .. code:: yaml @@ -62,7 +62,7 @@ Global Settings ``wiki_url`` : Link to your wiki (or ``false``) -.. _settings global general: +.. _settings general: ``general:`` ------------ @@ -85,7 +85,78 @@ Global Settings Enabled by default. Record various anonymous metrics availabled at ``/stats``, ``/stats/errors`` and ``/preferences``. -.. _settings global server: +.. _settings search: + +``search:`` +----------- + +.. code:: yaml + + search: + safe_search: 0 + autocomplete: "" + default_lang: "" + ban_time_on_fail: 5 + max_ban_time_on_fail: 120 + formats: + - html + +``safe_search``: + Filter results. + + - ``0``: None + - ``1``: Moderate + - ``2``: Strict + +``autocomplete``: + Existing autocomplete backends, leave blank to turn it off. + + - ``dbpedia`` + - ``duckduckgo`` + - ``google`` + - ``startpage`` + - ``swisscows`` + - ``qwant`` + - ``wikipedia`` + +``default_lang``: + Default search language - leave blank to detect from browser information or + use codes from :origin:`searx/languages.py`. + +``languages``: + List of available languages - leave unset to use all codes from + :origin:`searx/languages.py`. Otherwise list codes of available languages. + The ``all`` value is shown as the ``Default language`` in the user interface + (in most cases, it is meant to send the query without a language parameter ; + in some cases, it means the English language) Example: + + .. code:: yaml + + languages: + - all + - en + - en-US + - de + - it-IT + - fr + - fr-BE + +``ban_time_on_fail``: + Ban time in seconds after engine errors. + +``max_ban_time_on_fail``: + Max ban time in seconds after engine errors. + +``formats``: + Result formats available from web, remove format to deny access (use lower + case). + + - ``html`` + - ``csv`` + - ``json`` + - ``rss`` + +.. _settings server: ``server:`` ----------- @@ -98,8 +169,6 @@ Global Settings bind_address: "127.0.0.1" # address to listen on secret_key: "ultrasecretkey" # change this! image_proxy: false # proxying image results through SearXNG - default_locale: "" # default interface locale - default_theme: oscar # ui theme default_http_headers: X-Content-Type-Options : nosniff X-XSS-Protection : 1; mode=block @@ -128,6 +197,26 @@ Global Settings ``image_proxy`` : Allow your instance of SearXNG of being able to proxy images. Uses memory space. +.. _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>`__ + + +.. _settings ui: + +``ui:`` +------- + +.. code:: yaml + + ui: + default_locale: "" + query_in_title: false + default_theme: simple + theme_args: + simple_style: auto + ``default_locale`` : SearXNG interface language. If blank, the locale is detected by using the browser language. If it doesn't work, or you are deploying a language @@ -137,10 +226,15 @@ Global Settings ``default_theme`` : Name of the theme you want to use by default on your SearXNG instance. -.. _HTTP headers: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers +``theme_args.simple_style``: + Style of simple theme: ``auto``, ``light``, ``dark`` -``default_http_headers``: - Set additional HTTP headers, see `#755 <https://github.com/searx/searx/issues/715>`__ +``query_in_title``: + When true, the result page's titles contains the query it decreases the + privacy, since the browser can records the page titles. + +``results_on_new_tab``: + Open result links in a new tab by default. .. _settings redis: @@ -150,6 +244,17 @@ Global Settings .. _Redis.from_url(url): https://redis-py.readthedocs.io/en/stable/connections.html#redis.client.Redis.from_url +A redis DB can be connected by an URL, in :py:obj:`searx.shared.redisdb` you +will find a description to test your redis connection in SerXNG. When using +sockets, don't forget to check the access rights on the socket:: + + ls -la /usr/local/searxng-redis/run/redis.sock + srwxrwx--- 1 searxng-redis searxng-redis ... /usr/local/searxng-redis/run/redis.sock + +In this example read/write access is given to the *searxng-redis* group. To get +access rights to redis instance (the socket), your SearXNG (or even your +developer) account needs to be added to the *searxng-redis* group. + ``url`` URL to connect redis database, see `Redis.from_url(url)`_ & :ref:`redis db`:: @@ -159,17 +264,21 @@ Global Settings .. admonition:: Tip for developers - To set up a redis instance simply use:: + To set up a local redis instance using sockets simply use:: $ ./manage redis.build $ sudo -H ./manage redis.install - - To get access rights to this instance, your developer account needs to be - added to the *searxng-redis* group:: - $ sudo -H ./manage redis.addgrp "${USER}" # don't forget to logout & login to get member of group + The YAML setting for such a redis instance is: + + .. code:: yaml + + redis: + url: unix:///usr/local/searxng-redis/run/redis.sock?db=0 + + .. _settings outgoing: ``outgoing:`` @@ -374,8 +483,9 @@ engine is shown. Most of the options have a default value or even are optional. ``network``: optional Use the network configuration from another engine. In addition, there are two default networks: - * ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses) - * ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses) + + - ``ipv4`` set ``local_addresses`` to ``0.0.0.0`` (use only IPv4 local addresses) + - ``ipv6`` set ``local_addresses`` to ``::`` (use only IPv6 local addresses) .. note:: diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst index f08149ae9..60d7cbeba 100644 --- a/docs/admin/filtron.rst +++ b/docs/admin/filtron.rst @@ -5,17 +5,19 @@ How to protect an instance ========================== +.. tip:: + + To protect your instance a installation of filtron (as described here) is no + longer needed, alternatively activate the :ref:`limiter plugin` in your + ``settings.yml``. Note that the :ref:`limiter plugin` requires a :ref:`Redis + <settings redis>` database. + + .. sidebar:: further reading - :ref:`filtron.sh` - :ref:`nginx searxng site` - -.. contents:: Contents - :depth: 2 - :local: - :backlinks: entry - .. _filtron: https://github.com/searxng/filtron SearXNG depends on external search services. To avoid the abuse of these services diff --git a/docs/conf.py b/docs/conf.py index 1dd5693ca..5db9e8178 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -123,6 +123,7 @@ extensions = [ 'linuxdoc.kfigure', # Sphinx extension which implements scalable image handling. "sphinx_tabs.tabs", # https://github.com/djungelorm/sphinx-tabs 'myst_parser', # https://www.sphinx-doc.org/en/master/usage/markdown.html + 'notfound.extension', # https://github.com/readthedocs/sphinx-notfound-page ] suppress_warnings = ['myst.domains'] @@ -140,6 +141,10 @@ issues_github_path = "searxng/searxng" # HTML ----------------------------------------------------------------- +# https://searxng.github.io/searxng --> '/searxng/' +# https://docs.searxng.org --> '/' +notfound_urls_prefix = '/' + sys.path.append(os.path.abspath('_themes')) sys.path.insert(0, os.path.abspath("../utils/")) html_theme_path = ['_themes'] diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index 8e9de7882..ceb76bf10 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -87,7 +87,7 @@ the :origin:`setup.py` file, you have to call :ref:`make clean`. ================= Rebuild instance's environment with the modified settings from the -:ref:`settings global brand` and :ref:`settings global server` section of your +:ref:`settings brand` and :ref:`settings server` section of your :ref:`settings.yml <settings location>`. We have all SearXNG setups are centralized in the :ref:`settings.yml` file. @@ -107,10 +107,10 @@ The ``make buildenv`` target will update the *build environment* in: Tasks running outside of an *installed instance*, need the following settings from the YAML configuration: -- ``SEARXNG_URL`` from :ref:`server.base_url <settings global server>` (aka +- ``SEARXNG_URL`` from :ref:`server.base_url <settings server>` (aka ``PUBLIC_URL``) -- ``SEARXNG_BIND_ADDRESS`` from :ref:`server.bind_address <settings global server>` -- ``SEARXNG_PORT`` from :ref:`server.port <settings global server>` +- ``SEARXNG_BIND_ADDRESS`` from :ref:`server.bind_address <settings server>` +- ``SEARXNG_PORT`` from :ref:`server.port <settings server>` .. _make node.env: diff --git a/docs/dev/translation.rst b/docs/dev/translation.rst index 922c29c54..9de9ff2de 100644 --- a/docs/dev/translation.rst +++ b/docs/dev/translation.rst @@ -16,6 +16,7 @@ Translation .. sidebar:: |translated| + - :ref:`searx.babel_extract` - Weblate_ - SearXNG `translations branch`_ - SearXNG `Weblate repository`_ diff --git a/docs/src/searx.babel_extract.rst b/docs/src/searx.babel_extract.rst new file mode 100644 index 000000000..741d67fc1 --- /dev/null +++ b/docs/src/searx.babel_extract.rst @@ -0,0 +1,8 @@ +.. _searx.babel_extract: + +=============================== +Custom message extractor (i18n) +=============================== + +.. automodule:: searx.babel_extract + :members: diff --git a/docs/src/searx.plugins.limiter.rst b/docs/src/searx.plugins.limiter.rst index 4984cd37a..75d06f5c2 100644 --- a/docs/src/searx.plugins.limiter.rst +++ b/docs/src/searx.plugins.limiter.rst @@ -4,6 +4,10 @@ Limiter Plugin ============== +.. sidebar:: info + + The :ref:`limiter plugin` requires a :ref:`Redis <settings redis>` database. + .. automodule:: searx.plugins.limiter :members: |