From 3aff2c19d16619d949dc52216b29ef637d1a44a1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 4 Mar 2020 12:22:20 +0100 Subject: [PATCH] docs: complement uwsgi documentation for all distros Signed-off-by: Markus Heiser --- docs/admin/installation-searx.rst | 2 + docs/admin/installation-uwsgi.rst | 91 +++++++++++++++++++++++++++++++ utils/searx.sh | 49 ++++++++++++++--- 3 files changed, 133 insertions(+), 9 deletions(-) diff --git a/docs/admin/installation-searx.rst b/docs/admin/installation-searx.rst index 76449beb..88562f3e 100644 --- a/docs/admin/installation-searx.rst +++ b/docs/admin/installation-searx.rst @@ -12,6 +12,8 @@ Step by step installation Step by step installation with virtualenv. For Ubuntu, be sure to have enable universe repository. +.. _install packages: + Install packages ================ diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst index f9161679..7996bf93 100644 --- a/docs/admin/installation-uwsgi.rst +++ b/docs/admin/installation-uwsgi.rst @@ -4,6 +4,97 @@ 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 ... + + sudo -H service uwsgi start searx + sudo -H service uwsgi stop searx + +My experience is, that this command is a bit buggy. + +Alltogether +=========== + Create the configuration ini-file according to your distribution (see below) and restart the uwsgi application. diff --git a/utils/searx.sh b/utils/searx.sh index 447e9911..03911dff 100755 --- a/utils/searx.sh +++ b/utils/searx.sh @@ -643,7 +643,7 @@ rst-doc() { arch="$(echo "${arch}" | sed 's/.*/ & \\/' | sed '$ s/.$//')" fedora="$(echo "${fedora}" | sed 's/.*/ & \\/' | sed '$ s/.$//')" - eval "echo \"$(< ${REPO_ROOT}/docs/build-templates/searx.rst)\"" + eval "echo \"$(< "${REPO_ROOT}/docs/build-templates/searx.rst")\"" # I use ubuntu-20.04 here to demonstrate that versions are also suported, # normaly debian-* and ubuntu-* are most the same. @@ -656,19 +656,50 @@ rst-doc() { uWSGI_distro_setup echo -e "\n.. START searx uwsgi-description $DIST_NAME" - echo "location: ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}" + case $DIST_ID-$DIST_VERS in - ubuntu-*|debian-*) - echo "restart: sudo -H service uwsgi restart ${SEARX_UWSGI_APP%.*}" ;; - arch-*) - echo "restart: sudo -H systemctl restart uwsgi@${SEARX_UWSGI_APP%.*}" ;; - fedora-*) - echo "restart: sudo -H touch ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP}";; + ubuntu-*|debian-*) cat < /usr/share/doc/uwsgi/README.Debian.gz +# For uWSGI debian uses the LSB init process, this might be changed +# one day, see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=833067 + +create ${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP} +enable: sudo -H ln -s ${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP} ${uWSGI_APPS_ENABLED}/ +start: sudo -H service uwsgi start ${SEARX_UWSGI_APP%.*} +restart: sudo -H service uwsgi restart ${SEARX_UWSGI_APP%.*} +stop: sudo -H service uwsgi stop ${SEARX_UWSGI_APP%.*} +disable: sudo -H rm ${uWSGI_APPS_ENABLED}/${CONF} +EOF + ;; + arch-*) cat < /usr/lib/systemd/system/uwsgi@.service +# For uWSGI archlinux uses systemd template units, see +# - http://0pointer.de/blog/projects/instances.html +# - https://uwsgi-docs.readthedocs.io/en/latest/Systemd.html#one-service-per-app-in-systemd + +create: ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP} +enable: sudo -H systemctl enable uwsgi@${SEARX_UWSGI_APP%.*} +start: sudo -H systemctl start uwsgi@${SEARX_UWSGI_APP%.*} +restart: sudo -H systemctl restart uwsgi@${SEARX_UWSGI_APP%.*} +stop: sudo -H systemctl stop uwsgi@${SEARX_UWSGI_APP%.*} +disable: sudo -H systemctl disable uwsgi@${SEARX_UWSGI_APP%.*} +EOF + ;; + fedora-*) cat < /usr/lib/systemd/system/uwsgi.service +# The unit file starts uWSGI in emperor mode (/etc/uwsgi.ini), see +# - https://uwsgi-docs.readthedocs.io/en/latest/Emperor.html + +create: ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP} +restart: sudo -H touch ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP} +disable: sudo -H rm ${uWSGI_APPS_ENABLED}/${SEARX_UWSGI_APP} +EOF + ;; esac echo -e ".. END searx uwsgi-description $DIST_NAME" echo -e "\n.. START searx uwsgi-appini $DIST_NAME" - eval "echo \"$(< ${TEMPLATES}/${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP})\"" + eval "echo \"$(< "${TEMPLATES}/${uWSGI_APPS_AVAILABLE}/${SEARX_UWSGI_APP}")\"" echo -e "\n.. END searx uwsgi-appini $DIST_NAME" )