mirror of https://github.com/searxng/searxng.git
doc: proofread of the all reST sources (no content change)
Normalize reST sources with best practice and KISS in mind. to name a few points: - simplify reST tables - make use of ``literal`` markup for monospace rendering - fix code-blocks for better rendering in HTML - normalize section header markup - limit all lines to a maximum of 79 characters - add option -H to the sudo command used in code blocks - drop useless indentation of lists - ... [1] https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser
parent
0011890043
commit
e9fff4fde6
|
|
@ -1,19 +1,20 @@
|
||||||
.. _adminapi:
|
.. _adminapi:
|
||||||
|
|
||||||
|
==================
|
||||||
Administration API
|
Administration API
|
||||||
------------------
|
==================
|
||||||
|
|
||||||
Get configuration data
|
Get configuration data
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
======================
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: http
|
||||||
|
|
||||||
GET /config
|
GET /config HTTP/1.1
|
||||||
|
|
||||||
Sample response
|
Sample response
|
||||||
```````````````
|
---------------
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: json
|
||||||
|
|
||||||
{
|
{
|
||||||
"autocomplete": "",
|
"autocomplete": "",
|
||||||
|
|
@ -77,16 +78,17 @@ Sample response
|
||||||
"safe_search": 0
|
"safe_search": 0
|
||||||
}
|
}
|
||||||
|
|
||||||
Embed search bar
|
|
||||||
----------------
|
|
||||||
|
|
||||||
The search bar can be embedded into websites. Just paste the example into the HTML of the site.
|
Embed search bar
|
||||||
URL of the searx instance and values are customizable.
|
================
|
||||||
|
|
||||||
|
The search bar can be embedded into websites. Just paste the example into the
|
||||||
|
HTML of the site. URL of the searx instance and values are customizable.
|
||||||
|
|
||||||
.. code:: html
|
.. code:: html
|
||||||
|
|
||||||
<form method="post" action="https://searx.me/">
|
<form method="post" action="https://searx.me/">
|
||||||
<!-- search query --> <input type="text" name="q" />
|
<!-- search --> <input type="text" name="q" />
|
||||||
<!-- categories --> <input type="hidden" name="categories" value="general,social media" />
|
<!-- categories --> <input type="hidden" name="categories" value="general,social media" />
|
||||||
<!-- language --> <input type="hidden" name="lang" value="all" />
|
<!-- language --> <input type="hidden" name="lang" value="all" />
|
||||||
<!-- locale --> <input type="hidden" name="locale" value="en" />
|
<!-- locale --> <input type="hidden" name="locale" value="en" />
|
||||||
|
|
|
||||||
|
|
@ -1,25 +1,26 @@
|
||||||
|
==========================
|
||||||
How to protect an instance
|
How to protect an instance
|
||||||
==========================
|
==========================
|
||||||
|
|
||||||
Searx depens on external search services. To avoid the abuse of these services it is advised to limit the number of requests processed by searx.
|
Searx depens on external search services. To avoid the abuse of these services
|
||||||
|
it is advised to limit the number of requests processed by searx.
|
||||||
|
|
||||||
|
An application firewall, ``filtron`` solves exactly this problem. Information
|
||||||
|
on how to install it can be found at the `project page of filtron
|
||||||
|
<https://github.com/asciimoo/filtron>`__.
|
||||||
|
|
||||||
An application firewall, ``filtron`` solves exactly this problem. Information on how to install it can be found at the `project page of filtron <https://github.com/asciimoo/filtron>`__.
|
|
||||||
|
|
||||||
Sample configuration of filtron
|
Sample configuration of filtron
|
||||||
-------------------------------
|
===============================
|
||||||
|
|
||||||
An example configuration can be find below. This configuration limits the access of
|
An example configuration can be find below. This configuration limits the access
|
||||||
|
of:
|
||||||
* scripts or applications (roboagent limit)
|
|
||||||
|
|
||||||
* webcrawlers (botlimit)
|
|
||||||
|
|
||||||
* IPs which send too many requests (IP limit)
|
|
||||||
|
|
||||||
* too many json, csv, etc. requests (rss/json limit)
|
|
||||||
|
|
||||||
* the same UserAgent of if too many requests (useragent limit)
|
|
||||||
|
|
||||||
|
- scripts or applications (roboagent limit)
|
||||||
|
- webcrawlers (botlimit)
|
||||||
|
- IPs which send too many requests (IP limit)
|
||||||
|
- too many json, csv, etc. requests (rss/json limit)
|
||||||
|
- the same UserAgent of if too many requests (useragent limit)
|
||||||
|
|
||||||
.. code:: json
|
.. code:: json
|
||||||
|
|
||||||
|
|
@ -120,15 +121,16 @@ An example configuration can be find below. This configuration limits the access
|
||||||
|
|
||||||
|
|
||||||
Route request through filtron
|
Route request through filtron
|
||||||
-----------------------------
|
=============================
|
||||||
|
|
||||||
Filtron can be started using the following command:
|
Filtron can be started using the following command:
|
||||||
|
|
||||||
.. code:: bash
|
.. code:: sh
|
||||||
|
|
||||||
$ filtron -rules rules.json
|
$ filtron -rules rules.json
|
||||||
|
|
||||||
It listens on 127.0.0.1:4004 and forwards filtered requests to 127.0.0.1:8888 by default.
|
It listens on ``127.0.0.1:4004`` and forwards filtered requests to
|
||||||
|
``127.0.0.1:8888`` by default.
|
||||||
|
|
||||||
Use it along with ``nginx`` with the following example configuration.
|
Use it along with ``nginx`` with the following example configuration.
|
||||||
|
|
||||||
|
|
@ -142,4 +144,5 @@ Use it along with ``nginx`` with the following example configuration.
|
||||||
proxy_pass http://127.0.0.1:4004/;
|
proxy_pass http://127.0.0.1:4004/;
|
||||||
}
|
}
|
||||||
|
|
||||||
Requests are coming from port 4004 going through filtron and then forwarded to port 8888 where a searx is being run.
|
Requests are coming from port 4004 going through filtron and then forwarded to
|
||||||
|
port 8888 where a searx is being run.
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,26 @@
|
||||||
|
=========================
|
||||||
How to setup result proxy
|
How to setup result proxy
|
||||||
=========================
|
=========================
|
||||||
|
|
||||||
By default searx can only act as an image proxy for result images,
|
.. _morty: https://github.com/asciimoo/morty
|
||||||
but it is possible to proxify all the result URLs with an external service,
|
.. _morty's README: https://github.com/asciimoo/morty
|
||||||
`morty <https://github.com/asciimoo/morty>`__.
|
|
||||||
|
|
||||||
To use this feature, morty has to be installed and activated in searx's ``settings.yml``.
|
By default searx can only act as an image proxy for result images, but it is
|
||||||
|
possible to proxify all the result URLs with an external service, morty_.
|
||||||
|
|
||||||
|
To use this feature, morty has to be installed and activated in searx's
|
||||||
|
``settings.yml``.
|
||||||
|
|
||||||
Add the following snippet to your ``settings.yml`` and restart searx:
|
Add the following snippet to your ``settings.yml`` and restart searx:
|
||||||
|
|
||||||
|
|
||||||
.. code:: yaml
|
.. code:: yaml
|
||||||
|
|
||||||
result_proxy:
|
result_proxy:
|
||||||
url : http://127.0.0.1:3000/
|
url : http://127.0.0.1:3000/
|
||||||
key : your_morty_proxy_key
|
key : your_morty_proxy_key
|
||||||
|
|
||||||
``url`` is the address of the running morty service
|
``url``
|
||||||
|
Is the address of the running morty service.
|
||||||
|
|
||||||
``key`` is an optional argument, see `morty's README <https://github.com/asciimoo/morty>`__ for more information.
|
``key``
|
||||||
|
Is an optional argument, see `morty's README`_ for more information.
|
||||||
|
|
|
||||||
|
|
@ -1,42 +1,43 @@
|
||||||
Searx admin interface: manage your instance from your browser
|
=============================================================
|
||||||
|
Searx admin interface
|
||||||
=============================================================
|
=============================================================
|
||||||
|
|
||||||
One of the biggest advantages of searx is being extremely customizable. But at first it can be daunting to newcomers.
|
.. _searx-admin: https://github.com/kvch/searx-admin#searx-admin
|
||||||
A barrier of taking advantage of this feature is our ugly settings file which is sometimes hard to understand and edit.
|
.. _NLnet Foundation: https://nlnet.nl/
|
||||||
|
|
||||||
To make self-hosting searx more accessible a new tool is introduced, called ``searx-admin``.
|
manage your instance from your browser
|
||||||
It is a web application which is capable of managing your instance and manipulating its settings via a web UI.
|
|
||||||
It aims to replace editing of ``settings.yml`` for less experienced administrators or people
|
.. sidebar:: Installation
|
||||||
who prefer graphical admin interfaces.
|
|
||||||
|
Installation guide can be found in the repository of searx-admin_.
|
||||||
|
|
||||||
|
One of the biggest advantages of searx is being extremely customizable. But at
|
||||||
|
first it can be daunting to newcomers. A barrier of taking advantage of this
|
||||||
|
feature is our ugly settings file which is sometimes hard to understand and
|
||||||
|
edit.
|
||||||
|
|
||||||
|
To make self-hosting searx more accessible a new tool is introduced, called
|
||||||
|
``searx-admin``. It is a web application which is capable of managing your
|
||||||
|
instance and manipulating its settings via a web UI. It aims to replace editing
|
||||||
|
of ``settings.yml`` for less experienced administrators or people who prefer
|
||||||
|
graphical admin interfaces.
|
||||||
|
|
||||||
.. figure:: searx-admin-engines.png
|
.. figure:: searx-admin-engines.png
|
||||||
:scale: 50 %
|
|
||||||
:alt: Screenshot of engine list
|
:alt: Screenshot of engine list
|
||||||
:align: center
|
|
||||||
:figclass: align-center
|
|
||||||
|
|
||||||
Configuration page of engines
|
Configuration page of engines
|
||||||
|
|
||||||
|
Since ``searx-admin`` acts as a supervisor for searx, we have decided to
|
||||||
|
implement it as a standalone tool instead of part of searx. Another reason for
|
||||||
|
making it a standalone tool is that the codebase and dependencies of searx
|
||||||
|
should not grow because of a fully optional feature, which does not affect
|
||||||
|
existing instances.
|
||||||
|
|
||||||
Since ``searx-admin`` acts as a supervisor for searx, we have decided to implement it
|
|
||||||
as a standalone tool instead of part of searx. Another reason for making it a standalone
|
|
||||||
tool is that the codebase and dependencies of searx should not grow because of a fully optional feature,
|
|
||||||
which does not affect existing instances.
|
|
||||||
|
|
||||||
|
|
||||||
Installation
|
|
||||||
------------
|
|
||||||
|
|
||||||
Installation guide can be found in the repository of searx-admin:
|
|
||||||
https://github.com/kvch/searx-admin#installation--usage
|
|
||||||
|
|
||||||
Acknowledgements
|
Acknowledgements
|
||||||
----------------
|
================
|
||||||
|
|
||||||
This development was sponsored by `NLnet Foundation`_.
|
This development was sponsored by `NLnet Foundation`_.
|
||||||
|
|
||||||
.. _NLnet Foundation: https://nlnet.nl/
|
|
||||||
|
|
||||||
|
|
||||||
| Happy hacking.
|
| Happy hacking.
|
||||||
| kvch // 2017.08.22 21:25
|
| kvch // 2017.08.22 21:25
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,4 @@
|
||||||
|
====
|
||||||
Blog
|
Blog
|
||||||
====
|
====
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,12 +1,17 @@
|
||||||
|
===============================
|
||||||
Preparation for offline engines
|
Preparation for offline engines
|
||||||
===============================
|
===============================
|
||||||
|
|
||||||
Offline engines
|
Offline engines
|
||||||
---------------
|
===============
|
||||||
|
|
||||||
To extend the functionality of searx, 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.
|
To extend the functionality of searx, 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 as online engines, by adding those to the `engines` list of `settings.yml`. Thus, searx finds the engine file and imports it.
|
Offline engines can be configured as online engines, by adding those to the
|
||||||
|
`engines` list of :origin:`settings.yml <searx/settings.yml>`. Thus, searx
|
||||||
|
finds the engine file and imports it.
|
||||||
|
|
||||||
Example skeleton for the new engines:
|
Example skeleton for the new engines:
|
||||||
|
|
||||||
|
|
@ -38,21 +43,28 @@ Example skeleton for the new engines:
|
||||||
|
|
||||||
|
|
||||||
Development progress
|
Development progress
|
||||||
--------------------
|
====================
|
||||||
|
|
||||||
First, a proposal has been created as a Github issue. Then it was moved to the wiki as a design document. You can read it here: :wiki:`Offline-engines`.
|
First, a proposal has been created as a Github issue. Then it was moved to the
|
||||||
|
wiki as a design document. You can read it here: :wiki:`Offline-engines`.
|
||||||
|
|
||||||
In this development step, searx core was prepared to accept and perform offline searches. Offline search requests are scheduled together with regular offline requests.
|
In this development step, searx core was prepared to accept and perform offline
|
||||||
|
searches. Offline search requests are scheduled together with regular offline
|
||||||
|
requests.
|
||||||
|
|
||||||
As offline searches can return arbitrary results depending on the engine, the current result templates were insufficient to present such results. Thus, a new template is introduced which is caplable of presenting arbitrary key value pairs as a table. You can check out the pull request for more details: https://github.com/asciimoo/searx/pull/1700
|
As offline searches can return arbitrary results depending on the engine, the
|
||||||
|
current result templates were insufficient to present such results. Thus, a new
|
||||||
|
template is introduced which is caplable of presenting arbitrary key value pairs
|
||||||
|
as a table. You can check out the pull request for more details see
|
||||||
|
:pull:`1700`.
|
||||||
|
|
||||||
Next steps
|
Next steps
|
||||||
----------
|
==========
|
||||||
|
|
||||||
Today, it is possible to create/run an offline engine. However, it is going to be publicly available for everyone who knows the searx instance. So the next step is to introduce token based access for engines. This way administrators are able to limit the access to private engines.
|
Today, it is possible to create/run an offline engine. However, it is going to be publicly available for everyone who knows the searx instance. So the next step is to introduce token based access for engines. This way administrators are able to limit the access to private engines.
|
||||||
|
|
||||||
Acknowledgement
|
Acknowledgement
|
||||||
---------------
|
===============
|
||||||
|
|
||||||
This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
|
This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,17 @@
|
||||||
|
============================
|
||||||
Introducing Python 3 support
|
Introducing Python 3 support
|
||||||
===========================
|
============================
|
||||||
|
|
||||||
As most operation systems are coming with Python3 installed by default. So it is time for searx to support Python3. But don't worry support of Python2.7 won't be dropped.
|
.. _Python 2.7 clock: https://pythonclock.org/
|
||||||
|
|
||||||
|
.. sidebar:: Python 2.7 to 3 upgrade
|
||||||
|
|
||||||
|
This chapter exists of historical reasons. Python 2.7 release schedule ends
|
||||||
|
(`Python 2.7 clock`_) after 11 years Python 3 exists
|
||||||
|
|
||||||
|
As most operation systems are coming with Python3 installed by default. So it is
|
||||||
|
time for searx to support Python3. But don't worry support of Python2.7 won't be
|
||||||
|
dropped.
|
||||||
|
|
||||||
.. image:: searxpy3.png
|
.. image:: searxpy3.png
|
||||||
:scale: 50 %
|
:scale: 50 %
|
||||||
|
|
@ -10,12 +20,13 @@ As most operation systems are coming with Python3 installed by default. So it is
|
||||||
|
|
||||||
|
|
||||||
How to run searx using Python 3
|
How to run searx using Python 3
|
||||||
------------------------------
|
===============================
|
||||||
|
|
||||||
Please make sure that you run at least Python 3.5.
|
Please make sure that you run at least Python 3.5.
|
||||||
|
|
||||||
To run searx, first a Python3 virtualenv should be created. After entering the virtualenv,
|
To run searx, first a Python3 virtualenv should be created. After entering the
|
||||||
dependencies must be installed. Then run searx with python3 instead of the usual python command.
|
virtualenv, dependencies must be installed. Then run searx with python3 instead
|
||||||
|
of the usual python command.
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: sh
|
||||||
|
|
||||||
|
|
@ -25,25 +36,28 @@ dependencies must be installed. Then run searx with python3 instead of the usual
|
||||||
python3 searx/webapp.py
|
python3 searx/webapp.py
|
||||||
|
|
||||||
|
|
||||||
If you want to run searx using Python2.7, you don't have to do anything differently as before.
|
If you want to run searx using Python2.7, you don't have to do anything
|
||||||
|
differently as before.
|
||||||
|
|
||||||
Fun facts
|
Fun facts
|
||||||
---------
|
=========
|
||||||
|
|
||||||
- 115 files were changed when implementing the support for both Python versions.
|
- 115 files were changed when implementing the support for both Python versions.
|
||||||
|
|
||||||
- All of the dependencies was compatible except for the robotframework used for browser tests. Thus, these tests were migrated to splinter. So from now on both versions are being tested on Travis and can be tested locally.
|
- All of the dependencies was compatible except for the robotframework used for
|
||||||
|
browser tests. Thus, these tests were migrated to splinter. So from now on
|
||||||
|
both versions are being tested on Travis and can be tested locally.
|
||||||
|
|
||||||
If you found bugs...
|
If you found bugs
|
||||||
--------------------
|
=================
|
||||||
|
|
||||||
...please open an issue on `GitHub`_. Make sure that you mention your Python version in your issue,
|
Please open an issue on `GitHub`_. Make sure that you mention your Python
|
||||||
so we can investigate it properly.
|
version in your issue, so we can investigate it properly.
|
||||||
|
|
||||||
.. _GitHub: https://github.com/asciimoo/searx/issues
|
.. _GitHub: https://github.com/asciimoo/searx/issues
|
||||||
|
|
||||||
Acknowledgement
|
Acknowledgment
|
||||||
---------------
|
==============
|
||||||
|
|
||||||
This development was sponsored by `NLnet Foundation`_.
|
This development was sponsored by `NLnet Foundation`_.
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -20,12 +20,16 @@ master_doc = "index"
|
||||||
source_suffix = '.rst'
|
source_suffix = '.rst'
|
||||||
|
|
||||||
# usage:: lorem :patch:`f373169` ipsum
|
# usage:: lorem :patch:`f373169` ipsum
|
||||||
|
|
||||||
extlinks = {}
|
extlinks = {}
|
||||||
|
|
||||||
|
# upstream links
|
||||||
|
extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ')
|
||||||
|
extlinks['pull'] = ('https://github.com/asciimoo/searx/pull/%s', 'PR ')
|
||||||
|
|
||||||
|
# links to custom brand
|
||||||
extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
|
extlinks['origin'] = (GIT_URL + '/blob/master/%s', 'git://')
|
||||||
extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
|
extlinks['patch'] = (GIT_URL + '/commit/%s', '#')
|
||||||
extlinks['search'] = (SEARX_URL + '/%s', '#')
|
extlinks['search'] = (SEARX_URL + '/%s', '#')
|
||||||
extlinks['wiki'] = ('https://github.com/asciimoo/searx/wiki/%s', ' ')
|
|
||||||
|
|
||||||
extensions = [
|
extensions = [
|
||||||
'sphinx.ext.extlinks',
|
'sphinx.ext.extlinks',
|
||||||
|
|
|
||||||
|
|
@ -1,66 +1,68 @@
|
||||||
|
=================
|
||||||
How to contribute
|
How to contribute
|
||||||
-----------------
|
=================
|
||||||
|
|
||||||
Prime directives: Privacy, Hackability
|
Prime directives: Privacy, Hackability
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
======================================
|
||||||
|
|
||||||
Searx has two prime directives, privacy-by-design and hackability. The
|
Searx has two prime directives, **privacy-by-design and hackability** . The
|
||||||
hackability comes in three levels:
|
hackability comes in three levels:
|
||||||
|
|
||||||
- support of search engines
|
- support of search engines
|
||||||
- plugins to alter search behaviour
|
- plugins to alter search behaviour
|
||||||
- hacking searx itself
|
- hacking searx itself
|
||||||
|
|
||||||
Note the lack of "world domination" among the directives.
|
Note the lack of "world domination" among the directives. Searx has no
|
||||||
Searx has no intention of wide mass-adoption, rounded
|
intention of wide mass-adoption, rounded corners, etc. The prime directive
|
||||||
corners, etc. The prime directive "privacy" deserves a separate
|
"privacy" deserves a separate chapter, as it's quite uncommon unfortunately.
|
||||||
chapter, as it's quite uncommon unfortunately.
|
|
||||||
|
|
||||||
Privacy-by-design
|
Privacy-by-design
|
||||||
^^^^^^^^^^^^^^^^^
|
-----------------
|
||||||
|
|
||||||
Searx was born out of the need for a privacy-respecting search tool
|
Searx was born out of the need for a **privacy-respecting** search tool which
|
||||||
which can be extended easily to maximize both its search and its
|
can be extended easily to maximize both, its search and its privacy protecting
|
||||||
privacy protecting capabilities.
|
capabilities.
|
||||||
|
|
||||||
A few widely used features work differently or turned off by default or not implemented
|
A few widely used features work differently or turned off by default or not
|
||||||
at all as a consequence of privacy-by-design.
|
implemented at all **as a consequence of privacy-by-design**.
|
||||||
|
|
||||||
If a feature reduces the privacy preserving aspects of searx, it
|
If a feature reduces the privacy preserving aspects of searx, it should be
|
||||||
should be switched off by default or should not implemented at all.
|
switched off by default or should not implemented at all. There are plenty of
|
||||||
There are plenty of search engines already providing such features.
|
search engines already providing such features. If a feature reduces the
|
||||||
If a feature reduces the protection of searx, users must be
|
protection of searx, users must be informed about the effect of choosing to
|
||||||
informed about the effect of choosing to enable it. Features
|
enable it. Features that protect privacy but differ from the expectations of
|
||||||
that protect privacy but differ from the expectations of the
|
the user should also be explained.
|
||||||
user should also be explained.
|
|
||||||
|
|
||||||
Also, if you think that something works weird with searx,
|
Also, if you think that something works weird with searx, it's might be because
|
||||||
it's might be because of the tool you use is designed in a way to interfere with
|
of the tool you use is designed in a way to interfere with the privacy respect.
|
||||||
the privacy respect. Submitting a bugreport to the vendor of the tool that
|
Submitting a bugreport to the vendor of the tool that misbehaves might be a good
|
||||||
misbehaves might be a good feedback to reconsider the disrespect to
|
feedback to reconsider the disrespect to its customers (e.g. ``GET`` vs ``POST``
|
||||||
its customers (e.g. GET vs POST requests in various browsers).
|
requests in various browsers).
|
||||||
|
|
||||||
Remember the other prime directive of searx is to be hackable, so if the
|
Remember the other prime directive of searx is to be hackable, so if the above
|
||||||
above privacy concerns do not fancy you, simply fork it.
|
privacy concerns do not fancy you, simply fork it.
|
||||||
|
|
||||||
Happy hacking.
|
*Happy hacking.*
|
||||||
|
|
||||||
Code
|
Code
|
||||||
~~~~
|
====
|
||||||
|
|
||||||
|
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
|
||||||
|
|
||||||
|
|
||||||
In order to submit a patch, please follow the steps below:
|
In order to submit a patch, please follow the steps below:
|
||||||
|
|
||||||
- Follow coding conventions.
|
- Follow coding conventions.
|
||||||
|
|
||||||
- PEP8 standards apply, except the convention of line length
|
- PEP8_ standards apply, except the convention of line length
|
||||||
|
|
||||||
- Maximum line length is 120 characters
|
- Maximum line length is 120 characters
|
||||||
|
|
||||||
- Check if your code breaks existing tests. If so, update the tests or fix your code.
|
- Check if your code breaks existing tests. If so, update the tests or fix your
|
||||||
|
code.
|
||||||
|
|
||||||
- If your code can be unit-tested, add unit tests.
|
- If your code can be unit-tested, add unit tests.
|
||||||
|
|
||||||
- Add yourself to the AUTHORS file.
|
- Add yourself to the :origin:`AUTHORS.rst` file.
|
||||||
|
|
||||||
- Create a pull request.
|
- Create a pull request.
|
||||||
|
|
||||||
|
|
@ -68,31 +70,20 @@ For more help on getting started with searx development, see :ref:`devquickstart
|
||||||
|
|
||||||
|
|
||||||
Translation
|
Translation
|
||||||
~~~~~~~~~~~
|
===========
|
||||||
|
|
||||||
Translation currently takes place on
|
Translation currently takes place on :ref:`transifex <translation>`.
|
||||||
`transifex <https://transifex.com/projects/p/searx>`__.
|
|
||||||
|
.. caution::
|
||||||
|
|
||||||
|
Please, do not update translation files in the repo.
|
||||||
|
|
||||||
**Please, do not update translation files in the repo.**
|
|
||||||
|
|
||||||
Documentation
|
Documentation
|
||||||
~~~~~~~~~~~~~
|
=============
|
||||||
|
|
||||||
The documentation is built using Sphinx. So in order to be able to generate the required
|
.. admonition:: ToDo
|
||||||
files, you have to install it on your system. (It can be installed easily using pip.)
|
|
||||||
|
|
||||||
1. Checkout the gh-pages branch.
|
docs are no longer in gh-branch
|
||||||
|
|
||||||
2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder.
|
Update this chapter and document the /docs workflow!!
|
||||||
|
|
||||||
3. Build the documentation using Sphinx.
|
|
||||||
|
|
||||||
4. Add the updated and created files of these extension:
|
|
||||||
|
|
||||||
- .rst
|
|
||||||
|
|
||||||
- .html
|
|
||||||
|
|
||||||
- .txt
|
|
||||||
|
|
||||||
6. Create a pull request.
|
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,25 @@
|
||||||
|
|
||||||
|
.. _engines-dev:
|
||||||
|
|
||||||
|
===============
|
||||||
Engine overview
|
Engine overview
|
||||||
===============
|
===============
|
||||||
|
|
||||||
|
.. _metasearch-engine: https://en.wikipedia.org/wiki/Metasearch_engine
|
||||||
|
|
||||||
searx is a `metasearch-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__,
|
searx is a metasearch-engine_, so it uses different search engines to provide
|
||||||
so it uses different search engines to provide better results.
|
better results.
|
||||||
|
|
||||||
Because there is no general search API which could be used for every
|
|
||||||
search engine, an adapter has to be built between searx and the
|
|
||||||
external search engines. Adapters are stored under the folder
|
|
||||||
:origin:`searx/engines`.
|
|
||||||
|
|
||||||
|
Because there is no general search API which could be used for every search
|
||||||
|
engine, an adapter has to be built between searx and the external search
|
||||||
|
engines. Adapters are stored under the folder :origin:`searx/engines`.
|
||||||
|
|
||||||
.. contents::
|
.. contents::
|
||||||
:depth: 3
|
:depth: 3
|
||||||
|
:backlinks: entry
|
||||||
|
|
||||||
general engine configuration
|
general engine configuration
|
||||||
----------------------------
|
============================
|
||||||
|
|
||||||
It is required to tell searx the type of results the engine provides. The
|
It is required to tell searx the type of results the engine provides. The
|
||||||
arguments can be set in the engine file or in the settings file
|
arguments can be set in the engine file or in the settings file
|
||||||
|
|
@ -27,62 +31,56 @@ settings. However, the standard way is the following:
|
||||||
|
|
||||||
|
|
||||||
engine file
|
engine file
|
||||||
~~~~~~~~~~~
|
-----------
|
||||||
|
|
||||||
|
======================= =========== ===========================================
|
||||||
|
argument type information
|
||||||
|
======================= =========== ===========================================
|
||||||
|
categories list pages, in which the engine is working
|
||||||
|
paging boolean support multible pages
|
||||||
|
language_support boolean support language choosing
|
||||||
|
time_range_support boolean support search time range
|
||||||
|
offline boolean engine runs offline
|
||||||
|
======================= =========== ===========================================
|
||||||
|
|
||||||
+----------------------+-----------+-----------------------------------------+
|
|
||||||
| argument | type | information |
|
|
||||||
+======================+===========+=========================================+
|
|
||||||
| categories | list | pages, in which the engine is working |
|
|
||||||
+----------------------+-----------+-----------------------------------------+
|
|
||||||
| paging | boolean | support multible pages |
|
|
||||||
+----------------------+-----------+-----------------------------------------+
|
|
||||||
| language\_support | boolean | support language choosing |
|
|
||||||
+----------------------+-----------+-----------------------------------------+
|
|
||||||
| time\_range\_support | boolean | support search time range |
|
|
||||||
+----------------------+-----------+-----------------------------------------+
|
|
||||||
| offline | boolean | engine runs offline |
|
|
||||||
+----------------------+-----------+-----------------------------------------+
|
|
||||||
|
|
||||||
settings.yml
|
settings.yml
|
||||||
~~~~~~~~~~~~
|
------------
|
||||||
|
|
||||||
|
======================= =========== ===========================================
|
||||||
|
argument type information
|
||||||
|
======================= =========== ===========================================
|
||||||
|
name string name of search-engine
|
||||||
|
engine string name of searx-engine
|
||||||
|
(filename without ``.py``)
|
||||||
|
shortcut string shortcut of search-engine
|
||||||
|
timeout string specific timeout for search-engine
|
||||||
|
======================= =========== ===========================================
|
||||||
|
|
||||||
+------------+----------+-----------------------------------------------+
|
|
||||||
| argument | type | information |
|
|
||||||
+============+==========+===============================================+
|
|
||||||
| name | string | name of search-engine |
|
|
||||||
+------------+----------+-----------------------------------------------+
|
|
||||||
| engine | string | name of searx-engine (filename without .py) |
|
|
||||||
+------------+----------+-----------------------------------------------+
|
|
||||||
| shortcut | string | shortcut of search-engine |
|
|
||||||
+------------+----------+-----------------------------------------------+
|
|
||||||
| timeout | string | specific timeout for search-engine |
|
|
||||||
+------------+----------+-----------------------------------------------+
|
|
||||||
|
|
||||||
overrides
|
overrides
|
||||||
~~~~~~~~~
|
---------
|
||||||
|
|
||||||
A few of the options have default values in the engine, but are
|
A few of the options have default values in the engine, but are often
|
||||||
often overwritten by the settings. If ``None`` is assigned to an option
|
overwritten by the settings. If ``None`` is assigned to an option in the engine
|
||||||
in the engine file, it has to be redefined in the settings,
|
file, it has to be redefined in the settings, otherwise searx will not start
|
||||||
otherwise searx will not start with that engine.
|
with that engine.
|
||||||
|
|
||||||
The naming of overrides is arbitrary. But the recommended
|
The naming of overrides is arbitrary. But the recommended overrides are the
|
||||||
overrides are the following:
|
following:
|
||||||
|
|
||||||
+-----------------------+----------+----------------------------------------------------------------+
|
======================= =========== ===========================================
|
||||||
| argument | type | information |
|
argument type information
|
||||||
+=======================+==========+================================================================+
|
======================= =========== ===========================================
|
||||||
| base\_url | string | base-url, can be overwritten to use same engine on other URL |
|
base_url string base-url, can be overwritten to use same
|
||||||
+-----------------------+----------+----------------------------------------------------------------+
|
engine on other URL
|
||||||
| number\_of\_results | int | maximum number of results per request |
|
number_of_results int maximum number of results per request
|
||||||
+-----------------------+----------+----------------------------------------------------------------+
|
language string ISO code of language and country like en_US
|
||||||
| language | string | ISO code of language and country like en\_US |
|
api_key string api-key if required by engine
|
||||||
+-----------------------+----------+----------------------------------------------------------------+
|
======================= =========== ===========================================
|
||||||
| api\_key | string | api-key if required by engine |
|
|
||||||
+-----------------------+----------+----------------------------------------------------------------+
|
|
||||||
|
|
||||||
example code
|
example code
|
||||||
~~~~~~~~~~~~
|
------------
|
||||||
|
|
||||||
.. code:: python
|
.. code:: python
|
||||||
|
|
||||||
|
|
@ -91,69 +89,56 @@ example code
|
||||||
paging = True
|
paging = True
|
||||||
language_support = True
|
language_support = True
|
||||||
|
|
||||||
making a request
|
|
||||||
----------------
|
|
||||||
|
|
||||||
To perform a search an URL have to be specified. In addition to
|
making a request
|
||||||
specifying an URL, arguments can be passed to the query.
|
================
|
||||||
|
|
||||||
|
To perform a search an URL have to be specified. In addition to specifying an
|
||||||
|
URL, arguments can be passed to the query.
|
||||||
|
|
||||||
passed arguments
|
passed arguments
|
||||||
~~~~~~~~~~~~~~~~
|
----------------
|
||||||
|
|
||||||
These arguments can be used to construct the search query. Furthermore,
|
These arguments can be used to construct the search query. Furthermore,
|
||||||
parameters with default value can be redefined for special purposes.
|
parameters with default value can be redefined for special purposes.
|
||||||
|
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
====================== ============ ========================================================================
|
||||||
| argument | type | default-value, information |
|
argument type default-value, information
|
||||||
+======================+============+========================================================================+
|
====================== ============ ========================================================================
|
||||||
| url | string | ``''`` |
|
url string ``''``
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
method string ``'GET'``
|
||||||
| method | string | ``'GET'`` |
|
headers set ``{}``
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
data set ``{}``
|
||||||
| headers | set | ``{}`` |
|
cookies set ``{}``
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
verify boolean ``True``
|
||||||
| data | set | ``{}`` |
|
headers.User-Agent string a random User-Agent
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
category string current category, like ``'general'``
|
||||||
| cookies | set | ``{}`` |
|
started datetime current date-time
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
pageno int current pagenumber
|
||||||
| verify | boolean | ``True`` |
|
language string specific language code like ``'en_US'``, or ``'all'`` if unspecified
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
====================== ============ ========================================================================
|
||||||
| headers.User-Agent | string | a random User-Agent |
|
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
|
||||||
| category | string | current category, like ``'general'`` |
|
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
|
||||||
| started | datetime | current date-time |
|
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
|
||||||
| pageno | int | current pagenumber |
|
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
|
||||||
| language | string | specific language code like ``'en_US'``, or ``'all'`` if unspecified |
|
|
||||||
+----------------------+------------+------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
parsed arguments
|
parsed arguments
|
||||||
~~~~~~~~~~~~~~~~
|
----------------
|
||||||
|
|
||||||
The function ``def request(query, params):`` always returns the
|
The function ``def request(query, params):`` always returns the ``params``
|
||||||
``params`` variable. Inside searx, the following paramters can be
|
variable. Inside searx, the following paramters can be used to specify a search
|
||||||
used to specify a search request:
|
request:
|
||||||
|
|
||||||
|
============ =========== =========================================================
|
||||||
|
argument type information
|
||||||
|
============ =========== =========================================================
|
||||||
|
url string requested url
|
||||||
|
method string HTTP request method
|
||||||
|
headers set HTTP header information
|
||||||
|
data set HTTP data information (parsed if ``method != 'GET'``)
|
||||||
|
cookies set HTTP cookies
|
||||||
|
verify boolean Performing SSL-Validity check
|
||||||
|
============ =========== =========================================================
|
||||||
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
| argument | type | information |
|
|
||||||
+============+===========+=========================================================+
|
|
||||||
| url | string | requested url |
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
| method | string | HTTP request method |
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
| headers | set | HTTP header information |
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
| data | set | HTTP data information (parsed if ``method != 'GET'``) |
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
| cookies | set | HTTP cookies |
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
| verify | boolean | Performing SSL-Validity check |
|
|
||||||
+------------+-----------+---------------------------------------------------------+
|
|
||||||
|
|
||||||
example code
|
example code
|
||||||
~~~~~~~~~~~~
|
------------
|
||||||
|
|
||||||
.. code:: python
|
.. code:: python
|
||||||
|
|
||||||
|
|
@ -171,144 +156,110 @@ example code
|
||||||
|
|
||||||
return params
|
return params
|
||||||
|
|
||||||
|
|
||||||
returned results
|
returned results
|
||||||
----------------
|
================
|
||||||
|
|
||||||
Searx is able to return results of different media-types.
|
Searx is able to return results of different media-types. Currently the
|
||||||
Currently the following media-types are supported:
|
following media-types are supported:
|
||||||
|
|
||||||
- default
|
- default_
|
||||||
- images
|
- images_
|
||||||
- videos
|
- videos_
|
||||||
- torrent
|
- torrent_
|
||||||
- map
|
- map_
|
||||||
|
|
||||||
To set another media-type as default, the parameter
|
To set another media-type as default, the parameter ``template`` must be set to
|
||||||
``template`` must be set to the desired type.
|
the desired type.
|
||||||
|
|
||||||
default
|
default
|
||||||
~~~~~~~
|
-------
|
||||||
|
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------+
|
========================= =====================================================
|
||||||
| result-parameter | information |
|
result-parameter information
|
||||||
+====================+===============================================================================================================+
|
========================= =====================================================
|
||||||
| url | string, url of the result |
|
url string, url of the result
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------+
|
title string, title of the result
|
||||||
| title | string, title of the result |
|
content string, general result-text
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------+
|
publishedDate :py:class:`datetime.datetime`, time of publish
|
||||||
| content | string, general result-text |
|
========================= =====================================================
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------+
|
|
||||||
| publishedDate | :py:class:`datetime.datetime`, time of publish |
|
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
images
|
images
|
||||||
~~~~~~
|
------
|
||||||
|
|
||||||
to use this template, the parameter
|
To use this template, the parameter:
|
||||||
|
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
========================= =====================================================
|
||||||
| result-parameter | information |
|
result-parameter information
|
||||||
+====================+=======================================================================================================================================+
|
========================= =====================================================
|
||||||
| template | is set to ``images.html`` |
|
template is set to ``images.html``
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
url string, url to the result site
|
||||||
| url | string, url to the result site |
|
title string, title of the result *(partly implemented)*
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
content *(partly implemented)*
|
||||||
| title | string, title of the result *(partly implemented)* |
|
publishedDate :py:class:`datetime.datetime`,
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
time of publish *(partly implemented)*
|
||||||
| content | *(partly implemented)* |
|
img\_src string, url to the result image
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
thumbnail\_src string, url to a small-preview image
|
||||||
| publishedDate | :py:class:`datetime.datetime`, time of publish *(partly implemented)* |
|
========================= =====================================================
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
| img\_src | string, url to the result image |
|
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
| thumbnail\_src | string, url to a small-preview image |
|
|
||||||
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
videos
|
videos
|
||||||
~~~~~~
|
------
|
||||||
|
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
========================= =====================================================
|
||||||
| result-parameter | information |
|
result-parameter information
|
||||||
+====================+==============================================================================================================+
|
========================= =====================================================
|
||||||
| template | is set to ``videos.html`` |
|
template is set to ``videos.html``
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
url string, url of the result
|
||||||
| url | string, url of the result |
|
title string, title of the result
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
content *(not implemented yet)*
|
||||||
| title | string, title of the result |
|
publishedDate :py:class:`datetime.datetime`, time of publish
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
thumbnail string, url to a small-preview image
|
||||||
| content | *(not implemented yet)* |
|
========================= =====================================================
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| publishedDate | :py:class:`datetime.datetime`, time of publish |
|
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| thumbnail | string, url to a small-preview image |
|
|
||||||
+--------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
torrent
|
torrent
|
||||||
~~~~~~~
|
-------
|
||||||
|
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
.. _magnetlink: https://en.wikipedia.org/wiki/Magnet_URI_scheme
|
||||||
| result-parameter | information |
|
|
||||||
+==================+=======================================================================================================================================+
|
========================= =====================================================
|
||||||
| template | is set to ``torrent.html`` |
|
result-parameter information
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
========================= =====================================================
|
||||||
| url | string, url of the result |
|
template is set to ``torrent.html``
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
url string, url of the result
|
||||||
| title | string, title of the result |
|
title string, title of the result
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
content string, general result-text
|
||||||
| content | string, general result-text |
|
publishedDate :py:class:`datetime.datetime`,
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
time of publish *(not implemented yet)*
|
||||||
| publishedDate | :py:class:`datetime.datetime`, time of publish *(not implemented yet)* |
|
seed int, number of seeder
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
leech int, number of leecher
|
||||||
| seed | int, number of seeder |
|
filesize int, size of file in bytes
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
files int, number of files
|
||||||
| leech | int, number of leecher |
|
magnetlink string, magnetlink_ of the result
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
torrentfile string, torrentfile of the result
|
||||||
| filesize | int, size of file in bytes |
|
========================= =====================================================
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
| files | int, number of files |
|
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
| magnetlink | string, `magnetlink <https://en.wikipedia.org/wiki/Magnet_URI_scheme>`__ of the result |
|
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
| torrentfile | string, torrentfile of the result |
|
|
||||||
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
|
|
||||||
map
|
map
|
||||||
~~~
|
---
|
||||||
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| result-parameter | information |
|
|
||||||
+=========================+==============================================================================================================+
|
|
||||||
| url | string, url of the result |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| title | string, title of the result |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| content | string, general result-text |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| publishedDate | :py:class:`datetime.datetime`, time of publish |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| 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) |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| osm.type | type of osm-object (if OSM-Result) |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| osm.id | id of osm-object (if OSM-Result) |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| address.name | name of object |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| address.road | street name of object |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| address.house\_number | house number of object |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| address.locality | city, place of object |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| address.postcode | postcode of object |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
| address.country | country of object |
|
|
||||||
+-------------------------+--------------------------------------------------------------------------------------------------------------+
|
|
||||||
|
|
||||||
|
========================= =====================================================
|
||||||
|
result-parameter information
|
||||||
|
========================= =====================================================
|
||||||
|
url string, url of the result
|
||||||
|
title string, title of the result
|
||||||
|
content string, general result-text
|
||||||
|
publishedDate :py:class:`datetime.datetime`, time of publish
|
||||||
|
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)
|
||||||
|
osm.type type of osm-object (if OSM-Result)
|
||||||
|
osm.id id of osm-object (if OSM-Result)
|
||||||
|
address.name name of object
|
||||||
|
address.road street name of object
|
||||||
|
address.house_number house number of object
|
||||||
|
address.locality city, place of object
|
||||||
|
address.postcode postcode of object
|
||||||
|
address.country country of object
|
||||||
|
========================= =====================================================
|
||||||
|
|
|
||||||
|
|
@ -1,11 +1,11 @@
|
||||||
|
=======
|
||||||
Plugins
|
Plugins
|
||||||
-------
|
=======
|
||||||
|
|
||||||
Plugins can extend or replace functionality of various components of
|
Plugins can extend or replace functionality of various components of searx.
|
||||||
searx.
|
|
||||||
|
|
||||||
Example plugin
|
Example plugin
|
||||||
~~~~~~~~~~~~~~
|
==============
|
||||||
|
|
||||||
.. code:: python
|
.. code:: python
|
||||||
|
|
||||||
|
|
@ -25,21 +25,24 @@ Example plugin
|
||||||
return True
|
return True
|
||||||
|
|
||||||
Plugin entry points
|
Plugin entry points
|
||||||
~~~~~~~~~~~~~~~~~~~
|
===================
|
||||||
|
|
||||||
Entry points (hooks) define when a plugin runs. Right now only three hooks are implemented. So feel free to implement a hook if it fits the behaviour of your plugin.
|
Entry points (hooks) define when a plugin runs. Right now only three hooks are
|
||||||
|
implemented. So feel free to implement a hook if it fits the behaviour of your
|
||||||
|
plugin.
|
||||||
|
|
||||||
Pre search hook
|
Pre search hook
|
||||||
```````````````
|
---------------
|
||||||
|
|
||||||
Runs BEFORE the search request. Function to implement: ``pre_search``
|
Runs BEFORE the search request. Function to implement: ``pre_search``
|
||||||
|
|
||||||
Post search hook
|
Post search hook
|
||||||
````````````````
|
----------------
|
||||||
|
|
||||||
Runs AFTER the search request. Function to implement: ``post_search``
|
Runs AFTER the search request. Function to implement: ``post_search``
|
||||||
|
|
||||||
Result hook
|
Result hook
|
||||||
```````````
|
-----------
|
||||||
|
|
||||||
Runs when a new result is added to the result list. Function to implement: ``on_result``
|
Runs when a new result is added to the result list. Function to implement:
|
||||||
|
``on_result``
|
||||||
|
|
|
||||||
|
|
@ -1,17 +1,18 @@
|
||||||
.. _devquickstart:
|
.. _devquickstart:
|
||||||
|
|
||||||
|
======================
|
||||||
Development Quickstart
|
Development Quickstart
|
||||||
----------------------
|
======================
|
||||||
|
|
||||||
This quickstart guide gets your environment set up with searx. Furthermore, it gives a
|
This quickstart guide gets your environment set up with searx. Furthermore, it
|
||||||
short introduction to the new manage.sh script.
|
gives a short introduction to the ``manage.sh`` script.
|
||||||
|
|
||||||
How to setup your development environment
|
How to setup your development environment
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
=========================================
|
||||||
|
|
||||||
First, clone the source code of searx to the desired folder. In this case the source
|
First, clone the source code of searx to the desired folder. In this case the
|
||||||
is cloned to ~/myprojects/searx. Then create and activate the searx-ve
|
source is cloned to ``~/myprojects/searx``. Then create and activate the
|
||||||
virtualenv and install the required packages using manage.sh.
|
searx-ve virtualenv and install the required packages using manage.sh.
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: sh
|
||||||
|
|
||||||
|
|
@ -24,18 +25,14 @@ virtualenv and install the required packages using manage.sh.
|
||||||
|
|
||||||
|
|
||||||
How to run tests
|
How to run tests
|
||||||
~~~~~~~~~~~~~~~~
|
================
|
||||||
|
|
||||||
Tests can be run using the manage.sh script.
|
Tests can be run using the ``manage.sh`` script. Following tests and checks are
|
||||||
|
available:
|
||||||
Following tests and checks are available:
|
|
||||||
|
|
||||||
- Unit tests
|
- Unit tests
|
||||||
|
|
||||||
- Selenium tests
|
- Selenium tests
|
||||||
|
|
||||||
- PEP8 validation
|
- PEP8 validation
|
||||||
|
|
||||||
- Unit test coverage check
|
- Unit test coverage check
|
||||||
|
|
||||||
For example unit tests are run with the command below:
|
For example unit tests are run with the command below:
|
||||||
|
|
@ -44,30 +41,33 @@ For example unit tests are run with the command below:
|
||||||
|
|
||||||
./manage.sh unit_tests
|
./manage.sh unit_tests
|
||||||
|
|
||||||
For further test options, please consult the help of the manage.sh script.
|
For further test options, please consult the help of the ``manage.sh`` script.
|
||||||
|
|
||||||
|
|
||||||
How to compile styles and javascript
|
How to compile styles and javascript
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
====================================
|
||||||
|
|
||||||
|
.. _less: http://lesscss.org/
|
||||||
|
.. _NodeJS: https://nodejs.org
|
||||||
|
|
||||||
How to build styles
|
How to build styles
|
||||||
^^^^^^^^^^^^^^^^^^^
|
-------------------
|
||||||
|
|
||||||
Less is required to build the styles of searx. Less can be installed using either NodeJS or Apt.
|
Less_ is required to build the styles of searx. Less_ can be installed using
|
||||||
|
either NodeJS_ or Apt.
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: sh
|
||||||
|
|
||||||
sudo apt-get install nodejs
|
sudo -H apt-get install nodejs
|
||||||
sudo npm install -g less
|
sudo -H npm install -g less
|
||||||
|
|
||||||
|
|
||||||
OR
|
OR
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: sh
|
||||||
|
|
||||||
sudo apt-get install node-less
|
sudo -H apt-get install node-less
|
||||||
|
|
||||||
After satisfying the requirements styles can be build using manage.sh
|
After satisfying the requirements styles can be build using ``manage.sh``
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: sh
|
||||||
|
|
||||||
|
|
@ -75,15 +75,17 @@ After satisfying the requirements styles can be build using manage.sh
|
||||||
|
|
||||||
|
|
||||||
How to build the source of the oscar theme
|
How to build the source of the oscar theme
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
==========================================
|
||||||
|
|
||||||
Grunt must be installed in order to build the javascript sources. It depends on NodeJS, so first
|
.. _grunt: https://gruntjs.com/
|
||||||
Node has to be installed.
|
|
||||||
|
Grunt_ must be installed in order to build the javascript sources. It depends on
|
||||||
|
NodeJS, so first Node has to be installed.
|
||||||
|
|
||||||
.. code:: sh
|
.. code:: sh
|
||||||
|
|
||||||
sudo apt-get install nodejs
|
sudo -H apt-get install nodejs
|
||||||
sudo npm install -g grunt-cli
|
sudo -H npm install -g grunt-cli
|
||||||
|
|
||||||
After installing grunt, the files can be built using the following command:
|
After installing grunt, the files can be built using the following command:
|
||||||
|
|
||||||
|
|
@ -92,17 +94,17 @@ After installing grunt, the files can be built using the following command:
|
||||||
./manage.sh grunt_build
|
./manage.sh grunt_build
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Tips for debugging/development
|
Tips for debugging/development
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
==============================
|
||||||
|
|
||||||
1. Turn on debug logging
|
Turn on debug logging
|
||||||
Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea
|
Whether you are working on a new engine or trying to eliminate a bug, it is
|
||||||
to turn on debug logging. When debug logging is enabled a stack trace appears,
|
always a good idea to turn on debug logging. When debug logging is enabled a
|
||||||
instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting
|
stack trace appears, instead of the cryptic ``Internal Server Error``
|
||||||
``debug: False`` to ``debug: True`` in settings.yml.
|
message. It can be turned on by setting ``debug: False`` to ``debug: True`` in
|
||||||
|
:origin:`settings.yml <searx/settings.yml>`.
|
||||||
|
|
||||||
2. Run ``./manage.sh tests`` before creating a PR.
|
Run ``./manage.sh tests`` before creating a PR.
|
||||||
Failing build on Travis is common because of PEP8 checks. So a new commit must be created
|
Failing build on Travis is common because of PEP8 checks. So a new commit
|
||||||
containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run
|
must be created containing these format fixes. This phase can be skipped if
|
||||||
locally before creating a PR.
|
``./manage.sh tests`` is run locally before creating a PR.
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,4 @@
|
||||||
|
==========
|
||||||
Search API
|
Search API
|
||||||
==========
|
==========
|
||||||
|
|
||||||
|
|
@ -11,194 +12,101 @@ Furthermore, two enpoints ``/`` and ``/search`` are available for querying.
|
||||||
``GET /search``
|
``GET /search``
|
||||||
|
|
||||||
Parameters
|
Parameters
|
||||||
~~~~~~~~~~
|
==========
|
||||||
|
|
||||||
.. code:: sh
|
``q`` : required
|
||||||
|
The search query. This string is passed to external search services. Thus,
|
||||||
|
searx supports syntax of each search service. For example, ``site:github.com
|
||||||
|
searx`` is a valid query for Google. However, if simply the query above is
|
||||||
|
passed to any search engine which does not filter its results based on this
|
||||||
|
syntax, you might not get the results you wanted.
|
||||||
|
|
||||||
q
|
See more at :ref:`search-syntax`
|
||||||
|
|
||||||
The search query. This string is passed to external search services.
|
|
||||||
Thus, searx supports syntax of each search service. For example, ``site:github.com searx`` is a valid
|
|
||||||
query for Google. However, if simply the query above is passed to any search engine which does not filter its
|
|
||||||
results based on this syntax, you might not get the results you wanted.
|
|
||||||
|
|
||||||
|
|
||||||
See more at :doc:`/user/search_syntax`
|
|
||||||
|
|
||||||
Required.
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
categories
|
|
||||||
|
|
||||||
|
``categories`` : optional
|
||||||
Comma separated list, specifies the active search categories
|
Comma separated list, specifies the active search categories
|
||||||
|
|
||||||
Optional.
|
``engines``: optional
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
engines
|
|
||||||
|
|
||||||
Comma separated list, specifies the active search engines.
|
Comma separated list, specifies the active search engines.
|
||||||
|
|
||||||
Optional.
|
``lang``: default ``all``
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
lang
|
|
||||||
|
|
||||||
Code of the language.
|
Code of the language.
|
||||||
|
|
||||||
Optional.
|
``pageno``: default ``1``
|
||||||
|
|
||||||
Default: ``all``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
pageno
|
|
||||||
|
|
||||||
Search page number.
|
Search page number.
|
||||||
|
|
||||||
Optional.
|
``time_range``: optional
|
||||||
|
[ ``day``, ``month``, ``year`` ]
|
||||||
|
|
||||||
Default: ``1``
|
Time range of search for engines which support it. See if an engine supports
|
||||||
|
time range search in the preferences page of an instance.
|
||||||
|
|
||||||
.. code:: sh
|
``format``: optional
|
||||||
|
[ ``json``, ``csv``, ``rss`` ]
|
||||||
time_range
|
|
||||||
|
|
||||||
Time range of search for engines which support it. See if an engine supports time range search in the preferences page of an instance.
|
|
||||||
|
|
||||||
Optional.
|
|
||||||
|
|
||||||
Possible: ``day``, ``month``, ``year``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
format
|
|
||||||
|
|
||||||
Output format of results.
|
Output format of results.
|
||||||
|
|
||||||
Optional.
|
``results_on_new_tab``: default ``0``
|
||||||
|
[ ``0``, ``1`` ]
|
||||||
Possible: ``json``, ``csv``, ``rss``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
results_on_new_tab
|
|
||||||
|
|
||||||
Open search results on new tab.
|
Open search results on new tab.
|
||||||
|
|
||||||
Optional.
|
``image_proxy``: default ``False``
|
||||||
|
[ ``True``, ``False`` ]
|
||||||
Default: ``0``
|
|
||||||
|
|
||||||
Possible: ``0``, ``1``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
image_proxy
|
|
||||||
|
|
||||||
Proxy image results through searx.
|
Proxy image results through searx.
|
||||||
|
|
||||||
Optional.
|
``autocomplete``: default *empty*
|
||||||
|
[ ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia`` ]
|
||||||
Default: ``False``
|
|
||||||
|
|
||||||
Possible: ``True``, ``False``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
autocomplete
|
|
||||||
|
|
||||||
Service which completes words as you type.
|
Service which completes words as you type.
|
||||||
|
|
||||||
Optional.
|
``safesearch``: default ``None``
|
||||||
|
[ ``0``, ``1``, ``None`` ]
|
||||||
|
|
||||||
Default: empty
|
Filter search results of engines which support safe search. See if an engine
|
||||||
|
supports safe search in the preferences page of an instance.
|
||||||
|
|
||||||
Possible: ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia``
|
``theme``: default ``oscar``
|
||||||
|
[ ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette`` ]
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
safesearch
|
|
||||||
|
|
||||||
Filter search results of engines which support safe search. See if an engine supports safe search in the preferences page of an instance.
|
|
||||||
|
|
||||||
Optional.
|
|
||||||
|
|
||||||
Default: ``None``
|
|
||||||
|
|
||||||
Possible: ``0``, ``1``, ``None``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
theme
|
|
||||||
|
|
||||||
Theme of instance.
|
Theme of instance.
|
||||||
|
|
||||||
Optional.
|
Please note, available themes depend on an instance. It is possible that an
|
||||||
|
instance administrator deleted, created or renamed themes on his/her instance.
|
||||||
|
See the available options in the preferences page of the instance.
|
||||||
|
|
||||||
Default: ``oscar``
|
``oscar-style``: default ``logicodev``
|
||||||
|
[ ``pointhi``, ``logicodev`` ]
|
||||||
|
|
||||||
Possible: ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette``
|
Style of Oscar theme. It is only parsed if the theme of an instance is
|
||||||
|
``oscar``.
|
||||||
|
|
||||||
Please note, available themes depend on an instance. It is possible that an instance administrator deleted, created or renamed themes on his/her instance. See the available options in the preferences page of the instance.
|
Please note, available styles depend on an instance. It is possible that an
|
||||||
|
instance administrator deleted, created or renamed styles on his/her
|
||||||
.. code:: sh
|
instance. See the available options in the preferences page of the instance.
|
||||||
|
|
||||||
oscar-style
|
|
||||||
|
|
||||||
Style of Oscar theme. It is only parsed if the theme of an instance is ``oscar``.
|
|
||||||
|
|
||||||
Optional.
|
|
||||||
|
|
||||||
Default: ``logicodev``
|
|
||||||
|
|
||||||
Possible: ``pointhi``, ``logicodev``
|
|
||||||
|
|
||||||
Please note, available styles depend on an instance. It is possible that an instance administrator deleted, created or renamed styles on his/her instance. See the available options in the preferences page of the instance.
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
enabled_plugins
|
|
||||||
|
|
||||||
|
``enabled_plugins``: optional
|
||||||
List of enabled plugins.
|
List of enabled plugins.
|
||||||
|
|
||||||
Optional.
|
:default: ``HTTPS_rewrite``, ``Self_Informations``,
|
||||||
|
``Search_on_category_select``, ``Tracker_URL_remover``
|
||||||
|
|
||||||
Default: ``HTTPS_rewrite``, ``Self_Informations``, ``Search_on_category_select``, ``Tracker_URL_remover``
|
:values: [ ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``,
|
||||||
|
``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``,
|
||||||
Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select``
|
``Search_on_category_select`` ]
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
disabled_plugins
|
|
||||||
|
|
||||||
|
``disabled_plugins``: optional
|
||||||
List of disabled plugins.
|
List of disabled plugins.
|
||||||
|
|
||||||
Optional.
|
:default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``
|
||||||
|
:values: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``,
|
||||||
Default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``
|
``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``,
|
||||||
|
``Search_on_category_select``
|
||||||
Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select``
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
enabled_engines
|
|
||||||
|
|
||||||
|
``enabled_engines``: optional : *all* :origin:`engines <searx/engines>`
|
||||||
List of enabled engines.
|
List of enabled engines.
|
||||||
|
|
||||||
Optional.
|
``disabled_engines``: optional : *all* :origin:`engines <searx/engines>`
|
||||||
|
|
||||||
Possible: all engines
|
|
||||||
|
|
||||||
.. code:: sh
|
|
||||||
|
|
||||||
disabled_engines
|
|
||||||
|
|
||||||
List of disabled engines.
|
List of disabled engines.
|
||||||
|
|
||||||
Optional.
|
|
||||||
|
|
||||||
Possible: all engines
|
|
||||||
|
|
|
||||||
|
|
@ -1,28 +1,36 @@
|
||||||
|
.. _translation:
|
||||||
|
|
||||||
|
===========
|
||||||
Translation
|
Translation
|
||||||
===========
|
===========
|
||||||
|
|
||||||
|
.. _searx@transifex: https://www.transifex.com/asciimoo/searx/
|
||||||
|
|
||||||
|
Translation currently takes place on `searx@transifex`_
|
||||||
|
|
||||||
Requirements
|
Requirements
|
||||||
------------
|
============
|
||||||
|
|
||||||
* Transifex account
|
* Transifex account
|
||||||
|
|
||||||
* Installed CLI tool of Transifex
|
* Installed CLI tool of Transifex
|
||||||
|
|
||||||
Init Transifex project
|
Init Transifex project
|
||||||
----------------------
|
======================
|
||||||
|
|
||||||
After installing ``transifex`` using pip, run the following command to initialize the project.
|
After installing ``transifex`` using pip, run the following command to
|
||||||
|
initialize the project.
|
||||||
|
|
||||||
.. code:: shell
|
.. code:: sh
|
||||||
|
|
||||||
tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/
|
tx init # Transifex instance: https://www.transifex.com/asciimoo/searx/
|
||||||
|
|
||||||
|
|
||||||
After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it into the configuration file.
|
After ``$HOME/.transifexrc`` is created, get a Transifex API key and insert it
|
||||||
|
into the configuration file.
|
||||||
|
|
||||||
Create a configuration file for ``tx`` named ``$HOME/.tx/config``.
|
Create a configuration file for ``tx`` named ``$HOME/.tx/config``.
|
||||||
|
|
||||||
.. code:: shell
|
.. code:: ini
|
||||||
|
|
||||||
[main]
|
[main]
|
||||||
host = https://www.transifex.com
|
host = https://www.transifex.com
|
||||||
|
|
@ -42,20 +50,22 @@ Then run ``tx set``:
|
||||||
|
|
||||||
|
|
||||||
Update translations
|
Update translations
|
||||||
-------------------
|
===================
|
||||||
|
|
||||||
To retrieve the latest translations, pull it from Transifex.
|
To retrieve the latest translations, pull it from Transifex.
|
||||||
|
|
||||||
.. code:: shell
|
.. code:: sh
|
||||||
|
|
||||||
tx pull -a
|
tx pull -a
|
||||||
|
|
||||||
Then check the new languages. If strings translated are not enough, delete those folders, because
|
Then check the new languages. If strings translated are not enough, delete those
|
||||||
those should not be compiled. Call the command below to compile the ``.po`` files.
|
folders, because those should not be compiled. Call the command below to compile
|
||||||
|
the ``.po`` files.
|
||||||
|
|
||||||
.. code:: shell
|
.. code:: shell
|
||||||
|
|
||||||
pybabel compile -d searx/translations
|
pybabel compile -d searx/translations
|
||||||
|
|
||||||
|
|
||||||
After the compilation is finished commit the ``.po`` and ``.mo`` files and create a PR.
|
After the compilation is finished commit the ``.po`` and ``.mo`` files and
|
||||||
|
create a PR.
|
||||||
|
|
|
||||||
|
|
@ -3,13 +3,7 @@ Welcome to searx
|
||||||
|
|
||||||
Search without being tracked.
|
Search without being tracked.
|
||||||
|
|
||||||
Searx is a free internet metasearch engine which aggregates results from more than 70 search services. Users are neither tracked nor profiled. Additionally, searx can be used over Tor for online anonymity.
|
.. sidebar:: Features
|
||||||
|
|
||||||
Get started with searx by using one of the :wiki:`Searx-instances`. If you don't trust anyone, you can set up your own, see :ref:`installation`.
|
|
||||||
|
|
||||||
|
|
||||||
Features
|
|
||||||
--------
|
|
||||||
|
|
||||||
- Self hosted
|
- Self hosted
|
||||||
- No user tracking
|
- No user tracking
|
||||||
|
|
@ -18,7 +12,15 @@ Features
|
||||||
- Easy integration with any search engine
|
- Easy integration with any search engine
|
||||||
- Cookies are not used by default
|
- Cookies are not used by default
|
||||||
- Secure, encrypted connections (HTTPS/SSL)
|
- Secure, encrypted connections (HTTPS/SSL)
|
||||||
- Hosted by organisations, such as La Quadrature du Net, which promote digital rights
|
- Hosted by organizations, such as *La Quadrature du Net*, which promote
|
||||||
|
digital rights
|
||||||
|
|
||||||
|
Searx is a free internet metasearch engine which aggregates results from more
|
||||||
|
than 70 search services. Users are neither tracked nor profiled. Additionally,
|
||||||
|
searx can be used over Tor for online anonymity.
|
||||||
|
|
||||||
|
Get started with searx by using one of the :wiki:`Searx-instances`. If you
|
||||||
|
don't trust anyone, you can set up your own, see :ref:`installation`.
|
||||||
|
|
||||||
|
|
||||||
User documentation
|
User documentation
|
||||||
|
|
|
||||||
|
|
@ -1,43 +1,77 @@
|
||||||
|
===========================
|
||||||
Why use a private instance?
|
Why use a private instance?
|
||||||
===========================
|
===========================
|
||||||
|
|
||||||
"Is it worth to run my own instance?" is a common question among searx users. Before answering this question, see what options a searx user has.
|
"Is it worth to run my own instance?" is a common question among searx users.
|
||||||
|
Before answering this question, see what options a searx user has.
|
||||||
|
|
||||||
Public instances are open to everyone who has access to its URL. Usually, these are operated by unknown parties (from the users' point of view). Private instances can be used by a select group of people. It is for example a searx of group of friends or a company which can be accessed through VPN. Also it can be single user one which runs on the user's laptop.
|
Public instances are open to everyone who has access to its URL. Usually, these
|
||||||
|
are operated by unknown parties (from the users' point of view). Private
|
||||||
|
instances can be used by a select group of people. It is for example a searx of
|
||||||
|
group of friends or a company which can be accessed through VPN. Also it can be
|
||||||
|
single user one which runs on the user's laptop.
|
||||||
|
|
||||||
To gain more insight on how these instances work let's dive into how searx protects its users.
|
To gain more insight on how these instances work let's dive into how searx
|
||||||
|
protects its users.
|
||||||
|
|
||||||
How does searx protect privacy?
|
How does searx protect privacy?
|
||||||
-------------------------------
|
===============================
|
||||||
|
|
||||||
Searx protects the privacy of its users in multiple ways regardless of the type of the instance (private, public). Removal of private data from search requests comes in three forms:
|
Searx protects the privacy of its users in multiple ways regardless of the type
|
||||||
|
of the instance (private, public). Removal of private data from search requests
|
||||||
|
comes in three forms:
|
||||||
|
|
||||||
1. removal of private data from requests going to search services
|
1. removal of private data from requests going to search services
|
||||||
2. not forwarding anything from a third party services through search services (e.g. advertisement)
|
2. not forwarding anything from a third party services through search services
|
||||||
|
(e.g. advertisement)
|
||||||
3. removal of private data from requests going to the result pages
|
3. removal of private data from requests going to the result pages
|
||||||
|
|
||||||
Removing private data means not sending cookies to external search engines and generating a random browser profile for every request. Thus, it does not matter if a public or private instance handles the request, because it is anonymized in both cases. IP addresses will be the IP of the instance. But searx can be configured to use proxy or Tor. `Result proxy <https://github.com/asciimoo/morty>`__ is supported, too.
|
Removing private data means not sending cookies to external search engines and
|
||||||
|
generating a random browser profile for every request. Thus, it does not matter
|
||||||
|
if a public or private instance handles the request, because it is anonymized in
|
||||||
|
both cases. IP addresses will be the IP of the instance. But searx can be
|
||||||
|
configured to use proxy or Tor. `Result proxy
|
||||||
|
<https://github.com/asciimoo/morty>`__ is supported, too.
|
||||||
|
|
||||||
|
Searx does not serve ads or tracking content unlike most search services. So
|
||||||
|
private data is not forwarded to third parties who might monetize it. Besides
|
||||||
|
protecting users from search services, both referring page and search query are
|
||||||
|
hidden from visited result pages.
|
||||||
|
|
||||||
Searx does not serve ads or tracking content unlike most search services. So private data is not forwarded to third parties who might monetize it. Besides protecting users from search services, both referring page and search query are hidden from visited result pages.
|
|
||||||
|
|
||||||
What are the consequences of using public instances?
|
What are the consequences of using public instances?
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
----------------------------------------------------
|
||||||
|
|
||||||
If someone uses a public instance, he/she has to trust the administrator of that instance.
|
If someone uses a public instance, he/she has to trust the administrator of that
|
||||||
This means that the user of the public instance does not know whether his/her requests are logged, aggregated and sent or sold to a third party.
|
instance. This means that the user of the public instance does not know whether
|
||||||
|
his/her requests are logged, aggregated and sent or sold to a third party.
|
||||||
|
|
||||||
Also, public instances without proper protection are more vulnerable to abusing the search service, In this case the external service in exchange returns CAPTCHAs or bans the IP of the instance. Thus, search requests return less results.
|
Also, public instances without proper protection are more vulnerable to abusing
|
||||||
|
the search service, In this case the external service in exchange returns
|
||||||
|
CAPTCHAs or bans the IP of the instance. Thus, search requests return less
|
||||||
|
results.
|
||||||
|
|
||||||
I see. What about private instances?
|
I see. What about private instances?
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
------------------------------------
|
||||||
|
|
||||||
If users run their own instances, everything is in their control: the source code, logging settings and private data. Unknown instance administrators do not have to be trusted.
|
If users run their own instances, everything is in their control: the source
|
||||||
|
code, logging settings and private data. Unknown instance administrators do not
|
||||||
|
have to be trusted.
|
||||||
|
|
||||||
Furthermore, as the default settings of their instance is editable, there is no need to use cookies to tailor searx to their needs. So preferences will not be reset to defaults when clearing browser cookies. As settings are stored on their computer, it will not be accessible to others as long as their computer is not compromised.
|
Furthermore, as the default settings of their instance is editable, there is no
|
||||||
|
need to use cookies to tailor searx to their needs. So preferences will not be
|
||||||
|
reset to defaults when clearing browser cookies. As settings are stored on
|
||||||
|
their computer, it will not be accessible to others as long as their computer is
|
||||||
|
not compromised.
|
||||||
|
|
||||||
Conclusion
|
Conclusion
|
||||||
----------
|
==========
|
||||||
|
|
||||||
Always use an instance which is operated by people you trust. The privacy features of searx are available to users no matter what kind of instance they use.
|
Always use an instance which is operated by people you trust. The privacy
|
||||||
|
features of searx are available to users no matter what kind of instance they
|
||||||
|
use.
|
||||||
|
|
||||||
If someone is on the go or just wants to try searx for the first time public instances are the best choices. Additionally, public instance are making a world a better place, because those who cannot or do not want to run an instance, have access to a privacy respecting search service.
|
If someone is on the go or just wants to try searx for the first time public
|
||||||
|
instances are the best choices. Additionally, public instance are making a
|
||||||
|
world a better place, because those who cannot or do not want to run an
|
||||||
|
instance, have access to a privacy respecting search service.
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,12 @@
|
||||||
|
|
||||||
|
.. _search-syntax:
|
||||||
|
|
||||||
|
=============
|
||||||
Search syntax
|
Search syntax
|
||||||
=============
|
=============
|
||||||
|
|
||||||
Searx allows you to modify the default categories, engines and search
|
Searx allows you to modify the default categories, engines and search language
|
||||||
language via the search query.
|
via the search query.
|
||||||
|
|
||||||
Prefix ``!``
|
Prefix ``!``
|
||||||
to set Category/engine
|
to set Category/engine
|
||||||
|
|
@ -22,7 +26,7 @@ See the :search:`/preferences page <preferences>` for the list of engines,
|
||||||
categories and languages.
|
categories and languages.
|
||||||
|
|
||||||
Examples
|
Examples
|
||||||
~~~~~~~~
|
========
|
||||||
|
|
||||||
Search in wikipedia for ``qwer``:
|
Search in wikipedia for ``qwer``:
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue