OwlBurst/Ponysearch
1
0
Fork 0
forked from Ponysearch/Ponysearch
Code Pull requests Activity

doc: move patches from /doc folder of branch gh-pages to master

Browse source 
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2019-12-12 11:19:26 +01:00
commit 49e8dd1e0d
25 changed files with 2533 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
docs/_themes/searx_theme/layout.html vendored Normal file
View file

@ -0,0 +1,20 @@
{%- extends "basic/layout.html" %}
{%- block extrahead %}
{{ super() }}
{% if theme_touch_icon %}
<link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
{% endif %}
<link media="only screen and (max-device-width: 480px)" href="{{
pathto('_static/small_flask.css', 1) }}" type= "text/css" rel="stylesheet" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
{% endblock %}
{%- block relbar2 %}{% endblock %}
{%- block relbar1 %}{% endblock %}
{%- block sidebarsearch %}{% endblock %}
{%- block sidebarsourcelink %}{% endblock %}
{%- block sidebartoc %}{% endblock %}
{%- block footer %}
<div class="footer">
&copy; Copyright {{ copyright }}.
</div>
{%- endblock %}

14
docs/_themes/searx_theme/relations.html vendored Normal file
View file

@ -0,0 +1,14 @@
<div class="sidebar_container body">
<h1>Searx</h1>
<ul>
<li><a href="{{ pathto('index') }}">Home</a></li>
<li><a href="https://github.com/asciimoo/searx">Source</a></li>
<li><a href="{{ pathto('blog/blog') }}">Blog</a></li>
<li><a href="https://github.com/asciimoo/searx/wiki">Wiki</a></li>
<li><a href="https://github.com/asciimoo/searx/wiki/Searx-instances">Public instances</a></li>
</ul>
<hr />
<ul>
<li><a href="https://twitter.com/Searx_engine">Twitter</a></li>
</ul>
</div>

443
docs/_themes/searx_theme/static/style.css_t vendored Normal file
View file

@ -0,0 +1,443 @@
/*
* flasky.css_t
* ~~~~~~~~~~~~
*
* :copyright: Copyright 2010 by Armin Ronacher. Modifications by Kenneth Reitz.
* :license: Flask Design License, see LICENSE for details.
*/
{% set page_width = '940px' %}
{% set sidebar_width = '220px' %}
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
body {
font-family: 'goudy old style', 'minion pro', 'bell mt', Georgia, 'Hiragino Mincho Pro';
font-size: 17px;
background-color: white;
color: #000;
margin: 0;
padding: 0;
}
div.document {
width: {{ page_width }};
margin: 30px auto 0 auto;
}
div.documentwrapper {
float: left;
width: 100%;
}
div.bodywrapper {
margin: 0 0 0 {{ sidebar_width }};
}
div.sphinxsidebar {
width: {{ sidebar_width }};
word-wrap: normal !important;
overflow-wrap: normal !important;
}
hr {
border: 1px solid #B1B4B6;
}
div.body {
background-color: #ffffff;
color: #3E4349;
padding: 0 30px 0 30px;
}
img.floatingflask {
padding: 0 0 10px 10px;
float: right;
}
div.footer {
width: {{ page_width }};
margin: 20px auto 30px auto;
font-size: 14px;
color: #888;
text-align: right;
}
div.footer a {
color: #888;
}
div.sphinxsidebar a {
color: #444;
text-decoration: none;
border-bottom: 1px dotted #999;
}
div.sphinxsidebar a:hover {
border-bottom: 1px solid #999;
}
div.sphinxsidebarwrapper {
padding: 0 10px;
}
div.sphinxsidebarwrapper p.logo {
padding: 0;
margin: -10px 0 0 -20px;
text-align: center;
}
div.sphinxsidebar h3,
div.sphinxsidebar h4 {
font-family: 'Garamond', 'Georgia', serif;
color: #444;
font-size: 24px;
font-weight: normal;
margin: 0 0 5px 0;
padding: 0;
}
div.sphinxsidebar h4 {
font-size: 20px;
}
div.sphinxsidebar h3 a {
color: #444;
}
div.sphinxsidebar p.logo a,
div.sphinxsidebar h3 a,
div.sphinxsidebar p.logo a:hover,
div.sphinxsidebar h3 a:hover {
border: none;
}
div.sphinxsidebar p {
color: #555;
margin: 10px 0;
}
div.sphinxsidebar ul {
margin: 10px 0;
padding: 0;
color: #000;
}
div.sphinxsidebar input {
border: 1px solid #ccc;
font-family: 'Georgia', serif;
font-size: 1em;
}
/* -- body styles ----------------------------------------------------------- */
a {
color: #004B6B;
text-decoration: underline;
}
a:hover {
color: #6D4100;
text-decoration: underline;
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family: 'Garamond', 'Georgia', serif;
font-weight: normal;
margin: 30px 0px 10px 0px;
padding: 0;
}
div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; }
div.body h2 { font-size: 180%; }
div.body h3 { font-size: 150%; }
div.body h4 { font-size: 130%; }
div.body h5 { font-size: 100%; }
div.body h6 { font-size: 100%; }
a.headerlink {
color: #ddd;
padding: 0 4px;
text-decoration: none;
}
a.headerlink:hover {
color: #444;
background: #eaeaea;
}
div.body p, div.body dd, div.body li {
line-height: 1.4em;
}
div.admonition {
background: #fafafa;
margin: 20px -30px;
padding: 10px 30px;
border-top: 1px solid #ccc;
border-bottom: 1px solid #ccc;
}
div.admonition tt.xref, div.admonition a tt {
border-bottom: 1px solid #fafafa;
}
dd div.admonition {
margin-left: -60px;
padding-left: 60px;
}
div.admonition p.admonition-title {
font-family: 'Garamond', 'Georgia', serif;
font-weight: normal;
font-size: 24px;
margin: 0 0 10px 0;
padding: 0;
line-height: 1;
}
div.admonition p.last {
margin-bottom: 0;
}
div.highlight {
background-color: white;
}
dt:target, .highlight {
background: #FAF3E8;
}
div.note {
background-color: #eee;
border: 1px solid #ccc;
}
div.seealso {
background-color: #ffc;
border: 1px solid #ff6;
}
div.topic {
background-color: #eee;
}
p.admonition-title {
display: inline;
}
p.admonition-title:after {
content: ":";
}
pre, tt {
font-family: 'Consolas', 'Menlo', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
font-size: 0.9em;
}
img.screenshot {
}
tt.descname, tt.descclassname {
font-size: 0.95em;
}
tt.descname {
padding-right: 0.08em;
}
img.screenshot {
-moz-box-shadow: 2px 2px 4px #eee;
-webkit-box-shadow: 2px 2px 4px #eee;
box-shadow: 2px 2px 4px #eee;
}
table.docutils {
border: 1px solid #888;
-moz-box-shadow: 2px 2px 4px #eee;
-webkit-box-shadow: 2px 2px 4px #eee;
box-shadow: 2px 2px 4px #eee;
}
table.docutils td, table.docutils th {
border: 1px solid #888;
padding: 0.25em 0.7em;
}
table.field-list, table.footnote {
border: none;
-moz-box-shadow: none;
-webkit-box-shadow: none;
box-shadow: none;
}
table.footnote {
margin: 15px 0;
width: 100%;
border: 1px solid #eee;
background: #fdfdfd;
font-size: 0.9em;
}
table.footnote + table.footnote {
margin-top: -15px;
border-top: none;
}
table.field-list th {
padding: 0 0.8em 0 0;
}
table.field-list td {
padding: 0;
}
table.footnote td.label {
width: 0px;
padding: 0.3em 0 0.3em 0.5em;
}
table.footnote td {
padding: 0.3em 0.5em;
}
dl {
margin: 0;
padding: 0;
}
dl dd {
margin-left: 30px;
}
blockquote {
margin: 0 0 0 30px;
padding: 0;
}
ul, ol {
margin: 10px 0 10px 30px;
padding: 0;
}
pre {
background: #eee;
padding: 7px 30px;
margin: 15px -30px;
line-height: 1.3em;
}
dl pre, blockquote pre, li pre {
margin-left: -60px;
padding-left: 60px;
}
dl dl pre {
margin-left: -90px;
padding-left: 90px;
}
tt {
background-color: #ecf0f3;
color: #222;
/* padding: 1px 2px; */
}
tt.xref, a tt {
background-color: #FBFBFB;
border-bottom: 1px solid white;
}
a.reference {
text-decoration: none;
border-bottom: 1px dotted #004B6B;
}
a.reference:hover {
border-bottom: 1px solid #6D4100;
}
a.footnote-reference {
text-decoration: none;
font-size: 0.7em;
vertical-align: top;
border-bottom: 1px dotted #004B6B;
}
a.footnote-reference:hover {
border-bottom: 1px solid #6D4100;
}
a:hover tt {
background: #EEE;
}
@media screen and (max-width: 600px) {
div.document {
width: 100%;
}
div.documentwrapper {
margin-left: 0;
margin-top: 0;
margin-right: 0;
margin-bottom: 0;
}
div.bodywrapper {
margin-top: 0;
margin-right: 0;
margin-bottom: 0;
margin-left: 0;
}
ul {
margin-left: 0;
}
.document {
width: auto;
}
.footer {
width: auto;
}
.bodywrapper {
margin: 0;
}
.footer {
width: auto;
}
div.sphinxsidebar {
display: none;
}
}
div.sidebar_container, div.sidebar_container h1 {
}
div.sidebar_container h1 {
padding: 0;
margin: 0;
font-size: 350%;
line-height: 100%;
}
div.sidebar_container ul li {
padding: 2px 8px;
font-size: 0.9em;
}

7
docs/_themes/searx_theme/theme.conf vendored Normal file
View file

@ -0,0 +1,7 @@
[theme]
inherit = basic
stylesheet = style.css
pygments_style = flask_theme_support.FlaskyStyle
[options]
touch_icon =

94
docs/admin/api.rst Normal file
View file

@ -0,0 +1,94 @@
.. _adminapi:
Administration API
------------------
Get configuration data
~~~~~~~~~~~~~~~~~~~~~~
.. code:: sh
GET /config
Sample response
```````````````
.. code:: sh
{
"autocomplete": "",
"categories": [
"map",
"it",
"images",
],
"default_locale": "",
"default_theme": "oscar",
"engines": [
{
"categories": [
"map"
],
"enabled": true,
"name": "openstreetmap",
"shortcut": "osm"
},
{
"categories": [
"it"
],
"enabled": true,
"name": "arch linux wiki",
"shortcut": "al"
},
{
"categories": [
"images"
],
"enabled": true,
"name": "google images",
"shortcut": "goi"
},
{
"categories": [
"it"
],
"enabled": false,
"name": "bitbucket",
"shortcut": "bb"
},
],
"instance_name": "searx",
"locales": {
"de": "Deutsch (German)",
"en": "English",
"eo": "Esperanto (Esperanto)",
},
"plugins": [
{
"enabled": true,
"name": "HTTPS rewrite"
},
{
"enabled": false,
"name": "Vim-like hotkeys"
}
],
"safe_search": 0
}
Embed search bar
----------------
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
<form method="post" action="https://searx.me/">
<!-- search query --> <input type="text" name="q" />
<!-- categories --> <input type="hidden" name="categories" value="general,social media" />
<!-- language --> <input type="hidden" name="lang" value="all" />
<!-- locale --> <input type="hidden" name="locale" value="en" />
<!-- date filter --> <input type="hidden" name="time_range" value="month" />
</form>

114
docs/admin/filtron.rst Normal file
View file

@ -0,0 +1,114 @@
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.
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
-------------------------------
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)
.. code:: json
[
{
"name": "search request",
"filters": ["Param:q", "Path=^(/|/search)$"],
"interval": <time-interval-in-sec>,
"limit": <max-request-number-in-interval>,
"subrules": [
{
"name": "roboagent limit",
"interval": <time-interval-in-sec>,
"limit": <max-request-number-in-interval>,
"filters": ["Header:User-Agent=(curl|cURL|Wget|python-requests|Scrapy|FeedFetcher|Go-http-client)"],
"actions": [
{"name": "block",
"params": {"message": "Rate limit exceeded"}}
]
},
{
"name": "botlimit",
"limit": 0,
"stop": true,
"filters": ["Header:User-Agent=(Googlebot|bingbot|Baiduspider|yacybot|YandexMobileBot|YandexBot|Yahoo! Slurp|MJ12bot|AhrefsBot|archive.org_bot|msnbot|MJ12bot|SeznamBot|linkdexbot|Netvibes|SMTBot|zgrab|James BOT)"],
"actions": [
{"name": "block",
"params": {"message": "Rate limit exceeded"}}
]
},
{
"name": "IP limit",
"interval": <time-interval-in-sec>,
"limit": <max-request-number-in-interval>,
"stop": true,
"aggregations": ["Header:X-Forwarded-For"],
"actions": [
{"name": "block",
"params": {"message": "Rate limit exceeded"}}
]
},
{
"name": "rss/json limit",
"interval": <time-interval-in-sec>,
"limit": <max-request-number-in-interval>,
"stop": true,
"filters": ["Param:format=(csv|json|rss)"],
"actions": [
{"name": "block",
"params": {"message": "Rate limit exceeded"}}
]
},
{
"name": "useragent limit",
"interval": <time-interval-in-sec>,
"limit": <max-request-number-in-interval>,
"aggregations": ["Header:User-Agent"],
"actions": [
{"name": "block",
"params": {"message": "Rate limit exceeded"}}
]
}
]
}
]
Route request through filtron
-----------------------------
Filtron can be started using the following command:
.. code:: bash
$ filtron -rules rules.json
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.
.. code:: bash
location / {
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Scheme $scheme;
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.

21
docs/admin/morty.rst Normal file
View file

@ -0,0 +1,21 @@
How to setup result proxy
=========================
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 <https://github.com/asciimoo/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:
.. code:: yaml
result_proxy:
url : http://127.0.0.1:3000/
key : your_morty_proxy_key
``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.

42
docs/blog/admin.rst Normal file
View file

@ -0,0 +1,42 @@
Searx admin interface: manage your instance from your browser
=============================================================
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
:scale: 50 %
:alt: Screenshot of engine list
:align: center
:figclass: align-center
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.
Installation
------------
Installation guide can be found in the repository of searx-admin:
https://github.com/kvch/searx-admin#installation--usage
Acknowledgements
----------------
This development was sponsored by `NLnet Foundation`_.
.. _NLnet Foundation: https://nlnet.nl/
| Happy hacking.
| kvch // 2017.08.22 21:25

9
docs/blog/blog.rst Normal file
View file

@ -0,0 +1,9 @@
Blog
====
.. toctree::
:maxdepth: 1
python3
admin
intro-offline

65
docs/blog/intro-offline.rst Normal file
View file

@ -0,0 +1,65 @@
Preparation for 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.
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.
Example skeleton for the new engines:
.. code:: python
from subprocess import PIPE, Popen
categories = ['general']
offline = True
def init(settings):
pass
def search(query, params):
process = Popen(['ls', query], stdout=PIPE)
return_code = process.wait()
if return_code != 0:
raise RuntimeError('non-zero return code', return_code)
results = []
line = process.stdout.readline()
while line:
result = parse_line(line)
results.append(results)
line = process.stdout.readline()
return results
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: https://github.com/asciimoo/searx/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.
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
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.
Acknowledgement
---------------
This development was sponsored by `Search and Discovery Fund`_ of `NLnet Foundation`_ .
.. _Search and Discovery Fund: https://nlnet.nl/discovery
.. _NLnet Foundation: https://nlnet.nl/
| Happy hacking.
| kvch // 2019.10.21 17:03

54
docs/blog/python3.rst Normal file
View file

@ -0,0 +1,54 @@
Introducing Python3 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.
.. image:: searxpy3.png
:scale: 50 %
:alt: hurray
:align: center
How to run searx using Python3
------------------------------
Please make sure that you run at least Python3.5.
To run searx, first a Python3 virtualenv should be created. After entering the virtualenv,
dependencies must be installed. Then run searx with python3 instead of the usual python command.
.. code:: sh
virtualenv -p python3 venv3
source venv3/bin/activate
pip3 install -r requirements.txt
python3 searx/webapp.py
If you want to run searx using Python2.7, you don't have to do anything differently as before.
Fun facts
---------
- 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.
If you found bugs...
--------------------
...please open an issue on `GitHub`_. Make sure that you mention your Python version in your issue,
so we can investigate it properly.
.. _GitHub: https://github.com/asciimoo/searx/issues
Acknowledgement
---------------
This development was sponsored by `NLnet Foundation`_.
.. _NLnet Foundation: https://nlnet.nl/
| Happy hacking.
| kvch // 2017.05.13 22:57

BIN
docs/blog/searx-admin-engines.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 50 KiB

BIN
docs/blog/searxpy3.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 30 KiB

358
docs/conf.py Normal file
View file

@ -0,0 +1,358 @@
# -*- coding: utf-8 -*-
#
# searx documentation build configuration file, created by
# sphinx-quickstart on Tue Nov 17 17:12:13 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
import shlex
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.viewcode',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'searx'
copyright = u'2015-2019, Adam Tauber, Noémi Ványi'
author = u'Adam Tauber'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.12.0'
# The full version, including alpha/beta/rc tags.
release = '0.12.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
sys.path.append(os.path.abspath('_themes'))
html_theme_path = ['_themes']
html_theme = 'searx_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
#html_search_language = 'en'
# A dictionary with options for the search language support, empty by default.
# Now only 'ja' uses this config value
#html_search_options = {'type': 'default'}
# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#html_search_scorer = 'scorer.js'
# Output file base name for HTML help builder.
htmlhelp_basename = 'searxdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
# Latex figure (float) alignment
#'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'searx.tex', u'searx Documentation',
u'Adam Tauber', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'searx', u'searx Documentation',
[author], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'searx', u'searx Documentation',
author, 'searx', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# The basename for the epub file. It defaults to the project name.
#epub_basename = project
# The HTML theme for the epub output. Since the default themes are not optimized
# for small screen space, using the same theme for HTML and epub output is
# usually not wise. This defaults to 'epub', a theme designed to save visual
# space.
#epub_theme = 'epub'
# The language of the text. It defaults to the language option
# or 'en' if the language is not set.
#epub_language = ''
# The scheme of the identifier. Typical schemes are ISBN or URL.
#epub_scheme = ''
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#epub_identifier = ''
# A unique identification for the text.
#epub_uid = ''
# A tuple containing the cover image and cover page html template filenames.
#epub_cover = ()
# A sequence of (type, uri, title) tuples for the guide element of content.opf.
#epub_guide = ()
# HTML files that should be inserted before the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_pre_files = []
# HTML files shat should be inserted after the pages created by sphinx.
# The format is a list of tuples containing the path and title.
#epub_post_files = []
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# The depth of the table of contents in toc.ncx.
#epub_tocdepth = 3
# Allow duplicate toc entries.
#epub_tocdup = True
# Choose between 'default' and 'includehidden'.
#epub_tocscope = 'default'
# Fix unsupported image types using the Pillow.
#epub_fix_images = False
# Scale large images.
#epub_max_image_width = 0
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#epub_show_urls = 'inline'
# If false, no index is generated.
#epub_use_index = True

98
docs/dev/contribution_guide.rst Normal file
View file

@ -0,0 +1,98 @@
How to contribute
-----------------
Prime directives: Privacy, Hackability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Searx has two prime directives, privacy-by-design and hackability. The
hackability comes in three levels:
- support of search engines
- plugins to alter search behaviour
- hacking searx itself
Note the lack of "world domination" among the directives.
Searx has no intention of wide mass-adoption, rounded
corners, etc. The prime directive "privacy" deserves a separate
chapter, as it's quite uncommon unfortunately.
Privacy-by-design
^^^^^^^^^^^^^^^^^
Searx was born out of the need for a privacy-respecting search tool
which can be extended easily to maximize both its search and its
privacy protecting capabilities.
A few widely used features work differently or turned off by default or not implemented
at all as a consequence of privacy-by-design.
If a feature reduces the privacy preserving aspects of searx, it
should be switched off by default or should not implemented at all.
There are plenty of search engines already providing such features.
If a feature reduces the protection of searx, users must be
informed about the effect of choosing to enable it. Features
that protect privacy but differ from the expectations of the
user should also be explained.
Also, if you think that something works weird with searx,
it's might be because of the tool you use is designed in a way to interfere with
the privacy respect. Submitting a bugreport to the vendor of the tool that
misbehaves might be a good feedback to reconsider the disrespect to
its customers (e.g. GET vs POST requests in various browsers).
Remember the other prime directive of searx is to be hackable, so if the
above privacy concerns do not fancy you, simply fork it.
Happy hacking.
Code
~~~~
In order to submit a patch, please follow the steps below:
- Follow coding conventions.
- PEP8 standards apply, except the convention of line length
- Maximum line length is 120 characters
- 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.
- Add yourself to the AUTHORS file.
- Create a pull request.
For more help on getting started with searx development, see :ref:`devquickstart`.
Translation
~~~~~~~~~~~
Translation currently takes place on
`transifex <https://transifex.com/projects/p/searx>`__.
**Please, do not update translation files in the repo.**
Documentation
~~~~~~~~~~~~~
The documentation is built using Sphinx. So in order to be able to generate the required
files, you have to install it on your system. (It can be installed easily using pip.)
1. Checkout the gh-pages branch.
2. Edit the rst file you wish to update. Or create a new rst file and place it under the appropriate folder.
3. Build the documentation using Sphinx.
4. Add the updated and created files of these extension:
- .rst
- .html
- .txt
6. Create a pull request.

315
docs/dev/engine_overview.rst Normal file
View file

@ -0,0 +1,315 @@
Engine overview
===============
searx is a `metasearch-engine <https://en.wikipedia.org/wiki/Metasearch_engine>`__,
so it uses different search engines to provide 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
`searx/engines
<https://github.com/asciimoo/searx/tree/master/searx/engines>`__.
.. contents::
:depth: 3
general engine configuration
----------------------------
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
(normally ``settings.yml``). The arguments in the settings file override
the ones in the engine file.
It does not matter if an option is stored in the engine file or in the
settings. However, the standard way is the following:
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 |
+----------------------+-----------+-----------------------------------------+
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 |
+------------+----------+-----------------------------------------------+
overrides
~~~~~~~~~
A few of the options have default values in the engine, but are
often overwritten by the settings. If ``None`` is assigned to an option
in the engine file, it has to be redefined in the settings,
otherwise searx will not start with that engine.
The naming of overrides is arbitrary. But the recommended
overrides are the following:
+-----------------------+----------+----------------------------------------------------------------+
| argument | type | information |
+=======================+==========+================================================================+
| 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 |
+-----------------------+----------+----------------------------------------------------------------+
| language | string | ISO code of language and country like en\_US |
+-----------------------+----------+----------------------------------------------------------------+
| api\_key | string | api-key if required by engine |
+-----------------------+----------+----------------------------------------------------------------+
example code
~~~~~~~~~~~~
.. code:: python
# engine dependent config
categories = ['general']
paging = True
language_support = True
making a request
----------------
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
~~~~~~~~~~~~~~~~
These arguments can be used to construct the search query. Furthermore,
parameters with default value can be redefined for special purposes.
+----------------------+------------+------------------------------------------------------------------------+
| argument | type | default-value, information |
+======================+============+========================================================================+
| url | string | ``''`` |
+----------------------+------------+------------------------------------------------------------------------+
| method | string | ``'GET'`` |
+----------------------+------------+------------------------------------------------------------------------+
| headers | set | ``{}`` |
+----------------------+------------+------------------------------------------------------------------------+
| data | set | ``{}`` |
+----------------------+------------+------------------------------------------------------------------------+
| cookies | set | ``{}`` |
+----------------------+------------+------------------------------------------------------------------------+
| verify | boolean | ``True`` |
+----------------------+------------+------------------------------------------------------------------------+
| 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
~~~~~~~~~~~~~~~~
The function ``def request(query, params):`` always returns the
``params`` variable. Inside searx, the following paramters can be
used to specify a search 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 |
+------------+-----------+---------------------------------------------------------+
example code
~~~~~~~~~~~~
.. code:: python
# search-url
base_url = 'https://example.com/'
search_string = 'search?{query}&page={page}'
# do search-request
def request(query, params):
search_path = search_string.format(
query=urlencode({'q': query}),
page=params['pageno'])
params['url'] = base_url + search_path
return params
returned results
----------------
Searx is able to return results of different media-types.
Currently the following media-types are supported:
- default
- images
- videos
- torrent
- map
To set another media-type as default, the parameter
``template`` must be set to the desired type.
default
~~~~~~~
+--------------------+---------------------------------------------------------------------------------------------------------------+
| result-parameter | information |
+====================+===============================================================================================================+
| url | string, url of the result |
+--------------------+---------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+--------------------+---------------------------------------------------------------------------------------------------------------+
| content | string, general result-text |
+--------------------+---------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish |
+--------------------+---------------------------------------------------------------------------------------------------------------+
images
~~~~~~
to use this template, the parameter
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| result-parameter | information |
+====================+=======================================================================================================================================+
| template | is set to ``images.html`` |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| url | string, url to the result site |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| title | string, title of the result *(partly implemented)* |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| content | *(partly implemented)* |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish *(partly implemented)* |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| img\_src | string, url to the result image |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| thumbnail\_src | string, url to a small-preview image |
+--------------------+---------------------------------------------------------------------------------------------------------------------------------------+
videos
~~~~~~
+--------------------+--------------------------------------------------------------------------------------------------------------+
| result-parameter | information |
+====================+==============================================================================================================+
| template | is set to ``videos.html`` |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| url | string, url of the result |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| content | *(not implemented yet)* |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish |
+--------------------+--------------------------------------------------------------------------------------------------------------+
| thumbnail | string, url to a small-preview image |
+--------------------+--------------------------------------------------------------------------------------------------------------+
torrent
~~~~~~~
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| result-parameter | information |
+==================+=======================================================================================================================================+
| template | is set to ``torrent.html`` |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| url | string, url of the result |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| content | string, general result-text |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, time of publish *(not implemented yet)* |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| seed | int, number of seeder |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| leech | int, number of leecher |
+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| 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
~~~
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| result-parameter | information |
+=========================+==============================================================================================================+
| url | string, url of the result |
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| title | string, title of the result |
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| content | string, general result-text |
+-------------------------+--------------------------------------------------------------------------------------------------------------+
| publishedDate | `datetime.datetime <https://docs.python.org/2/library/datetime.html#datetime-objects>`__, 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 |
+-------------------------+--------------------------------------------------------------------------------------------------------------+

