diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/admin/api.rst | 2 | ||||
| -rw-r--r-- | docs/admin/engines/index.rst | 1 | ||||
| -rw-r--r-- | docs/admin/engines/nosql-engines.rst | 136 | ||||
| -rw-r--r-- | docs/admin/engines/settings.rst | 73 | ||||
| -rw-r--r-- | docs/admin/installation-searx.rst | 2 | ||||
| -rw-r--r-- | docs/build-templates/searx.rst | 3 | ||||
| -rw-r--r-- | docs/dev/makefile.rst | 34 |
7 files changed, 224 insertions, 27 deletions
diff --git a/docs/admin/api.rst b/docs/admin/api.rst index 7804a8664..8c782ea9c 100644 --- a/docs/admin/api.rst +++ b/docs/admin/api.rst @@ -87,7 +87,7 @@ HTML of the site. URL of the searx instance and values are customizable. .. code:: html - <form method="post" action="https://searx.me/"> + <form method="post" action="https://example.org/"> <!-- search --> <input type="text" name="q" /> <!-- categories --> <input type="hidden" name="categories" value="general,social media" /> <!-- language --> <input type="hidden" name="lang" value="all" /> diff --git a/docs/admin/engines/index.rst b/docs/admin/engines/index.rst index 80f4120a5..f488731ea 100644 --- a/docs/admin/engines/index.rst +++ b/docs/admin/engines/index.rst @@ -17,6 +17,7 @@ Engines & Settings private-engines recoll sql-engines + nosql-engines search-indexer-engines command-line-engines searx.engines.xpath diff --git a/docs/admin/engines/nosql-engines.rst b/docs/admin/engines/nosql-engines.rst new file mode 100644 index 000000000..19a723c4e --- /dev/null +++ b/docs/admin/engines/nosql-engines.rst @@ -0,0 +1,136 @@ +=============== +NoSQL databases +=============== + +.. sidebar:: further read + + - `NoSQL databases <https://en.wikipedia.org/wiki/NoSQL>`_ + - `redis.io <https://redis.io/>`_ + - `MongoDB <https://www.mongodb.com>`_ + +The following `NoSQL databases`_ are supported: + +- :ref:`engine redis_server` +- :ref:`engine mongodb` + +All of the engines above are just commented out in the :origin:`settings.yml +<searx/settings.yml>`, as you have to set various options and install +dependencies before using them. + +By default, the engines use the ``key-value`` template for displaying results / +see :origin:`oscar <searx/templates/oscar/result_templates/key-value.html>` & +:origin:`simple <searx/templates/simple/result_templates/key-value.html>` +themes. If you are not satisfied with the original result layout, you can use +your own template, set ``result_template`` attribute to ``{template_name}`` and +place the templates at:: + + searx/templates/{theme_name}/result_templates/{template_name} + +Futhermore, if you do not wish to expose these engines on a public instance, you +can still add them and limit the access by setting ``tokens`` as described in +section :ref:`private engines`. + + +Configure the engines +===================== + +`NoSQL databases`_ are used for storing arbitrary data without first defining +their structure. + + +Extra Dependencies +------------------ + +For using :ref:`engine redis_server` or :ref:`engine mongodb` you need to +install additional packages in Python's Virtual Environment of your SearxNG +instance. To switch into the environment (:ref:`searx-src`) you can use +:ref:`searx.sh`:: + + $ sudo utils/searx.sh shell + (searx-pyenv)$ pip install ... + + +.. _engine redis_server: + +Redis Server +------------ + +.. _redis: https://github.com/andymccurdy/redis-py#installation + +.. sidebar:: info + + - ``pip install`` redis_ + - redis.io_ + - :origin:`redis_server.py <searx/engines/redis_server.py>` + + +Redis is an open source (BSD licensed), in-memory data structure (key value +based) store. Before configuring the ``redis_server`` engine, you must install +the dependency redis_. + +Select a database to search in and set its index in the option ``db``. You can +either look for exact matches or use partial keywords to find what you are +looking for by configuring ``exact_match_only``. You find an example +configuration below: + +.. code:: yaml + + # Required dependency: redis + + - name: myredis + shortcut : rds + engine: redis_server + exact_match_only: false + host: '127.0.0.1' + port: 6379 + enable_http: true + password: '' + db: 0 + +.. _engine mongodb: + +MongoDB +------- + +.. _pymongo: https://github.com/mongodb/mongo-python-driver#installation + +.. sidebar:: info + + - ``pip install`` pymongo_ + - MongoDB_ + - :origin:`mongodb.py <searx/engines/mongodb.py>` + +MongoDB_ is a document based database program that handles JSON like data. +Before configuring the ``mongodb`` engine, you must install the dependency +redis_. + +In order to query MongoDB_, you have to select a ``database`` and a +``collection``. Furthermore, you have to select a ``key`` that is going to be +searched. MongoDB_ also supports the option ``exact_match_only``, so configure +it as you wish. Below is an example configuration for using a MongoDB +collection: + +.. code:: yaml + + # MongoDB engine + # Required dependency: pymongo + + - name: mymongo + engine: mongodb + shortcut: md + exact_match_only: false + host: '127.0.0.1' + port: 27017 + enable_http: true + results_per_page: 20 + database: 'business' + collection: 'reviews' # name of the db collection + key: 'name' # key in the collection to search for + + +Acknowledgment +============== + +This development was sponsored by `Search and Discovery Fund +<https://nlnet.nl/discovery>`_ of `NLnet Foundation <https://nlnet.nl/>`_. + diff --git a/docs/admin/engines/settings.rst b/docs/admin/engines/settings.rst index 7335b9a2a..cab4ee493 100644 --- a/docs/admin/engines/settings.rst +++ b/docs/admin/engines/settings.rst @@ -37,15 +37,10 @@ see how you can simplify your *user defined* ``settings.yml``. Global Settings =============== -``general:`` ------------- - -.. code:: yaml +.. _settings global brand: - general: - debug: false # Debug mode, only for development - instance_name: "searxng" # displayed name - contact_url: false # mailto:contact@example.com +``brand:`` +------------ .. code:: yaml @@ -57,22 +52,47 @@ Global Settings public_instances: https://searx.space wiki_url: https://github.com/searxng/searxng/wiki -``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. +.. sidebar:: buildenv -``contact_url``: - Contact ``mailto:`` address or WEB form. + Changing a value tagged by :ref:`buildenv <make buildenv>`, needs to + rebuild instance's environment :ref:`utils/brand.env <make buildenv>`. -``git_url`` and ``git_branch``: +``git_url`` & ``git_branch`` : :ref:`buildenv GIT_URL & GIT_BRANCH <make buildenv>` Changes this, to point to your searx fork (branch). -``docs_url`` - If you host your own documentation, change this URL. +``issue_url`` : + If you host your own issue tracker change this URL. + +``docs_url`` : + If you host your own documentation change this URL. -``wiki_url``: +``public_instances`` : + If you host your own https://searx.space change this URL. + +``wiki_url`` : Link to your wiki (or ``false``) +.. _settings global general: + +``general:`` +------------ + +.. code:: yaml + + general: + debug: false # Debug mode, only for development + instance_name: "searxng" # displayed name + contact_url: false # mailto:contact@example.com + +``debug`` : ``$SEARX_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. + +``contact_url``: + Contact ``mailto:`` address or WEB form. + + +.. _settings global server: ``server:`` ----------- @@ -80,10 +100,10 @@ Global Settings .. code:: yaml server: + base_url: false # set custom base_url (or false) 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 @@ -94,17 +114,24 @@ Global Settings X-Robots-Tag : noindex, nofollow Referrer-Policy : no-referrer -``port`` & ``bind_address``: +.. sidebar:: buildenv + + Changing a value tagged by :ref:`buildenv <make buildenv>`, needs to + rebuild instance's environment :ref:`utils/brand.env <make buildenv>`. + +``base_url`` : :ref:`buildenv SEARX_URL <make buildenv>` + The base URL where searx is deployed. Used to create correct inbound links. + If you change the value, don't forget to rebuild instance's environment + (:ref:`utils/brand.env <make buildenv>`) + +``port`` & ``bind_address``: :ref:`buildenv SEARX_PORT & SEARX_BIND_ADDRESS <make buildenv>` 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`` : +``secret_key`` : ``$SEARX_SECRET`` 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. diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst index 5c9985e8b..c5e1a05e7 100644 --- a/docs/admin/installation-searx.rst +++ b/docs/admin/installation-searx.rst @@ -94,7 +94,7 @@ For a *minimal setup*, configure like shown below – replace ``searx@$(uname .. group-tab:: Use default settings - .. literalinclude:: ../../utils/templates/etc/searx/use_default_settings.yml + .. literalinclude:: ../../utils/templates/etc/searx/settings.yml :language: yaml .. group-tab:: searx/settings.yml diff --git a/docs/build-templates/searx.rst b/docs/build-templates/searx.rst index 33ed9601c..e4d5f06b3 100644 --- a/docs/build-templates/searx.rst +++ b/docs/build-templates/searx.rst @@ -134,7 +134,7 @@ ${fedora_build} .. code-block:: sh $ sudo -H mkdir -p \"$(dirname ${SEARX_SETTINGS_PATH})\" - $ sudo -H cp \"$SEARX_SRC/utils/templates/etc/searx/use_default_settings.yml\" \\ + $ sudo -H cp \"$SEARX_SRC/utils/templates/etc/searx/settings.yml\" \\ \"${SEARX_SETTINGS_PATH}\" .. group-tab:: searx/settings.yml @@ -152,7 +152,6 @@ ${fedora_build} .. 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\" .. END searx config diff --git a/docs/dev/makefile.rst b/docs/dev/makefile.rst index b7472dad7..5bf3c13b2 100644 --- a/docs/dev/makefile.rst +++ b/docs/dev/makefile.rst @@ -81,6 +81,40 @@ the check fails if you edit the requirements listed in If you think, something goes wrong with your ./local environment or you change the :origin:`setup.py` file, you have to call :ref:`make clean`. +.. _make buildenv: + +``make buildenv`` +================= + +Rebuild instance's environment with the modified settings from the +:ref:`settings global brand` and :ref:`settings global server` section of your +:ref:`settings.yml <settings location>`. + +We have all SearXNG setups are centralized in the :ref:`settings.yml` file. +This setup is available as long we are in a *installed instance*. E.g. the +*installed instance* on the server or the *installed developer instance* at +``./local`` (the later one is created by a :ref:`make install <make +install>` or :ref:`make run <make run>`). + +Tasks running outside of an *installed instance*, especially those tasks and +scripts running at (pre-) installation time do not have access to the SearXNG +setup (from a *installed instance*). Those tasks need a *build environment*. + +The ``make buildenv`` target will update the *build environment* in: + +- :origin:`utils/brand.env` + +Tasks running outside of an *installed instance*, need the following settings +from the YAML configuration: + +- ``GIT_URL`` from :ref:`brand.git_url <settings global brand>` +- ``GIT_BRANCH`` from :ref:`brand.git_branch <settings global brand>` + +- ``SEARX_URL`` from :ref:`server.base_url <settings global server>` (aka + ``PUBLIC_URL``) +- ``SEARX_BIND_ADDRESS`` from :ref:`server.bind_address <settings global server>` +- ``SEARX_PORT`` from :ref:`server.port <settings global server>` + .. _make run: ``make run`` |