summaryrefslogtreecommitdiff
path: root/docs/admin
diff options
context:
space:
mode:
Diffstat (limited to 'docs/admin')
-rw-r--r--docs/admin/arch_public.dot8
-rw-r--r--docs/admin/architecture.rst12
-rw-r--r--docs/admin/buildhosts.rst59
-rw-r--r--docs/admin/filtron.rst246
-rw-r--r--docs/admin/index.rst9
-rw-r--r--docs/admin/installation-apache.rst95
-rw-r--r--docs/admin/installation-docker.rst28
-rw-r--r--docs/admin/installation-nginx.rst334
-rw-r--r--docs/admin/installation-searx.rst90
-rw-r--r--docs/admin/installation-uwsgi.rst149
-rw-r--r--docs/admin/installation.rst360
-rw-r--r--docs/admin/morty.rst3
-rw-r--r--docs/admin/settings.rst8
-rw-r--r--docs/admin/update-searx.rst23
14 files changed, 976 insertions, 448 deletions
diff --git a/docs/admin/arch_public.dot b/docs/admin/arch_public.dot
index a46c96de3..5018225c3 100644
--- a/docs/admin/arch_public.dot
+++ b/docs/admin/arch_public.dot
@@ -4,11 +4,11 @@ digraph G {
edge [fontname="Sans"];
browser [label="Browser", shape=Mdiamond];
- rp [label="Reverse Proxy", href="url to configure reverse proxy"];
- filtron [label="Filtron", href="https://github.com/asciimoo/filtron"];
- morty [label="Morty", href="https://github.com/asciimoo/morty"];
+ rp [label="Reverse Proxy", href="https://asciimoo.github.io/searx/utils/filtron.sh.html#public-reverse-proxy"];
+ filtron [label="Filtron", href="https://asciimoo.github.io/searx/utils/filtron.sh.html"];
+ morty [label="Morty", href="https://asciimoo.github.io/searx/utils/morty.sh.html"];
static [label="Static files", href="url to configure static files"];
- uwsgi [label="uwsgi", href="url to configure uwsgi"]
+ uwsgi [label="uwsgi", href="https://asciimoo.github.io/searx/utils/searx.sh.html"]
searx1 [label="Searx #1"];
searx2 [label="Searx #2"];
searx3 [label="Searx #3"];
diff --git a/docs/admin/architecture.rst b/docs/admin/architecture.rst
index 7064a294b..fbc3bf483 100644
--- a/docs/admin/architecture.rst
+++ b/docs/admin/architecture.rst
@@ -4,17 +4,19 @@
Architecture
============
-.. sidebar:: Needs work!
+.. sidebar:: Tooling box
- This article needs some work / Searx is a collaborative effort. If you have
- any contribution, feel welcome to send us your :pull:`PR <../pulls>`, see
- :ref:`how to contribute`.
+ - :ref:`searx & uwsgi <searx.sh>`
+ - :ref:`filtron <filtron.sh>`
+ - :ref:`reverse proxy`
+ - :ref:`morty <morty.sh>`
Herein you will find some hints and suggestions about typical architectures of
searx infrastructures.
We start with a contribution from :pull:`@dalf <1776#issuecomment-567917320>`.
-It shows a *reference* setup for public searx instances.
+It shows a *reference* setup for public searx instances which can build up and
+maintained by the scripts from our :ref:`toolboxing`.
.. _arch public:
diff --git a/docs/admin/buildhosts.rst b/docs/admin/buildhosts.rst
index 5260da033..27784764f 100644
--- a/docs/admin/buildhosts.rst
+++ b/docs/admin/buildhosts.rst
@@ -4,13 +4,18 @@
Buildhosts
==========
+To get best results from build, its recommend to install additional packages
+on build hosts.
+
.. sidebar:: This article needs some work
If you have any contribution send us your :pull:`PR <../pulls>`, see
:ref:`how to contribute`.
-To get best results from build, its recommend to install additional packages
-on build hosts.
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
.. _docs build:
@@ -35,8 +40,17 @@ processing additional packages are needed. The XeTeX_ needed not only for PDF
creation, its also needed for :ref:`math` when HTML output is build.
To be able to do :ref:`sphinx:math-support` without CDNs, the math are rendered
-as images (``sphinx.ext.imgmath`` extension). If your docs build (``make
-docs``) shows warnings like this::
+as images (``sphinx.ext.imgmath`` extension).
+
+Here is the extract from the :origin:`docs/conf.py` file, setting math renderer
+to ``imgmath``:
+
+.. literalinclude:: ../conf.py
+ :language: python
+ :start-after: # sphinx.ext.imgmath setup
+ :end-before: # sphinx.ext.imgmath setup END
+
+If your docs build (``make docs``) shows warnings like this::
WARNING: dot(1) not found, for better output quality install \
graphviz from http://www.graphviz.org
@@ -47,8 +61,6 @@ docs``) shows warnings like this::
you need to install additional packages on your build host, to get better HTML
output.
-.. _system requirements:
-
.. tabs::
.. group-tab:: Ubuntu / debian
@@ -94,10 +106,35 @@ For PDF output you also need:
texlive-collection-fontsrecommended texlive-collection-latex \
dejavu-sans-fonts dejavu-serif-fonts dejavu-sans-mono-fonts
-.. _system requirements END:
+.. _sh lint:
-.. literalinclude:: ../conf.py
- :language: python
- :start-after: # sphinx.ext.imgmath setup
- :end-before: # sphinx.ext.imgmath setup END
+Lint shell scripts
+==================
+
+.. _ShellCheck: https://github.com/koalaman/shellcheck
+
+To lint shell scripts, we use ShellCheck_ - A shell script static analysis tool.
+
+.. SNIP sh lint requirements
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code-block:: sh
+
+ $ sudo apt install shellcheck
+
+ .. group-tab:: Arch Linux
+
+ .. code-block:: sh
+
+ $ sudo pacman -S shellcheck
+
+ .. group-tab:: Fedora / RHEL
+
+ .. code-block:: sh
+
+ $ sudo dnf install ShellCheck
+.. SNAP sh lint requirements
diff --git a/docs/admin/filtron.rst b/docs/admin/filtron.rst
index 07dcb9bc5..970ce25d2 100644
--- a/docs/admin/filtron.rst
+++ b/docs/admin/filtron.rst
@@ -1,18 +1,50 @@
+
+.. _searx filtron:
+
==========================
How to protect an instance
==========================
-Searx depens on external search services. To avoid the abuse of these services
+.. sidebar:: further reading
+
+ - :ref:`filtron.sh`
+ - :ref:`nginx searx site`
+
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+.. _filtron: https://github.com/asciimoo/filtron
+
+Searx depends 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. Filtron is just
+a middleware between your web server (nginx, apache, ...) and searx, we describe
+such infratructures in chapter: :ref:`architecture`.
+
+
+filtron & go
+============
+
+.. _Go: https://golang.org/
+.. _filtron README: https://github.com/asciimoo/filtron/blob/master/README.md
+
+Filtron needs Go_ installed. If Go_ is preinstalled, filtron_ is simply
+installed by ``go get`` package management (see `filtron README`_). If you use
+filtron as middleware, a more isolated setup is recommended. To simplify such
+an installation and the maintenance of, use our script :ref:`filtron.sh`.
Sample configuration of filtron
===============================
+.. sidebar:: Tooling box
+
+ - :origin:`/etc/filtron/rules.json <utils/templates/etc/filtron/rules.json>`
+
An example configuration can be find below. This configuration limits the access
of:
@@ -24,101 +56,103 @@ of:
.. code:: json
- [{
- "name":"search request",
- "filters":[
- "Param:q",
- "Path=^(/|/search)$"
- ],
- "interval":"<time-interval-in-sec (int)>",
- "limit":"<max-request-number-in-interval (int)>",
- "subrules":[
- {
- "name":"roboagent limit",
- "interval":"<time-interval-in-sec (int)>",
- "limit":"<max-request-number-in-interval (int)>",
- "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 (int)>",
- "limit":"<max-request-number-in-interval (int)>",
- "stop":true,
- "aggregations":[
- "Header:X-Forwarded-For"
- ],
- "actions":[
- {
- "name":"block",
- "params":{
- "message":"Rate limit exceeded"
- }
- }
- ]
- },
- {
- "name":"rss/json limit",
- "interval":"<time-interval-in-sec (int)>",
- "limit":"<max-request-number-in-interval (int)>",
- "stop":true,
- "filters":[
- "Param:format=(csv|json|rss)"
- ],
- "actions":[
- {
- "name":"block",
- "params":{
- "message":"Rate limit exceeded"
- }
- }
- ]
- },
- {
- "name":"useragent limit",
- "interval":"<time-interval-in-sec (int)>",
- "limit":"<max-request-number-in-interval (int)>",
- "aggregations":[
- "Header:User-Agent"
- ],
- "actions":[
- {
- "name":"block",
- "params":{
- "message":"Rate limit exceeded"
- }
- }
- ]
- }
- ]
- }]
-
-
+ [
+ { "name": "search request",
+ "filters": [
+ "Param:q",
+ "Path=^(/|/search)$"
+ ],
+ "interval": "<time-interval-in-sec (int)>",
+ "limit": "<max-request-number-in-interval (int)>",
+ "subrules": [
+ {
+ "name": "roboagent limit",
+ "interval": "<time-interval-in-sec (int)>",
+ "limit": "<max-request-number-in-interval (int)>",
+ "filters": [
+ "Header:User-Agent=(curl|cURL|Wget|python-requests|Scrapy|FeedFetcher|Go-http-client)"
+ ],
+ "actions": [
+ { "name": "log"},
+ { "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": "log"},
+ { "name": "block",
+ "params": {
+ "message": "Rate limit exceeded"
+ }
+ }
+ ]
+ },
+ {
+ "name": "IP limit",
+ "interval": "<time-interval-in-sec (int)>",
+ "limit": "<max-request-number-in-interval (int)>",
+ "stop": true,
+ "aggregations": [
+ "Header:X-Forwarded-For"
+ ],
+ "actions": [
+ { "name": "log"},
+ { "name": "block",
+ "params": {
+ "message": "Rate limit exceeded"
+ }
+ }
+ ]
+ },
+ {
+ "name": "rss/json limit",
+ "interval": "<time-interval-in-sec (int)>",
+ "limit": "<max-request-number-in-interval (int)>",
+ "stop": true,
+ "filters": [
+ "Param:format=(csv|json|rss)"
+ ],
+ "actions": [
+ { "name": "log"},
+ { "name": "block",
+ "params": {
+ "message": "Rate limit exceeded"
+ }
+ }
+ ]
+ },
+ {
+ "name": "useragent limit",
+ "interval": "<time-interval-in-sec (int)>",
+ "limit": "<max-request-number-in-interval (int)>",
+ "aggregations": [
+ "Header:User-Agent"
+ ],
+ "actions": [
+ { "name": "log"},
+ { "name": "block",
+ "params": {
+ "message": "Rate limit exceeded"
+ }
+ }
+ ]
+ }
+ ]
+ }
+ ]
+
+
+.. _filtron route request:
Route request through filtron
=============================
@@ -137,12 +171,14 @@ Use it along with ``nginx`` with the following example configuration.
.. code:: nginx
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/;
+ proxy_pass http://127.0.0.1:4004/;
+
+ 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;
}
Requests are coming from port 4004 going through filtron and then forwarded to
-port 8888 where a searx is being run.
+port 8888 where a searx is being run. For a complete setup see: :ref:`nginx
+searx site`.
diff --git a/docs/admin/index.rst b/docs/admin/index.rst
index b3c7f5119..c708c4ffa 100644
--- a/docs/admin/index.rst
+++ b/docs/admin/index.rst
@@ -3,9 +3,16 @@ Administrator documentation
===========================
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
+ :caption: Contents
installation
+ installation-searx
+ installation-uwsgi
+ installation-nginx
+ installation-apache
+ installation-docker
+ update-searx
settings
api
architecture
diff --git a/docs/admin/installation-apache.rst b/docs/admin/installation-apache.rst
new file mode 100644
index 000000000..8c6228380
--- /dev/null
+++ b/docs/admin/installation-apache.rst
@@ -0,0 +1,95 @@
+.. _installation apache:
+
+===================
+Install with apache
+===================
+
+.. sidebar:: public to the internet?
+
+ If your searx instance is public, stop here and first install :ref:`filtron
+ reverse proxy <filtron.sh>` and :ref:`result proxy morty <morty.sh>`, see
+ :ref:`installation scripts`.
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+Add wsgi mod
+============
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ sudo -H apt-get install libapache2-mod-uwsgi
+ sudo -H a2enmod uwsgi
+
+Add this configuration in the file ``/etc/apache2/apache2.conf``. To limit
+acces to your intranet replace ``Allow from all`` directive and replace
+``192.168.0.0/16`` with your subnet IP/class.
+
+.. _inranet apache site:
+
+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>``:
+
+.. code:: apache
+
+ # CustomLog /dev/null combined
+
+ <IfModule mod_uwsgi.c>
+
+ <Location />
+
+ Options FollowSymLinks Indexes
+ SetHandler uwsgi-handler
+ uWSGISocket /run/uwsgi/app/searx/socket
+
+ Order deny,allow
+ Deny from all
+ # Allow from fd00::/8 192.168.0.0/16 fe80::/10 127.0.0.0/8 ::1
+ Allow from all
+
+ </Location>
+
+ </IfModule>
+
+Enable apache mod_uwsgi and restart apache:
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ a2enmod uwsgi
+ sudo -H systemctl restart apache2
+
+disable logs
+============
+
+For better privacy you can disable Apache logs. Go back to
+``/etc/apache2/apache2.conf`` :ref:`[example] <inranet apache site>` and above
+``<Location />`` activate directive:
+
+.. code:: apache
+
+ CustomLog /dev/null combined
+
+Restart apache:
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ sudo -H systemctl restart apache2
+
+.. warning::
+
+ You can only disable logs for the whole (virtual) server not for a specific
+ path.
diff --git a/docs/admin/installation-docker.rst b/docs/admin/installation-docker.rst
new file mode 100644
index 000000000..340e66319
--- /dev/null
+++ b/docs/admin/installation-docker.rst
@@ -0,0 +1,28 @@
+.. _installation docker:
+
+===================
+Docker installation
+===================
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+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 .
diff --git a/docs/admin/installation-nginx.rst b/docs/admin/installation-nginx.rst
new file mode 100644
index 000000000..2097d7daf
--- /dev/null
+++ b/docs/admin/installation-nginx.rst
@@ -0,0 +1,334 @@
+.. _installation nginx:
+
+==================
+Install with nginx
+==================
+
+.. _nginx:
+ https://docs.nginx.com/nginx/admin-guide/
+.. _nginx server configuration:
+ https://docs.nginx.com/nginx/admin-guide/web-server/web-server/#setting-up-virtual-servers
+.. _nginx beginners guide:
+ http://nginx.org/en/docs/beginners_guide.html
+.. _Getting Started wiki:
+ https://www.nginx.com/resources/wiki/start/
+.. _uWSGI support from nginx:
+ https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
+.. _uwsgi_params:
+ https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html#configuring-nginx
+.. _SCRIPT_NAME:
+ https://werkzeug.palletsprojects.com/en/1.0.x/wsgi/#werkzeug.wsgi.get_script_name
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+
+The nginx HTTP server
+=====================
+
+If nginx_ is not installed (uwsgi will not work with the package nginx-light)
+install it now.
+
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ sudo -H apt-get install nginx
+
+ .. group-tab:: Arch Linux
+
+ .. code-block:: sh
+
+ sudo -H pacman -S nginx-mainline
+ sudo -H systemctl enable nginx
+ sudo -H systemctl start nginx
+
+ .. group-tab:: Fedora / RHEL
+
+ .. code-block:: sh
+
+ sudo -H dnf install nginx
+ sudo -H systemctl enable nginx
+ sudo -H systemctl start nginx
+
+Now at http://localhost you should see a *Welcome to nginx!* page, on Fedora you
+see a *Fedora Webserver - Test Page*. The test page comes from the default
+`nginx server configuration`_:
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ less /etc/nginx/nginx.conf
+
+ there is a line including site configurations from:
+
+ .. code:: nginx
+
+ include /etc/nginx/sites-enabled/*;
+
+ .. group-tab:: Arch Linux
+
+ .. code-block:: sh
+
+ less /etc/nginx/nginx.conf
+
+ in there is a configuration section named ``server``:
+
+ .. code-block:: nginx
+
+ server {
+ listen 80;
+ server_name localhost;
+ # ...
+ }
+
+ .. group-tab:: Fedora / RHEL
+
+ .. code-block:: sh
+
+ less /etc/nginx/nginx.conf
+
+ there is a line including site configurations from:
+
+ .. code:: nginx
+
+ include /etc/nginx/conf.d/*.conf;
+
+.. _nginx searx site:
+
+A nginx searx site
+==================
+
+.. sidebar:: public to the internet?
+
+ If your searx instance is public, stop here and first install :ref:`filtron
+ reverse proxy <filtron.sh>` and :ref:`result proxy morty <morty.sh>`, see
+ :ref:`installation scripts`.
+
+Now you have to create a configuration for the searx site. If nginx_ is new to
+you, the `nginx beginners guide`_ is a good starting point and the `Getting
+Started wiki`_ is always a good resource *to keep in the pocket*.
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ Create configuration at ``/etc/nginx/sites-available/searx`` and place a
+ symlink to sites-enabled:
+
+ .. code:: sh
+
+ sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx
+
+ .. group-tab:: Arch Linux
+
+ In the ``/etc/nginx/nginx.conf`` file, replace the configuration section
+ named ``server``.
+
+ .. group-tab:: Fedora / RHEL
+
+ Create configuration at ``/etc/nginx/conf.d/searx`` and place a
+ symlink to sites-enabled:
+
+.. tabs::
+
+ .. group-tab:: searx via filtron plus morty
+
+ Use this setup, if your instance is public to the internet, compare
+ figure: :ref:`architecture <arch public>`. Configure a reverse proxy for
+ :ref:`filtron <filtron.sh>`, listening on *localhost 4004* (:ref:`filtron
+ route request`):
+
+ .. code:: nginx
+
+ location / {
+ proxy_pass http://127.0.0.1:4004/;
+
+ 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;
+ }
+
+
+ Configure reverse proxy for :ref:`morty <searx morty>`, listening on
+ *localhost 3000*:
+
+ .. code:: nginx
+
+ location /morty {
+ proxy_pass http://127.0.0.1:3000/;
+
+ 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;
+ }
+
+ Note that reverse proxy advised to be used in case of single-user or
+ low-traffic instances. For a fully result proxification add :ref:`morty's
+ <searx morty>` **public URL** to your :origin:`searx/settings.yml`:
+
+ .. code:: yaml
+
+ result_proxy:
+ # replace example.org with your server's public name
+ url : https://example.org/
+
+
+ .. group-tab:: proxy or uWSGI
+
+ Be warned, with this setup, your instance isn't :ref:`protected <searx
+ filtron>`. Nevertheless it is good enough for intranet usage and it is a
+ excellent example of; *how different services can be set up*. The next
+ example shows a reverse proxy configuration wrapping the :ref:`searx-uWSGI
+ application <uwsgi configuration>`, listening on ``http =
+ 127.0.0.1:8888``.
+
+ .. code:: nginx
+
+ location / {
+ 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;
+ }
+
+ Alternatively you can use the `uWSGI support from nginx`_ via unix
+ sockets. For socket communication, you have to activate ``socket =
+ /run/uwsgi/app/searx/socket`` and comment out the ``http =
+ 127.0.0.1:8888`` configuration in your :ref:`uwsgi ini file <uwsgi
+ configuration>`.
+
+ The example shows a nginx virtual ``server`` configuration, listening on
+ port 80 (IPv4 and IPv6 http://[::]:80). The uWSGI app is configured at
+ location ``/`` by importing the `uwsgi_params`_ and passing requests to
+ the uWSGI socket (``uwsgi_pass``). The ``server``\'s root points to the
+ :ref:`searx-src clone <searx-src>` and wraps directly the
+ :origin:`searx/static/` content at ``location /static``.
+
+ .. code:: nginx
+
+ server {
+ # replace example.org with your server's public name
+ server_name example.org;
+
+ listen 80;
+ listen [::]:80;
+
+ location / {
+ include uwsgi_params;
+ uwsgi_pass unix:/run/uwsgi/app/searx/socket;
+ }
+
+ root /usr/local/searx/searx-src/searx;
+ location /static { }
+ }
+
+ If not already exists, create a folder for the unix sockets, which can be
+ used by the searx account:
+
+ .. code:: bash
+
+ mkdir -p /run/uwsgi/app/searx/
+ sudo -H chown -R searx:searx /run/uwsgi/app/searx/
+
+ .. group-tab:: subdirectory URL
+
+ Be warned, with these setups, your instance isn't :ref:`protected <searx
+ filtron>`. The examples are just here to demonstrate how to export the
+ searx application from a subdirectory URL ``https://example.org/searx/``.
+
+ .. 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;
+ }
+
+ location /searx/static {
+ alias /usr/local/searx/searx-src/searx/static;
+ }
+
+ The ``X-Script-Name /searx`` is needed by the searx implementation to
+ calculate relative URLs correct. The next example shows a uWSGI
+ configuration. Since there are no HTTP headers in a (u)WSGI protocol, the
+ value is shipped via the SCRIPT_NAME_ in the WSGI environment.
+
+ .. code:: nginx
+
+ location /searx/static {
+ alias /usr/local/searx/searx-src/searx;
+ }
+
+ location /searx {
+ uwsgi_param SCRIPT_NAME /searx;
+ include uwsgi_params;
+ uwsgi_pass unix:/run/uwsgi/app/searx/socket;
+ }
+
+ For searx to work correctly the ``base_url`` must be set in the
+ :origin:`searx/settings.yml`.
+
+ .. code:: yaml
+
+ server:
+ # replace example.org with your server's public name
+ base_url : https://example.org/searx/
+
+
+Restart service:
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ sudo -H systemctl restart nginx
+ sudo -H service uwsgi restart searx
+
+ .. group-tab:: Arch Linux
+
+ .. code:: sh
+
+ sudo -H systemctl restart nginx
+ sudo -H systemctl restart uwsgi@searx
+
+ .. group-tab:: Fedora
+
+ .. code:: sh
+
+ sudo -H systemctl restart nginx
+ sudo -H touch /etc/uwsgi.d/searx.ini
+
+
+Disable logs
+============
+
+For better privacy you can disable nginx logs in ``/etc/nginx/nginx.conf``.
+
+.. code:: nginx
+
+ http {
+ # ...
+ access_log /dev/null;
+ error_log /dev/null;
+ # ...
+ }
diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst
new file mode 100644
index 000000000..91891d85c
--- /dev/null
+++ b/docs/admin/installation-searx.rst
@@ -0,0 +1,90 @@
+.. _installation basic:
+
+=========================
+Step by step installation
+=========================
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+Step by step installation with virtualenv. For Ubuntu, be sure to have enable
+universe repository.
+
+.. _install packages:
+
+Install packages
+================
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START distro-packages
+ :end-before: END distro-packages
+
+.. hint::
+
+ This installs also the packages needed by :ref:`searx uwsgi`
+
+Create user
+===========
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START create user
+ :end-before: END create user
+
+.. _searx-src:
+
+install searx & dependencies
+============================
+
+Start a interactive shell from new created user and clone searx:
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START clone searx
+ :end-before: END clone searx
+
+In the same shell create *virtualenv*:
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START create virtualenv
+ :end-before: END create virtualenv
+
+To install searx's dependencies, exit the searx *bash* session you opened above
+and restart a new. Before install, first check if your *virualenv* was sourced
+from the login (*~/.profile*):
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START manage.sh update_packages
+ :end-before: END manage.sh update_packages
+
+.. tip::
+
+ Open a second terminal for the configuration tasks and left the ``(searx)$``
+ terminal open for the tasks below.
+
+Configuration
+==============
+
+Create a copy of the :origin:`searx/settings.yml` configuration file in system's
+*/etc* folder. Configure like shown below -- replace ``searx@\$(uname -n)`` with
+a name of your choice -- *and/or* edit ``/etc/searx/settings.yml`` if necessary.
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START searx config
+ :end-before: END searx config
+
+Check
+=====
+
+To check your searx setup, optional enable debugging and start the *webapp*.
+Searx looks at the exported environment ``$SEARX_SETTINGS_PATH`` for a
+configuration file.
+
+.. include:: ../../build/docs/includes/searx.rst
+ :start-after: START check searx installation
+ :end-before: END check searx installation
+
+If everything works fine, hit ``[CTRL-C]`` to stop the *webapp* and disable the
+debug option in ``settings.yml``. You can now exit searx user bash (enter exit
+command twice). At this point searx is not demonized; uwsgi allows this.
+
diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst
new file mode 100644
index 000000000..67a8e127a
--- /dev/null
+++ b/docs/admin/installation-uwsgi.rst
@@ -0,0 +1,149 @@
+.. _searx uwsgi:
+
+=====
+uwsgi
+=====
+
+.. sidebar:: further read
+
+ - `systemd.unit`_
+ - `uWSGI Emperor`_
+
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+
+.. _systemd.unit: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
+.. _One service per app in systemd:
+ https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html#one-service-per-app-in-systemd
+.. _uWSGI Emperor:
+ https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
+.. _uwsgi ini file:
+ https://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#ini-files
+.. _systemd unit template:
+ http://0pointer.de/blog/projects/instances.html
+
+
+Origin uWSGI
+============
+
+How uWSGI is implemented by distributors is different. uWSGI itself
+recommend two methods
+
+`systemd.unit`_ template files as described here `One service per app in systemd`_.
+
+ There is one `systemd unit template`_ and one `uwsgi ini file`_ per uWSGI-app
+ placed at dedicated locations. Take archlinux and a searx.ini as example::
+
+ unit template --> /usr/lib/systemd/system/uwsgi@.service
+ uwsgi ini files --> /etc/uwsgi/searx.ini
+
+ The searx app can be maintained as know from common systemd units::
+
+ systemctl enable uwsgi@searx
+ systemctl start uwsgi@searx
+ systemctl restart uwsgi@searx
+ systemctl stop uwsgi@searx
+
+The `uWSGI Emperor`_ mode which fits for maintaining a large range of uwsgi apps.
+
+ The Emperor mode is a special uWSGI instance that will monitor specific
+ events. The Emperor mode (service) is started by a (common, not template)
+ systemd unit. The Emperor service will scan specific directories for `uwsgi
+ ini file`_\s (also know as *vassals*). If a *vassal* is added, removed or the
+ timestamp is modified, a corresponding action takes place: a new uWSGI
+ instance is started, reload or stopped. Take Fedora and a searx.ini as
+ example::
+
+ to start a new searx instance create --> /etc/uwsgi.d/searx.ini
+ to reload the instance edit timestamp --> touch /etc/uwsgi.d/searx.ini
+ to stop instance remove ini --> rm /etc/uwsgi.d/searx.ini
+
+Distributors
+============
+
+The `uWSGI Emperor`_ mode and `systemd unit template`_ is what the distributors
+mostly offer their users, even if they differ in the way they implement both
+modes and their defaults. Another point they might differ is the packaging of
+plugins (if so, compare :ref:`install packages`) and what the default python
+interpreter is (python2 vs. python3).
+
+Fedora starts a Emperor by default, while archlinux does not start any uwsgi
+service by default. Worth to know; debian (ubuntu) follow a complete different
+approach. *debian*: your are familiar with the apache infrastructure? .. they
+do similar for the uWSGI infrastructure (with less comfort), the folders are::
+
+ /etc/uwsgi/apps-available/
+ /etc/uwsgi/apps-enabled/
+
+The `uwsgi ini file`_ is enabled by a symbolic link::
+
+ ln -s /etc/uwsgi/apps-available/searx.ini /etc/uwsgi/apps-enabled/
+
+From debian's documentation (``/usr/share/doc/uwsgi/README.Debian.gz``): You
+could control specific instance(s) by issuing::
+
+ service uwsgi <command> <confname> <confname> ...
+
+ sudo -H service uwsgi start searx
+ sudo -H service uwsgi stop searx
+
+My experience is, that this command is a bit buggy.
+
+.. _uwsgi configuration:
+
+Alltogether
+===========
+
+Create the configuration ini-file according to your distribution (see below) and
+restart the uwsgi application.
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. literalinclude:: ../../build/docs/includes/searx.rst
+ :start-after: START searx uwsgi-description ubuntu-20.04
+ :end-before: END searx uwsgi-description ubuntu-20.04
+
+
+ .. group-tab:: Arch Linux
+
+ .. literalinclude:: ../../build/docs/includes/searx.rst
+ :start-after: START searx uwsgi-description arch
+ :end-before: END searx uwsgi-description arch
+
+
+ .. group-tab:: Fedora / RHEL
+
+ .. literalinclude:: ../../build/docs/includes/searx.rst
+ :start-after: START searx uwsgi-description fedora
+ :end-before: END searx uwsgi-description fedora
+
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. literalinclude:: ../../build/docs/includes/searx.rst
+ :language: ini
+ :start-after: START searx uwsgi-appini ubuntu-20.04
+ :end-before: END searx uwsgi-appini ubuntu-20.04
+
+ .. group-tab:: Arch Linux
+
+ .. literalinclude:: ../../build/docs/includes/searx.rst
+ :language: ini
+ :start-after: START searx uwsgi-appini arch
+ :end-before: END searx uwsgi-appini arch
+
+ .. group-tab:: Fedora / RHEL
+
+ .. literalinclude:: ../../build/docs/includes/searx.rst
+ :language: ini
+ :start-after: START searx uwsgi-appini fedora
+ :end-before: END searx uwsgi-appini fedora
+
+
diff --git a/docs/admin/installation.rst b/docs/admin/installation.rst
index 15800fc01..25d7f0ea9 100644
--- a/docs/admin/installation.rst
+++ b/docs/admin/installation.rst
@@ -4,346 +4,64 @@
Installation
============
-.. contents::
- :depth: 3
+*You're spoilt for choice*, choose your preferred method of installation.
-Basic installation
-==================
+- :ref:`installation docker`
+- :ref:`installation scripts`
+- :ref:`installation basic`
-Step by step installation for Debian/Ubuntu with virtualenv. For Ubuntu, be sure
-to have enable universe repository.
+The :ref:`installation basic` is good enough for intranet usage and it is a
+excellent illustration of *how a searx instance is build up*. If you place your
+instance public to the internet you should really consider to install a
+:ref:`filtron reverse proxy <filtron.sh>` and for privacy a :ref:`result proxy
+<morty.sh>` is mandatory.
-Install packages:
+Therefore, if you do not have any special preferences, its recommend to use the
+:ref:`installation docker` or the `Installation scripts`_ from our :ref:`tooling
+box <toolboxing>` as described below.
-.. code:: sh
+.. _installation scripts:
- $ sudo -H apt-get install \
- git build-essential libxslt-dev \
- python-dev python-virtualenv python-babel \
- zlib1g-dev libffi-dev libssl-dev
+Installation scripts
+====================
-Install searx:
+The following will install a setup as shown in :ref:`architecture`. First you
+need to get a clone. The clone is only needed for the installation procedure
+and some maintenance tasks (alternatively you can create your own fork).
-.. code:: sh
+.. code:: bash
- cd /usr/local
- sudo -H git clone https://github.com/asciimoo/searx.git
- sudo -H useradd searx -d /usr/local/searx
- sudo -H chown searx:searx -R /usr/local/searx
+ $ cd ~/Download
+ $ git clone https://github.com/asciimoo/searx searx
+ $ cd searx
-Install dependencies in a virtualenv:
+.. hint::
-.. code:: sh
+ The *tooling box* is not yet merged into `asciimoo/searx master
+ <https://github.com/asciimoo/searx>`_. As long as PR is not merged, you need
+ to merge the PR into your local clone (see below). The discussion takes
+ place in :pull:`1803`. To merge the :pull:`1803` in your local branch use:
- cd /usr/local/searx
- sudo -H -u searx -i
+ .. code:: bash
-.. code:: sh
+ $ git pull origin refs/pull/1803/head
- (searx)$ virtualenv searx-ve
- (searx)$ . ./searx-ve/bin/activate
- (searx)$ ./manage.sh update_packages
+**Install** :ref:`searx service <searx.sh>`
-Configuration
-==============
+This installs searx as described in :ref:`installation basic`.
-.. code:: sh
+.. code:: bash
- sed -i -e "s/ultrasecretkey/`openssl rand -hex 16`/g" searx/settings.yml
+ $ sudo -H ./utils/searx.sh install all
-Edit searx/settings.yml if necessary.
+**Install** :ref:`filtron reverse proxy <filtron.sh>`
-Check
-=====
+.. code:: bash
-Start searx:
+ $ sudo -H ./utils/filtron.sh install all
-.. code:: sh
+**Install** :ref:`result proxy <morty.sh>`
- python searx/webapp.py
+.. code:: bash
-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 -H apt-get install \
- uwsgi uwsgi-plugin-python
-
-Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this
-content:
-
-.. code:: ini
-
- [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
-
- # Support running the module from a webserver subdirectory.
- route-run = fixpathinfo:
-
- # 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 -H 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/searx;
-
- location /static {
- }
-
- location / {
- include uwsgi_params;
- uwsgi_pass unix:/run/uwsgi/app/searx/socket;
- }
- }
-
-Create a symlink to sites-enabled:
-
-.. code:: sh
-
- sudo -H ln -s /etc/nginx/sites-available/searx /etc/nginx/sites-enabled/searx
-
-Restart service:
-
-.. code:: sh
-
- sudo -H service nginx restart
- sudo -H service uwsgi restart
-
-from subdirectory URL (/searx)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Add this configuration in the server config file
-``/etc/nginx/sites-enabled/default``:
-
-.. code:: nginx
-
- location /searx/static {
- alias /usr/local/searx/searx/static;
- }
-
- location /searx {
- uwsgi_param SCRIPT_NAME /searx;
- include uwsgi_params;
- 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/static {
- alias /usr/local/searx/searx/static;
- }
-
- 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``
-
-.. code:: yaml
-
- base_url : http://your.domain.tld/searx/
-
-Restart service:
-
-.. code:: sh
-
- sudo -H service nginx restart
- sudo -H 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:
-
-.. code:: nginx
-
- access_log /dev/null;
- error_log /dev/null;
-
-Restart service:
-
-.. code:: sh
-
- sudo -H service nginx restart
-
-with apache
------------
-
-Add wsgi mod:
-
-.. code:: sh
-
- sudo -H apt-get install libapache2-mod-uwsgi
- sudo -H 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 -H /etc/init.d/apache2 restart
-
-disable logs
-~~~~~~~~~~~~
-
-For better privacy you can disable Apache logs.
-
-.. 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 -H /etc/init.d/apache2 restart
-
-How to update
-=============
-
-.. code:: sh
-
- cd /usr/local/searx
- sudo -H -u searx -i
-
-.. code:: sh
-
- (searx)$ . ./searx-ve/bin/activate
- (searx)$ git stash
- (searx)$ git pull origin master
- (searx)$ git stash apply
- (searx)$ ./manage.sh update_packages
-
-.. code:: sh
-
- sudo -H 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/>`__
+ $ sudo -H ./utils/morty.sh install all
diff --git a/docs/admin/morty.rst b/docs/admin/morty.rst
index 7d7b34492..48ff5b9c4 100644
--- a/docs/admin/morty.rst
+++ b/docs/admin/morty.rst
@@ -1,3 +1,6 @@
+
+.. _searx morty:
+
=========================
How to setup result proxy
=========================
diff --git a/docs/admin/settings.rst b/docs/admin/settings.rst
index 0bfdcc6cb..59a406a28 100644
--- a/docs/admin/settings.rst
+++ b/docs/admin/settings.rst
@@ -4,11 +4,17 @@
``settings.yml``
================
+This page describe the options possibilities of the :origin:`searx/settings.yml`
+file.
+
.. sidebar:: Further reading ..
- :ref:`search API`
-This page describe the options possibilities of the settings.yml file.
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
.. _settings global:
diff --git a/docs/admin/update-searx.rst b/docs/admin/update-searx.rst
new file mode 100644
index 000000000..c74c9568a
--- /dev/null
+++ b/docs/admin/update-searx.rst
@@ -0,0 +1,23 @@
+.. _update searx:
+
+=============
+How to update
+=============
+
+.. code:: sh
+
+ sudo -H -u searx -i
+ (searx)$ git stash
+ (searx)$ git pull origin master
+ (searx)$ git stash apply
+ (searx)$ ./manage.sh update_packages
+
+Restart uwsgi:
+
+.. tabs::
+
+ .. group-tab:: Ubuntu / debian
+
+ .. code:: sh
+
+ sudo -H systemctl restart uwsgi
generated by cgit v1.2.3 (git 2.25.1) at 2026-03-18 00:19:47 +0000