git.iko.soy/searx
on master help sign in
docs: complement uwsgi documentation for all distros

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

commit3aff2c19d16619d949dc52216b29ef637d1a44a1 authorMarkus Heiser <markus.heiser@darmarit.de> dateWed 4 Mar 2020, 12:22 (7 years ago) parent9f1cb7a
3 files changed+133−9
compare with master
unifiedsplit
docs/admin/installation-searx.rst+2 docs/admin/installation-uwsgi.rst+91 utils/searx.sh+40−9
docs/admin/installation-searx.rst+2
@@ -12,6 +12,8 @@ Step by step installation
1212Step by step installation with virtualenv. For Ubuntu, be sure to have enable
1313universe repository.
1414
15+.. _install packages:
16+
1517Install packages
1618================
1719
docs/admin/installation-uwsgi.rst+91
@@ -4,6 +4,97 @@
44uwsgi
55=====
66
7+.. sidebar:: further read
8+
9+ - `systemd.unit`_
10+ - `uWSGI Emperor`_
11+
12+.. contents:: Contents
13+ :depth: 2
14+ :local:
15+ :backlinks: entry
16+
17+
18+.. _systemd.unit: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
19+.. _One service per app in systemd:
20+ https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html#one-service-per-app-in-systemd
21+.. _uWSGI Emperor:
22+ https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
23+.. _uwsgi ini file:
24+ https://uwsgi-docs.readthedocs.io/en/latest/Configuration.html#ini-files
25+.. _systemd unit template:
26+ http://0pointer.de/blog/projects/instances.html
27+
28+
29+Origin uWSGI
30+============
31+
32+How uWSGI is implemented by distributors is different. uWSGI itself
33+recommend two methods
34+
35+`systemd.unit`_ template files as described here `One service per app in systemd`_.
36+
37+ There is one `systemd unit template`_ and one `uwsgi ini file`_ per uWSGI-app
38+ placed at dedicated locations. Take archlinux and a searx.ini as example::
39+
40+ unit template --> /usr/lib/systemd/system/uwsgi@.service
41+ uwsgi ini files --> /etc/uwsgi/searx.ini
42+
43+ The searx app can be maintained as know from common systemd units::
44+
45+ systemctl enable uwsgi@searx
46+ systemctl start uwsgi@searx
47+ systemctl restart uwsgi@searx
48+ systemctl stop uwsgi@searx
49+
50+The `uWSGI Emperor`_ mode which fits for maintaining a large range of uwsgi apps.
51+
52+ The Emperor mode is a special uWSGI instance that will monitor specific
53+ events. The Emperor mode (service) is started by a (common, not template)
54+ systemd unit. The Emperor service will scan specific directories for `uwsgi
55+ ini file`_\s (also know as *vassals*). If a *vassal* is added, removed or the
56+ timestamp is modified, a corresponding action takes place: a new uWSGI
57+ instance is started, reload or stopped. Take Fedora and a searx.ini as
58+ example::
59+
60+ to start a new searx instance create --> /etc/uwsgi.d/searx.ini
61+ to reload the instance edit timestamp --> touch /etc/uwsgi.d/searx.ini
62+ to stop instance remove ini --> rm /etc/uwsgi.d/searx.ini
63+
64+Distributors
65+============
66+
67+The `uWSGI Emperor`_ mode and `systemd unit template`_ is what the distributors
68+mostly offer their users, even if they differ in the way they implement both
69+modes and their defaults. Another point they might differ is the packaging of
70+plugins (if so, compare :ref:`install packages`) and what the default python
71+interpreter is (python2 vs. python3).
72+
73+Fedora starts a Emperor by default, while archlinux does not start any uwsgi
74+service by default. Worth to know; debian (ubuntu) follow a complete different
75+approach. *debian*: your are familiar with the apache infrastructure? .. they
76+do similar for the uWSGI infrastructure (with less comfort), the folders are::
77+
78+ /etc/uwsgi/apps-available/
79+ /etc/uwsgi/apps-enabled/
80+
81+The `uwsgi ini file`_ is enabled by a symbolic link::
82+
83+ ln -s /etc/uwsgi/apps-available/searx.ini /etc/uwsgi/apps-enabled/
84+
85+From debian's documentation (``/usr/share/doc/uwsgi/README.Debian.gz``): You
86+could control specific instance(s) by issuing::
87+
88+ service uwsgi <command> <confname> <confname> ...
89+
90+ sudo -H service uwsgi start searx
91+ sudo -H service uwsgi stop searx
92+
93+My experience is, that this command is a bit buggy.
94+
95+Alltogether
96+===========
97+
798Create the configuration ini-file according to your distribution (see below) and
899restart the uwsgi application.
9100
utils/searx.sh+40−9
@@ -643,7 +643,7 @@ rst-doc() {
643643 arch="$(echo "${arch}" | sed 's/.*/ & \\/' | sed '$ s/.$//')"
644644 fedora="$(echo "${fedora}" | sed 's/.*/ & \\/' | sed '$ s/.$//')"
645645
646− eval "echo \"$(< ${REPO_ROOT}/docs/build-templates/searx.rst)\""
646+ eval "echo \"$(< "${REPO_ROOT}/docs/build-templates/searx.rst")\""
647647
648648 # I use ubuntu-20.04 here to demonstrate that versions are also suported,
649649 # normaly debian-* and ubuntu-* are most the same.
@@ -656,19 +656,50 @@ rst-doc() {
656656 uWSGI_distro_setup
657657
658658 echo -e "\n.. START searx uwsgi-description $DIST_NAME"
659− echo "location: ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}"
659+
660660 case $DIST_ID-$DIST_VERS in
661− ubuntu-*|debian-*)
662− echo "restart: sudo -H service uwsgi restart ${SEARX_UWSGI_APP%.*}" ;;
663− arch-*)
664− echo "restart: sudo -H systemctl restart uwsgi@${SEARX_UWSGI_APP%.*}" ;;
665− fedora-*)
666− echo "restart: sudo -H touch ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}";;
661+ ubuntu-*|debian-*) cat <<EOF
662+# init.d --> /usr/share/doc/uwsgi/README.Debian.gz
663+# For uWSGI debian uses the LSB init process, this might be changed
664+# one day, see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=833067
665+
666+create ${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP}
667+enable: sudo -H ln -s ${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP} ${uWSGI_APPS_ENABLED}/
668+start: sudo -H service uwsgi start ${SEARX_UWSGI_APP%.*}
669+restart: sudo -H service uwsgi restart ${SEARX_UWSGI_APP%.*}
670+stop: sudo -H service uwsgi stop ${SEARX_UWSGI_APP%.*}
671+disable: sudo -H rm ${uWSGI_APPS_ENABLED}/${CONF}
672+EOF
673+ ;;
674+ arch-*) cat <<EOF
675+# systemd --> /usr/lib/systemd/system/uwsgi@.service
676+# For uWSGI archlinux uses systemd template units, see
677+# - http://0pointer.de/blog/projects/instances.html
678+# - https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html#one-service-per-app-in-systemd
679+
680+create: ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}
681+enable: sudo -H systemctl enable uwsgi@${SEARX_UWSGI_APP%.*}
682+start: sudo -H systemctl start uwsgi@${SEARX_UWSGI_APP%.*}
683+restart: sudo -H systemctl restart uwsgi@${SEARX_UWSGI_APP%.*}
684+stop: sudo -H systemctl stop uwsgi@${SEARX_UWSGI_APP%.*}
685+disable: sudo -H systemctl disable uwsgi@${SEARX_UWSGI_APP%.*}
686+EOF
687+ ;;
688+ fedora-*) cat <<EOF
689+# systemd --> /usr/lib/systemd/system/uwsgi.service
690+# The unit file starts uWSGI in emperor mode (/etc/uwsgi.ini), see
691+# - https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html
692+
693+create: ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}
694+restart: sudo -H touch ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}
695+disable: sudo -H rm ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}
696+EOF
697+ ;;
667698 esac
668699 echo -e ".. END searx uwsgi-description $DIST_NAME"
669700
670701 echo -e "\n.. START searx uwsgi-appini $DIST_NAME"
671− eval "echo \"$(< ${TEMPLATES}/${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP})\""
702+ eval "echo \"$(< "${TEMPLATES}/${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP}")\""
672703 echo -e "\n.. END searx uwsgi-appini $DIST_NAME"
673704
674705 )