329
docs/dev/install/installation.rst Normal file
View file

@ -0,0 +1,329 @@
.. _installation:
Installation
============
.. contents::
:depth: 3
Basic installation
------------------
Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure to have enable universe repository.
Install packages:
.. code:: sh
sudo apt-get install git build-essential libxslt-dev python-dev python-virtualenv python-babel zlib1g-dev libffi-dev libssl-dev
Install searx:
.. code:: sh
cd /usr/local
sudo git clone https://github.com/asciimoo/searx.git
sudo useradd searx -d /usr/local/searx
sudo chown searx:searx -R /usr/local/searx
Install dependencies in a virtualenv:
.. code:: sh
sudo -u searx -i
cd /usr/local/searx
virtualenv searx-ve
. ./searx-ve/bin/activate
./manage.sh update_packages
Configuration
-------------
.. code:: sh
sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml
Edit searx/settings.yml if necessary.
Check
-----
Start searx:
.. code:: sh
python searx/webapp.py
Go to http://localhost:8888
If everything works fine, disable the debug option in settings.yml:
.. code:: sh
sed -i -e "s/debug : True/debug : False/g" searx/settings.yml
At this point searx is not demonized ; uwsgi allows this.
You can exit the virtualenv and the searx user bash (enter exit command
twice).
uwsgi
-----
Install packages:
.. code:: sh
sudo apt-get install uwsgi uwsgi-plugin-python
Create the configuration file /etc/uwsgi/apps-available/searx.ini with
this content:
::
[uwsgi]
# Who will run the code
uid = searx
gid = searx
# disable logging for privacy
disable-logging = true
# Number of workers (usually CPU count)
workers = 4
# The right granted on the created socket
chmod-socket = 666
# Plugin to use and interpretor config
single-interpreter = true
master = true
plugin = python
lazy-apps = true
enable-threads = true
# Module to import
module = searx.webapp
# Virtualenv and python path
virtualenv = /usr/local/searx/searx-ve/
pythonpath = /usr/local/searx/
chdir = /usr/local/searx/searx/
Activate the uwsgi application and restart:
.. code:: sh
cd /etc/uwsgi/apps-enabled
ln -s ../apps-available/searx.ini
/etc/init.d/uwsgi restart
Web server
----------
with nginx
^^^^^^^^^^
If nginx is not installed (uwsgi will not work with the package
nginx-light):
.. code:: sh
sudo apt-get install nginx
Hosted at /
"""""""""""
Create the configuration file /etc/nginx/sites-available/searx with this
content:
.. code:: nginx
server {
listen 80;
server_name searx.example.com;
root /usr/local/searx;
location / {
include uwsgi_params;
uwsgi_pass unix:/run/uwsgi/app/searx/socket;
}
}
Create a symlink to sites-enabled:
.. code:: sh
sudo ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx
Restart service:
.. code:: sh
sudo service nginx restart
sudo service uwsgi restart
from subdirectory URL (/searx)
""""""""""""""""""""""""""""""
Add this configuration in the server config file
/etc/nginx/sites-enabled/default:
.. code:: nginx
location = /searx { rewrite ^ /searx/; }
location /searx {
try_files $uri @searx;
}
location @searx {
uwsgi_param SCRIPT_NAME /searx;
include uwsgi_params;
uwsgi_modifier1 30;
uwsgi_pass unix:/run/uwsgi/app/searx/socket;
}
OR
using reverse proxy
(Please, note that reverse proxy advised to be used in case of single-user or low-traffic instances.)
.. code:: nginx
location /searx {
proxy_pass http://127.0.0.1:8888;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Scheme $scheme;
proxy_set_header X-Script-Name /searx;
proxy_buffering off;
}
Enable base\_url in searx/settings.yml
::
base_url : http://your.domain.tld/searx/
Restart service:
.. code:: sh
sudo service nginx restart
sudo service uwsgi restart
disable logs
~~~~~~~~~~~~
for better privacy you can disable nginx logs about searx.
how to proceed: below ``uwsgi_pass`` in
/etc/nginx/sites-available/default add
::
access_log /dev/null;
error_log /dev/null;
Restart service:
.. code:: sh
sudo service nginx restart
with apache
^^^^^^^^^^^
Add wsgi mod:
.. code:: sh
sudo apt-get install libapache2-mod-uwsgi
sudo a2enmod uwsgi
Add this configuration in the file /etc/apache2/apache2.conf:
.. code:: apache
<Location />
Options FollowSymLinks Indexes
SetHandler uwsgi-handler
uWSGISocket /run/uwsgi/app/searx/socket
</Location>
Note that if your instance of searx is not at the root, you should
change ``<Location />`` by the location of your instance, like
``<Location /searx>``.
Restart Apache:
.. code:: sh
sudo /etc/init.d/apache2 restart
disable logs
""""""""""""
For better privacy you can disable Apache logs.
WARNING: not tested
WARNING: you can only disable logs for the whole (virtual) server not
for a specific path.
Go back to /etc/apache2/apache2.conf and above ``<Location />`` add:
.. code:: apache
CustomLog /dev/null combined
Restart Apache:
.. code:: sh
sudo /etc/init.d/apache2 restart
How to update
-------------
.. code:: sh
cd /usr/local/searx
sudo -u searx -i
. ./searx-ve/bin/activate
git stash
git pull origin master
git stash apply
./manage.sh update_packages
sudo service uwsgi restart
Docker
------
Make sure you have installed Docker. For instance, you can deploy searx like this:
.. code:: sh
docker pull wonderfall/searx
docker run -d --name searx -p $PORT:8888 wonderfall/searx
Go to http://localhost:$PORT.
See https://hub.docker.com/r/wonderfall/searx/ for more informations.
It's also possible to build searx from the embedded Dockerfile.
.. code:: sh
git clone https://github.com/asciimoo/searx.git
cd searx
docker build -t whatever/searx .
References
==========
* https://about.okhin.fr/posts/Searx/ with some additions
* How to: `Setup searx in a couple of hours with a free SSL certificate <https://www.reddit.com/r/privacytoolsIO/comments/366kvn/how_to_setup_your_own_privacy_respecting_search/>`__

45
docs/dev/plugins.rst Normal file
View file

@ -0,0 +1,45 @@
Plugins
-------
Plugins can extend or replace functionality of various components of
searx.
Example plugin
~~~~~~~~~~~~~~
.. code:: python
name = 'Example plugin'
description = 'This plugin extends the suggestions with the word "example"'
default_on = False # disabled by default
js_dependencies = tuple() # optional, list of static js files
css_dependencies = tuple() # optional, list of static css files
# attach callback to the post search hook
# request: flask request object
# ctx: the whole local context of the post search hook
def post_search(request, ctx):
ctx['search'].suggestions.add('example')
return True
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.
Pre search hook
```````````````
Runs BEFORE the search request. Function to implement: ``pre_search``
Post search hook
````````````````
Runs AFTER the search request. Function to implement: ``post_search``
Result hook
```````````
Runs when a new result is added to the result list. Function to implement: ``on_result``

108
docs/dev/quickstart.rst Normal file
View file

@ -0,0 +1,108 @@
.. _devquickstart:
Development Quickstart
----------------------
This quickstart guide gets your environment set up with searx. Furthermore, it gives a
short introduction to the new manage.sh script.
How to setup your development environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, clone the source code of searx to the desired folder. In this case the source
is cloned to ~/myprojects/searx. Then create and activate the searx-ve
virtualenv and install the required packages using manage.sh.
.. code:: sh
cd ~/myprojects
git clone https://github.com/asciimoo/searx.git
cd searx
virtualenv searx-ve
. ./searx-ve/bin/activate
./manage.sh update_dev_packages
How to run tests
~~~~~~~~~~~~~~~~
Tests can be run using the manage.sh script.
Following tests and checks are available:
- Unit tests
- Selenium tests
- PEP8 validation
- Unit test coverage check
For example unit tests are run with the command below:
.. code:: sh
./manage.sh unit_tests
For further test options, please consult the help of the manage.sh script.
How to compile styles and javascript
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
How to build styles
^^^^^^^^^^^^^^^^^^^
Less is required to build the styles of searx. Less can be installed using either NodeJS or Apt.
.. code:: sh
sudo apt-get install nodejs
sudo npm install -g less
OR
.. code:: sh
sudo apt-get install node-less
After satisfying the requirements styles can be build using manage.sh
.. code:: sh
./manage.sh styles
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
Node has to be installed.
.. code:: sh
sudo apt-get install nodejs
sudo npm install -g grunt-cli
After installing grunt, the files can be built using the following command:
.. code:: sh
./manage.sh grunt_build
Tips for debugging/development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1. Turn on debug logging
Whether you are working on a new engine or trying to eliminate a bug, it is always a good idea
to turn on debug logging. When debug logging is enabled a stack trace appears,
instead of the cryptic ``Internal Server Error`` message. It can be turned on by setting
``debug: False`` to ``debug: True`` in settings.yml.
2. 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
containing these format fixes. This phase can be skipped if ``./manage.sh tests`` is run
locally before creating a PR.

204
docs/dev/search_api.rst Normal file
View file

@ -0,0 +1,204 @@
Search API
==========
The search supports both ``GET`` and ``POST``.
Furthermore, two enpoints ``/`` and ``/search`` are available for querying.
``GET /``
``GET /search``
Parameters
~~~~~~~~~~
.. code:: sh
q
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
Comma separated list, specifies the active search categories
Optional.
.. code:: sh
engines
Comma separated list, specifies the active search engines.
Optional.
.. code:: sh
lang
Code of the language.
Optional.
Default: ``all``
.. code:: sh
pageno
Search page number.
Optional.
Default: ``1``
.. code:: sh
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.
Optional.
Possible: ``json``, ``csv``, ``rss``
.. code:: sh
results_on_new_tab
Open search results on new tab.
Optional.
Default: ``0``
Possible: ``0``, ``1``
.. code:: sh
image_proxy
Proxy image results through searx.
Optional.
Default: ``False``
Possible: ``True``, ``False``
.. code:: sh
autocomplete
Service which completes words as you type.
Optional.
Default: empty
Possible: ``google``, ``dbpedia``, ``duckduckgo``, ``startpage``, ``wikipedia``
.. 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.
Optional.
Default: ``oscar``
Possible: ``oscar``, ``simple``, ``legacy``, ``pix-art``, ``courgette``
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.
.. code:: sh
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
List of enabled plugins.
Optional.
Default: ``HTTPS_rewrite``, ``Self_Informations``, ``Search_on_category_select``, ``Tracker_URL_remover``
Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select``
.. code:: sh
disabled_plugins
List of disabled plugins.
Optional.
Default: ``DOAI_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``
Possible: ``DOAI_rewrite``, ``HTTPS_rewrite``, ``Infinite_scroll``, ``Vim-like_hotkeys``, ``Self_Informations``, ``Tracker_URL_remover``, ``Search_on_category_select``
.. code:: sh
enabled_engines
List of enabled engines.
Optional.
Possible: all engines
.. code:: sh
disabled_engines
List of disabled engines.
Optional.
Possible: all engines

61
docs/dev/translation.rst Normal file
View file

@ -0,0 +1,61 @@
Translation
===========
Requirements
------------
* Transifex account
* Installed CLI tool of Transifex
Init Transifex project
----------------------
After installing ``transifex`` using pip, run the following command to initialize the project.
.. code:: shell
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.
Create a configuration file for ``tx`` named ``$HOME/.tx/config``.
.. code:: shell
[main]
host = https://www.transifex.com
[searx.messagespo]
file_filter = searx/translations/<lang>/LC_MESSAGES/messages.po
source_file = messages.pot
source_lang = en
type = PO
Then run ``tx set``:
.. code:: shell
tx set --auto-local -r searx.messagespo 'searx/translations/<lang>/LC_MESSAGES/messages.po' \
--source-lang en --type PO --source-file messages.pot --execute
Update translations
-------------------
To retrieve the latest translations, pull it from Transifex.
.. code:: shell
tx pull -a
Then check the new languages. If strings translated are not enough, delete those folders, because
those should not be compiled. Call the command below to compile the ``.po`` files.
.. code:: shell
pybabel compile -d searx/translations
After the compilation is finished commit the ``.po`` and ``.mo`` files and create a PR.

56
docs/index.rst Normal file
View file

@ -0,0 +1,56 @@
Welcome to searx
================
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.
Get started with searx by using one of the `public instances`_. If you don't trust anyone, you can set up your own, see :ref:`installation`.
.. _public instances: https://github.com/asciimoo/searx/wiki/Searx-instances
Features
--------
- Self hosted
- No user tracking
- No user profiling
- About 70 supported search engines
- Easy integration with any search engine
- Cookies are not used by default
- Secure, encrypted connections (HTTPS/SSL)
- Hosted by organisations, such as La Quadrature du Net, which promote digital rights
User documentation
------------------
.. toctree::
:maxdepth: 1
user/search_syntax
user/own-instance
Administrator documentation
---------------------------
.. toctree::
:maxdepth: 1
dev/install/installation
admin/api
admin/filtron
admin/morty
Developer documentation
-----------------------
.. toctree::
:maxdepth: 1
dev/quickstart
dev/contribution_guide
dev/engine_overview
dev/search_api
dev/plugins
dev/translation

BIN
docs/static/img/searx_logo_small.png vendored Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.3 KiB

43
docs/user/own-instance.rst Normal file
View file

@ -0,0 +1,43 @@
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.
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.
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:
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)
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.
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?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If someone uses a public instance, he/she has to trust the administrator of that 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.
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.
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
----------
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.

33
docs/user/search_syntax.rst Normal file
View file

@ -0,0 +1,33 @@
Search syntax
=============
Searx allows you to modify the default categories, engines and search
language via the search query.
Category/engine prefix: ``!``
Language prefix: ``:``
Prefix to add engines and categories to the currently selected
categories: ``?``
Abbrevations of the engines and languages are also accepted.
Engine/category modifiers are chainable and inclusive (e.g. with
`!it !ddg !wp qwer <https://searx.me/?q=%21it%20%21ddg%20%21wp%20qwer>`_
search in IT category **and** duckduckgo **and** wikipedia for ``qwer``).
See the `/preferences page <https://searx.me/preferences>`_ for the
list of engines, categories and languages.
Examples
~~~~~~~~
Search in wikipedia for ``qwer``:
`!wp qwer <https://searx.me/?q=%21wp%20qwer>`__ or
`!wikipedia qwer <https://searx.me/?q=%21wikipedia%20qwer>`_
Image search:
`!images Cthulhu <https://searx.me/?q=%21images%20Cthulhu>`_
Custom language in wikipedia:
`:hu !wp hackerspace <https://searx.me/?q=%3Ahu%20%21wp%20hackerspace>`_