From c3e4753ce951f759844db13d98f9ad5b226f84b6 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Mon, 2 Mar 2020 19:00:19 +0100 Subject: docs: generic documentation from the installation scripts Signed-off-by: Markus Heiser --- docs/admin/installation-uwsgi.rst | 82 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/admin/installation-uwsgi.rst (limited to 'docs/admin/installation-uwsgi.rst') diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst new file mode 100644 index 000000000..0ee4800ad --- /dev/null +++ b/docs/admin/installation-uwsgi.rst @@ -0,0 +1,82 @@ +.. _searx uwsgi: + +===== +uwsgi +===== + +Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this +content: + +.. code:: ini + + [uwsgi] + + # uWSGI core + # ---------- + # + # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#uwsgi-core + + # Who will run the code + uid = searx + gid = searx + + # chdir to specified directory before apps loading + chdir = /usr/local/searx/searx-src/searx + + # disable logging for privacy + disable-logging = true + + # The right granted on the created socket + chmod-socket = 666 + + # Plugin to use and interpretor config + single-interpreter = true + + # enable master process + master = true + + # load apps in each worker instead of the master + lazy-apps = true + + # load uWSGI plugins + plugin = python3,http + + # By default the Python plugin does not initialize the GIL. This means your + # app-generated threads will not run. If you need threads, remember to enable + # them with enable-threads. Running uWSGI in multithreading mode (with the + # threads options) will automatically enable threading support. This *strange* + # default behaviour is for performance reasons. + enable-threads = true + + # plugin: python + # -------------- + # + # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-python + + # load a WSGI module + module = searx.webapp + + # set PYTHONHOME/virtualenv + virtualenv = /usr/local/searx/searx-pyenv + + # add directory (or glob) to pythonpath + pythonpath = /usr/local/searx/searx-src + + + # plugin http + # ----------- + # + # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http + + # Native HTTP support: https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html + http = 127.0.0.1:8888 + +Activate the uwsgi application and restart: + +.. code:: sh + + cd /etc/uwsgi/apps-enabled + ln -s ../apps-available/searx.ini + /etc/init.d/uwsgi restart + + -- cgit v1.2.3 From 3cb7daedb7c5c93a98dfefa191c161f31a1347c6 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 3 Mar 2020 19:57:15 +0100 Subject: docs: generic doocumentation for searx-uwsgi Signed-off-by: Markus Heiser --- docs/admin/installation-uwsgi.rst | 88 ++++++++++++++------------------------- 1 file changed, 31 insertions(+), 57 deletions(-) (limited to 'docs/admin/installation-uwsgi.rst') diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst index 0ee4800ad..f9161679f 100644 --- a/docs/admin/installation-uwsgi.rst +++ b/docs/admin/installation-uwsgi.rst @@ -4,79 +4,53 @@ uwsgi ===== -Create the configuration file ``/etc/uwsgi/apps-available/searx.ini`` with this -content: +Create the configuration ini-file according to your distribution (see below) and +restart the uwsgi application. -.. code:: ini +.. tabs:: - [uwsgi] + .. group-tab:: Ubuntu / debian - # uWSGI core - # ---------- - # - # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#uwsgi-core + .. literalinclude:: ../../build/docs/includes/searx.rst + :start-after: START searx uwsgi-description ubuntu-20.04 + :end-before: END searx uwsgi-description ubuntu-20.04 - # Who will run the code - uid = searx - gid = searx - # chdir to specified directory before apps loading - chdir = /usr/local/searx/searx-src/searx + .. group-tab:: Arch Linux - # disable logging for privacy - disable-logging = true + .. literalinclude:: ../../build/docs/includes/searx.rst + :start-after: START searx uwsgi-description arch + :end-before: END searx uwsgi-description arch - # The right granted on the created socket - chmod-socket = 666 - # Plugin to use and interpretor config - single-interpreter = true + .. group-tab:: Fedora / RHEL - # enable master process - master = true + .. literalinclude:: ../../build/docs/includes/searx.rst + :start-after: START searx uwsgi-description fedora + :end-before: END searx uwsgi-description fedora - # load apps in each worker instead of the master - lazy-apps = true - # load uWSGI plugins - plugin = python3,http +.. tabs:: - # By default the Python plugin does not initialize the GIL. This means your - # app-generated threads will not run. If you need threads, remember to enable - # them with enable-threads. Running uWSGI in multithreading mode (with the - # threads options) will automatically enable threading support. This *strange* - # default behaviour is for performance reasons. - enable-threads = true + .. group-tab:: Ubuntu / debian - # plugin: python - # -------------- - # - # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-python + .. 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 - # load a WSGI module - module = searx.webapp + .. group-tab:: Arch Linux - # set PYTHONHOME/virtualenv - virtualenv = /usr/local/searx/searx-pyenv + .. literalinclude:: ../../build/docs/includes/searx.rst + :language: ini + :start-after: START searx uwsgi-appini arch + :end-before: END searx uwsgi-appini arch - # add directory (or glob) to pythonpath - pythonpath = /usr/local/searx/searx-src + .. group-tab:: Fedora / RHEL - - # plugin http - # ----------- - # - # https://uwsgi-docs.readthedocs.io/en/latest/Options.html#plugin-http - - # Native HTTP support: https://uwsgi-docs.readthedocs.io/en/latest/HTTP.html - http = 127.0.0.1:8888 - -Activate the uwsgi application and restart: - -.. code:: sh - - cd /etc/uwsgi/apps-enabled - ln -s ../apps-available/searx.ini - /etc/init.d/uwsgi restart + .. literalinclude:: ../../build/docs/includes/searx.rst + :language: ini + :start-after: START searx uwsgi-appini fedora + :end-before: END searx uwsgi-appini fedora -- cgit v1.2.3 From 3aff2c19d16619d949dc52216b29ef637d1a44a1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 4 Mar 2020 12:22:20 +0100 Subject: docs: complement uwsgi documentation for all distros Signed-off-by: Markus Heiser --- docs/admin/installation-uwsgi.rst | 91 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) (limited to 'docs/admin/installation-uwsgi.rst') diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst index f9161679f..7996bf937 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. -- cgit v1.2.3 From 387c6a77691fec514704bdf178b9ab94ad4abb40 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Fri, 6 Mar 2020 14:47:00 +0100 Subject: docs: improve description of uwsgi & ngingx setup Signed-off-by: Markus Heiser --- docs/admin/installation-uwsgi.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/admin/installation-uwsgi.rst') diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst index 7996bf937..67a8e127a 100644 --- a/docs/admin/installation-uwsgi.rst +++ b/docs/admin/installation-uwsgi.rst @@ -92,6 +92,8 @@ could control specific instance(s) by issuing:: My experience is, that this command is a bit buggy. +.. _uwsgi configuration: + Alltogether =========== -- cgit v1.2.3 From ebde9d10fd84de74ea99385dae4d95bcf932bcf3 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 9 Apr 2020 15:04:23 +0200 Subject: docs: proofreading of all the installation topics Signed-off-by: Markus Heiser --- docs/admin/installation-uwsgi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/admin/installation-uwsgi.rst') diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst index 67a8e127a..72498c0bf 100644 --- a/docs/admin/installation-uwsgi.rst +++ b/docs/admin/installation-uwsgi.rst @@ -4,7 +4,7 @@ uwsgi ===== -.. sidebar:: further read +.. sidebar:: further reading - `systemd.unit`_ - `uWSGI Emperor`_ -- cgit v1.2.3 From bfef2c3b65aea8dd3485e0959e068d460577a841 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Thu, 18 Jun 2020 18:52:45 +0200 Subject: [fix] buildprocess of docs in LXC (containers) The $DOCS_BUILD variable (like all BUILD variables) in the lxc environment:: sudo -H ./utils/lxc.sh cmd searx-archlinux make docs is different from running build process in the HOST:: make docs with kernel-include directive we can use the environment variables in the reST documents to address the correct file location of the include. Signed-off-by: Markus Heiser --- docs/admin/installation-uwsgi.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/admin/installation-uwsgi.rst') diff --git a/docs/admin/installation-uwsgi.rst b/docs/admin/installation-uwsgi.rst index 72498c0bf..ac4c463b9 100644 --- a/docs/admin/installation-uwsgi.rst +++ b/docs/admin/installation-uwsgi.rst @@ -104,21 +104,21 @@ restart the uwsgi application. .. group-tab:: Ubuntu / debian - .. literalinclude:: ../../build/docs/includes/searx.rst + .. kernel-include:: $DOCS_BUILD/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 + .. kernel-include:: $DOCS_BUILD/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 + .. kernel-include:: $DOCS_BUILD/includes/searx.rst :start-after: START searx uwsgi-description fedora :end-before: END searx uwsgi-description fedora @@ -127,22 +127,22 @@ restart the uwsgi application. .. group-tab:: Ubuntu / debian - .. literalinclude:: ../../build/docs/includes/searx.rst - :language: ini + .. kernel-include:: $DOCS_BUILD/includes/searx.rst + :code: 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 + .. kernel-include:: $DOCS_BUILD/includes/searx.rst + :code: 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 + .. kernel-include:: $DOCS_BUILD/includes/searx.rst + :code: ini :start-after: START searx uwsgi-appini fedora :end-before: END searx uwsgi-appini fedora -- cgit v1.2.3