diff options
Diffstat (limited to 'docs/dev/offline_engines.rst')
| -rw-r--r-- | docs/dev/offline_engines.rst | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/docs/dev/offline_engines.rst b/docs/dev/offline_engines.rst new file mode 100644 index 000000000..ce6924542 --- /dev/null +++ b/docs/dev/offline_engines.rst @@ -0,0 +1,78 @@ +.. _offline engines: + +=============== +Offline Engines +=============== + +.. sidebar:: offline engines + + - :ref:`demo offline engine` + - :ref:`sql engines` + - :ref:`engine command` + - :origin:`Redis <searx/engines/redis_server.py>` + +To extend the functionality of SearxNG, offline engines are going to be +introduced. An offline engine is an engine which does not need Internet +connection to perform a search and does not use HTTP to communicate. + +Offline engines can be configured, by adding those to the `engines` list of +:origin:`settings.yml <searx/settings.yml>`. An example skeleton for offline +engines can be found in :ref:`demo offline engine` (:origin:`demo_offline.py +<searx/engines/demo_offline.py>`). + + +Programming Interface +===================== + +:py:func:`init(engine_settings=None) <searx.engines.demo_offline.init>` + All offline engines can have their own init function to setup the engine before + accepting requests. The function gets the settings from settings.yml as a + parameter. This function can be omitted, if there is no need to setup anything + in advance. + +:py:func:`search(query, params) <searx.engines.demo_offline.searc>` + + Each offline engine has a function named ``search``. This function is + responsible to perform a search and return the results in a presentable + format. (Where *presentable* means presentable by the selected result + template.) + + The return value is a list of results retrieved by the engine. + +Engine representation in ``/config`` + If an engine is offline, the attribute ``offline`` is set to ``True``. + +.. _offline requirements: + +Extra Dependencies +================== + +If an offline engine depends on an external tool, SearxNG does not install it by +default. When an administrator configures such engine and starts the instance, +the process returns an error with the list of missing dependencies. Also, +required dependencies will be added to the comment/description of the engine, so +admins can install packages in advance. + +If there is a need to install additional packages in *Python's Virtual +Environment* of your SearxNG instance you need to switch into the environment +(:ref:`searx-src`) first, for this you can use :ref:`searx.sh`:: + + $ sudo utils/searx.sh shell + (searx-pyenv)$ pip install ... + + +Private engines (Security) +========================== + +To limit the access to offline engines, if an instance is available publicly, +administrators can set token(s) for each of the :ref:`private engines`. If a +query contains a valid token, then SearxNG performs the requested private +search. If not, requests from an offline engines return errors. + + +Acknowledgement +=============== + +This development was sponsored by `Search and Discovery Fund +<https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_ . + |