Markus Heiser 5720844fcd [doc] rearranges Settings & Engines docs for better readability

We have built up detailed documentation of the *settings* and the *engines* over
the past few years.  However, this documentation was still spread over various
chapters and was difficult to navigate in its entirety.

This patch rearranges the Settings & Engines documentation for better
readability.

To review new ordered docs::

   make docs.clean docs.live

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

2023-07-01 22:45:19 +02:00

9.1 KiB

Raw Blame History

uWSGI

further reading

Origin uWSGI

How uWSGI is implemented by distributors varies. The uWSGI project itself recommends two methods:

systemd.unit template file as described here One service per app in systemd:

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:
systemd template unit: /usr/lib/systemd/system/uwsgi@.service
        contains: [Service]
                  ExecStart=/usr/bin/uwsgi --ini /etc/uwsgi/%I.ini

SearXNG application:   /etc/uwsgi/searxng.ini
        links to: /etc/uwsgi/apps-available/searxng.ini
The SearXNG app (template /etc/uwsgi/%I.ini) can be maintained as known from common systemd units:
$ systemctl enable  uwsgi@searxng
$ systemctl start   uwsgi@searxng
$ systemctl restart uwsgi@searxng
$ systemctl stop    uwsgi@searxng

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 (the service) is started by a (common, not template) systemd unit.

The Emperor service will scan specific directories for uwsgi ini files (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

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 in is the packaging of plugins (if so, compare install packages) and what the default python interpreter is (python2 vs. python3).

While archlinux does not start a uWSGI service by default, Fedora (RHEL) starts a Emperor in Tyrant mode by default (you should have read uWSGI Tyrant mode pitfalls). Worth to know; debian (ubuntu) follow a complete different approach, read see Debian's uWSGI layout.

Debian's uWSGI layout

Be aware, Debian's uWSGI layout is quite different from the standard uWSGI configuration. Your are familiar with Debian's Apache layout? .. they do a similar thing for the uWSGI infrastructure. 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/searxng.ini /etc/uwsgi/apps-enabled/

More details can be found in the uwsgi.README.Debian (/usr/share/doc/uwsgi/README.Debian.gz). Some commands you should know on Debian:

Commands recognized by init.d script
====================================

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)

'status' command must be issued with exactly one argument: '<confname>'.

Controlling specific instances of uWSGI
=======================================

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