Icycoide/searxng
1
0
Fork 1
mirror of https://github.com/searxng/searxng.git synced 2025-08-03 10:32:21 +02:00
Code Issues Projects Releases Packages Wiki Activity

[doc] update documentation of the installation procedures

Browse source 
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
This commit is contained in:
Markus Heiser 2022-06-14 10:02:50 +02:00
parent 782f73540e
commit ed8a169029
34 changed files with 967 additions and 1433 deletions
Download patch file Download diff file Expand all files Collapse all files

206
docs/admin/installation-uwsgi.rst
View file

@ -1,7 +1,7 @@
.. _searxng uwsgi:
=====
uwsgi
uWSGI
=====
.. sidebar:: further reading
@ -29,37 +29,51 @@ uwsgi
Origin uWSGI
============
How uWSGI is implemented by distributors is different. uWSGI itself
recommend two methods
.. _Tyrant mode:
https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html#tyrant-mode-secure-multi-user-hosting
`systemd.unit`_ template files as described here `One service per app in systemd`_.
How uWSGI is implemented by distributors varies. The uWSGI project itself
recommends two methods:
There is one `systemd unit template`_ and one `uwsgi ini file`_ per uWSGI-app
placed at dedicated locations. Take archlinux and a searxng.ini as example::
1. `systemd.unit`_ template file as described here `One service per app in systemd`_:
unit template --> /usr/lib/systemd/system/uwsgi@.service
uwsgi ini files --> /etc/uwsgi/searxng.ini
There is one `systemd unit template`_ on the system installed and one `uwsgi
ini file`_ per uWSGI-app placed at dedicated locations. Take archlinux and a
``searxng.ini`` as example::
The SearXNG app can be maintained as know from common systemd units::
systemd template unit: /usr/lib/systemd/system/uwsgi@.service
contains: [Service]
ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/%I.ini
systemctl enable uwsgi@searx
systemctl start uwsgi@searx
systemctl restart uwsgi@searx
systemctl stop uwsgi@searx
SearXNG application: /etc/uwsgi/searxng.ini
links to: /etc/uwsgi/apps-available/searxng.ini
The `uWSGI Emperor`_ mode which fits for maintaining a large range of uwsgi apps.
The SearXNG app (template ``/etc/uwsgi/%I.ini``) can be maintained as known
from common systemd units:
.. code:: sh
$ systemctl enable uwsgi@searxng
$ systemctl start uwsgi@searxng
$ systemctl restart uwsgi@searxng
$ systemctl stop uwsgi@searxng
2. The `uWSGI Emperor`_ which fits for maintaining a large range of uwsgi
apps and there is a `Tyrant mode`_ to secure multi-user hosting.
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 searxng.ini as
example::
events. The Emperor mode (the 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 ``searxng.ini`` as example::
to install & start SearXNG instance create --> /etc/uwsgi.d/searxng.ini
to reload the instance edit timestamp --> touch /etc/uwsgi.d/searxng.ini
to stop instance remove ini --> rm /etc/uwsgi.d/searxng.ini
to start a new SearXNG instance create --> /etc/uwsgi.d/searxng.ini
to reload the instance edit timestamp --> touch /etc/uwsgi.d/searxng.ini
to stop instance remove ini --> rm /etc/uwsgi.d/searxng.ini
Distributors
============
@ -70,10 +84,22 @@ 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::
While archlinux does not start a uWSGI service by default, Fedora (RHEL) starts
a Emperor in `Tyrant mode`_ by default (you should have read :ref:`uWSGI Tyrant
mode pitfalls`). Worth to know; debian (ubuntu) follow a complete different
approach, read see :ref:`Debian's uWSGI layout`.
.. _Debian's uWSGI layout:
Debian's uWSGI layout
---------------------
.. _uwsgi.README.Debian:
https://salsa.debian.org/uwsgi-team/uwsgi/-/raw/debian/latest/debian/uwsgi.README.Debian
Be aware, Debian's uWSGI layout is quite different from the standard uWSGI
configuration. Your are familiar with :ref:`Debian's Apache layout`? .. they do
similar for the uWSGI infrastructure. The folders are::
/etc/uwsgi/apps-available/
/etc/uwsgi/apps-enabled/
@ -82,29 +108,52 @@ The `uwsgi ini file`_ is enabled by a symbolic link::
ln -s /etc/uwsgi/apps-available/searxng.ini /etc/uwsgi/apps-enabled/
From debian's documentation (``/usr/share/doc/uwsgi/README.Debian.gz``): You
could control specific instance(s) by issuing::
More details you will find in the uwsgi.README.Debian_
(``/usr/share/doc/uwsgi/README.Debian.gz``). Some commands you should know on
Debian:
service uwsgi <command> <confname> <confname> ...
.. code:: none
sudo -H service uwsgi start searx
sudo -H service uwsgi stop searx
Commands recognized by init.d script
====================================
My experience is, that this command is a bit buggy.
You can issue to init.d script following commands:
* start | starts daemon
* stop | stops daemon
* reload | sends to daemon SIGHUP signal
* force-reload | sends to daemon SIGTERM signal
* restart | issues 'stop', then 'start' commands
* status | shows status of daemon instance (running/not running)
.. _uwsgi configuration:
'status' command must be issued with exactly one argument: '<confname>'.
Alltogether
===========
Controlling specific instances of uWSGI
=======================================
Create the configuration ini-file according to your distribution (see below) and
restart the uwsgi application.
You could control specific instance(s) by issuing:
SYSTEMCTL_SKIP_REDIRECT=1 service uwsgi <command> <confname> <confname>...
where:
* <command> is one of 'start', 'stop' etc.
* <confname> is the name of configuration file (without extension)
For example, this is how instance for /etc/uwsgi/apps-enabled/hello.xml is
started:
SYSTEMCTL_SKIP_REDIRECT=1 service uwsgi start hello
.. _uWSGI maintenance:
uWSGI maintenance
=================
.. tabs::
.. group-tab:: Ubuntu / debian
.. kernel-include:: $DOCS_BUILD/includes/searx.rst
.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
:start-after: START searxng uwsgi-description ubuntu-20.04
:end-before: END searxng uwsgi-description ubuntu-20.04
@ -112,7 +161,7 @@ restart the uwsgi application.
.. group-tab:: Arch Linux
.. kernel-include:: $DOCS_BUILD/includes/searx.rst
.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
:start-after: START searxng uwsgi-description arch
:end-before: END searxng uwsgi-description arch
@ -120,16 +169,28 @@ restart the uwsgi application.
.. group-tab:: Fedora / RHEL
.. kernel-include:: $DOCS_BUILD/includes/searx.rst
.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
:start-after: START searxng uwsgi-description fedora
:end-before: END searxng uwsgi-description fedora
.. _uwsgi setup:
uWSGI setup
===========
Create the configuration ini-file according to your distribution and restart the
uwsgi application. As shown below, the :ref:`installation scripts` installs by
default:
- a uWSGI setup that listens on a socket and
- enables :ref:`cache busting <static_use_hash>`.
.. tabs::
.. group-tab:: Ubuntu / debian
.. kernel-include:: $DOCS_BUILD/includes/searx.rst
.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
:start-after: START searxng uwsgi-appini ubuntu-20.04
:end-before: END searxng uwsgi-appini ubuntu-20.04
@ -137,7 +198,7 @@ restart the uwsgi application.
.. group-tab:: Arch Linux
.. kernel-include:: $DOCS_BUILD/includes/searx.rst
.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
:start-after: START searxng uwsgi-appini arch
:end-before: END searxng uwsgi-appini arch
@ -145,6 +206,63 @@ restart the uwsgi application.
.. group-tab:: Fedora / RHEL
.. kernel-include:: $DOCS_BUILD/includes/searx.rst
.. kernel-include:: $DOCS_BUILD/includes/searxng.rst
:start-after: START searxng uwsgi-appini fedora
:end-before: END searxng uwsgi-appini fedora
.. _uWSGI Tyrant mode pitfalls:
Pitfalls of the Tyrant mode
===========================
The implementation of the process owners and groups in the `Tyrant mode`_ is
somewhat unusual and requires special consideration. In `Tyrant mode`_ mode the
Emperor will run the vassal using the UID/GID of the vassal configuration file
(user and group of the app ``.ini`` file).
.. _#2099@uWSGI: https://github.com/unbit/uwsgi/issues/2099
.. _#752@uWSGI: https://github.com/unbit/uwsgi/pull/752
.. _#2425uWSGI: https://github.com/unbit/uwsgi/issues/2425
Without option ``emperor-tyrant-initgroups=true`` in ``/etc/uwsgi.ini`` the
process won't get the additional groups, but this option is not available in
2.0.x branch (see `#2099@uWSGI`_) the feature `#752@uWSGI`_ has been merged (on
Oct. 2014) to the master branch of uWSGI but had never been released; the last
major release is from Dec. 2013, since the there had been only bugfix releases
(see `#2425uWSGI`_). To shorten up:
**In Tyrant mode, there is no way to get additional groups, and the uWSGI
process misses additional permissions that may be needed.**
By example, on Fedora (RHEL): If you try to install a redis DB with socket
communication and you want to connect from the SearXNG uWSGI, you will see a
*Permission denied* in the log of your instance::
ERROR:searx.shared.redis: [searxng (993)] can't connect redis DB ...
ERROR:searx.shared.redis: Error 13 connecting to unix socket: /usr/local/searxng-redis/run/redis.sock. Permission denied.
ERROR:searx.plugins.limiter: init limiter DB failed!!!
Even if your *searxng* user of the uWSGI process is added to additional groups
to give access to the socket from the redis DB::
$ groups searxng
searxng : searxng searxng-redis
To see the effective groups of the uwsgi process, you have to look at the status
of the process, by example::
$ ps -aef | grep '/usr/sbin/uwsgi --ini searxng.ini'
searxng 93 92 0 12:43 ? 00:00:00 /usr/sbin/uwsgi --ini searxng.ini
searxng 186 93 0 12:44 ? 00:00:01 /usr/sbin/uwsgi --ini searxng.ini
Here you can see that the additional "Groups" of PID 186 are unset (missing gid
of ``searxng-redis``)::
$ cat /proc/186/task/186/status
...
Uid: 993 993 993 993
Gid: 993 993 993 993
FDSize: 128
Groups:
...