summaryrefslogtreecommitdiff
path: root/docs/utils
diff options
context:
space:
mode:
authorMarkus Heiser <markus.heiser@darmarit.de>2023-05-21 18:12:39 +0200
committerMarkus Heiser <markus.heiser@darmarit.de>2023-05-21 18:12:39 +0200
commitc9833ded9f4518f258e6b5d7eb4cc8ec79ade56d (patch)
tree0ae00c7e3da899be6a962db443f903a78997f98d /docs/utils
parentd867bf17e6d2f9a7c83c9a1ffafda5184a24c0e3 (diff)
downloadsearxng-c9833ded9f4518f258e6b5d7eb4cc8ec79ade56d.tar.gz
searxng-c9833ded9f4518f258e6b5d7eb4cc8ec79ade56d.zip
[doc] update & fix documentation of the "SearXNG LXC suite"
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Diffstat (limited to 'docs/utils')
-rw-r--r--docs/utils/index.rst2
-rw-r--r--docs/utils/lxc.sh.rst211
-rw-r--r--docs/utils/searxng.sh.rst14
3 files changed, 167 insertions, 60 deletions
diff --git a/docs/utils/index.rst b/docs/utils/index.rst
index 2da26ed12..1ac77e285 100644
--- a/docs/utils/index.rst
+++ b/docs/utils/index.rst
@@ -20,6 +20,8 @@ Common command environments
The scripts in our tooling box often dispose of common environments:
+.. _FORCE_TIMEOUT:
+
``FORCE_TIMEOUT`` : environment
Sets timeout for interactive prompts. If you want to run a script in batch
job, with defaults choices, set ``FORCE_TIMEOUT=0``. By example; to install a
diff --git a/docs/utils/lxc.sh.rst b/docs/utils/lxc.sh.rst
index 4308a12cc..cb0fe9361 100644
--- a/docs/utils/lxc.sh.rst
+++ b/docs/utils/lxc.sh.rst
@@ -14,6 +14,11 @@
``utils/lxc.sh``
================
+With the use of *Linux Containers* (LXC_) we can scale our tasks over a stack of
+containers, what we call the: *lxc suite*. The :ref:`lxc-searxng.env` is
+loaded by default, every time you start the ``lxc.sh`` script (*you do not need
+to care about*).
+
.. sidebar:: further reading
- snap_, `snapcraft LXD`_
@@ -21,10 +26,16 @@
- `LXC/LXD Image Server`_
- `LXD@github`_
-With the use of *Linux Containers* (LXC_) we can scale our tasks over a stack of
-containers, what we call the: *lxc suite*. The *SearXNG suite*
-(:origin:`lxc-searxng.env <utils/lxc-searxng.env>`) is loaded by default, every time
-you start the ``lxc.sh`` script (*you do not need to care about*).
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
+
+.. _lxd install:
+
+Install LXD
+===========
Before you can start with containers, you need to install and initiate LXD_
once::
@@ -38,44 +49,19 @@ take some time**::
$ sudo -H ./utils/lxc.sh build
+.. sidebar:: hint
+
+ If you have issues with the internet connectivity of your containers read
+ section :ref:`internet connectivity docker`.
+
A cup of coffee later, your LXC suite is build up and you can run whatever task
you want / in a selected or even in all :ref:`LXC suite containers <lxc.sh
help>`.
-.. hint::
-
- If you see any problems with the internet connectivity of your
- containers read section :ref:`internet connectivity docker`.
-
-If you do not want to build all containers, **you can build just one**::
-
- $ sudo -H ./utils/lxc.sh build searxng-archlinux
-
-*Good to know ...*
-
-Each container shares the root folder of the repository and the command
-``utils/lxc.sh cmd`` **handles relative path names transparent**, compare output
-of::
-
- $ sudo -H ./utils/lxc.sh cmd -- ls -la Makefile
- ...
-
-In the containers, you can run what ever you want, e.g. to start a bash use::
-
- $ sudo -H ./utils/lxc.sh cmd searxng-archlinux bash
- INFO: [searxng-archlinux] bash
- [root@searxng-archlinux SearXNG]#
-
-If there comes the time you want to **get rid off all** the containers and
-**clean up local images** just type::
-
- $ sudo -H ./utils/lxc.sh remove
- $ sudo -H ./utils/lxc.sh remove images
-
.. _internet connectivity docker:
Internet Connectivity & Docker
-==============================
+------------------------------
.. sidebar:: further read
@@ -115,21 +101,132 @@ Reboot your system and check the iptables rules::
:FORWARD ACCEPT [7048:7851230]
+.. _searxng lxc suite:
+
+SearXNG LXC suite
+=================
+
+The intention of the *SearXNG LXC suite* is to build up a suite of containers
+for development tasks or :ref:`buildhosts <Setup SearXNG buildhost>` with a very
+small set of simple commands. At the end of the ``--help`` output the SearXNG
+suite from the :ref:`lxc-searxng.env` is introduced::
+
+ $ sudo -H ./utils/lxc.sh --help
+ ...
+ LXC suite: searxng
+ Suite includes installation of SearXNG
+ images: ubu2004 ubu2204 fedora35 archlinux
+ containers: searxng-ubu2004 searxng-ubu2204 searxng-fedora35 searxng-archlinux
+
+As shown above there are images and containers build up on this images. To show
+more info about the containers in the *SearXNG LXC suite* call ``show suite``.
+If this is the first time you make use of the SearXNG LXC suite, no containers
+are installed and the output is::
+
+ $ sudo -H ./utils/lxc.sh show suite
+
+ LXC suite (searxng-*)
+ =====================
+
+ +------+-------+------+------+------+-----------+
+ | NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+ +------+-------+------+------+------+-----------+
+
+ WARN: container searxng-ubu2004 does not yet exists
+ WARN: container searxng-ubu2204 does not yet exists
+ WARN: container searxng-fedora35 does not yet exists
+ WARN: container searxng-archlinux does not yet exists
+
+If you do not want to run a command or a build in all containers, **you can
+build just one**. Here by example in the container that is build upon the
+*archlinux* image::
+
+ $ sudo -H ./utils/lxc.sh build searxng-archlinux
+ $ sudo -H ./utils/lxc.sh cmd searxng-archlinux pwd
+
+Otherwise, to apply a command to all containers you can use::
+
+ $ sudo -H ./utils/lxc.sh build
+ $ sudo -H ./utils/lxc.sh cmd -- ls -la .
+
+Running commands
+----------------
+
+**Inside containers, you can run scripts** from the :ref:`toolboxing` or run
+what ever command you need. By example, to start a bash use::
+
+ $ sudo -H ./utils/lxc.sh cmd searxng-archlinux bash
+ INFO: [searxng-archlinux] bash
+ [root@searxng-archlinux SearXNG]#
+
+.. _Good to know:
+
+Good to know
+------------
+
+Each container shares the root folder of the repository and the command
+``utils/lxc.sh cmd`` **handle relative path names transparent**::
+
+ $ pwd
+ /share/SearXNG
+
+ $ sudo -H ./utils/lxc.sh cmd searxng-archlinux pwd
+ INFO: [searxng-archlinux] pwd
+ /share/SearXNG
+
+The path ``/share/SearXNG`` will be different on your HOST system. The commands
+in the conatiner are executed by the ``root`` inside of the container. Compare
+output of::
+
+ $ ls -li Makefile
+ 47712402 -rw-rw-r-- 1 markus markus 2923 Apr 19 13:52 Makefile
+
+ $ sudo -H ./utils/lxc.sh cmd searxng-archlinux ls -li Makefile
+ INFO: [searxng-archlinux] ls -li Makefile
+ 47712402 -rw-rw-r-- 1 root root 2923 Apr 19 11:52 Makefile
+ ...
+
+Since the path ``/share/SearXNG`` of the HOST system is wrapped into the
+container under the same name, the shown ``Makefile`` (inode ``47712402``) in
+the ouput is always the identical ``/share/SearXNG/Makefile`` from the HOST
+system. In the example shown above the owner of the path in the container is
+the ``root`` user of the conatiner (and the timezone in the container is
+different to HOST system).
+
+
.. _lxc.sh install suite:
Install suite
-=============
+-------------
+
+.. sidebar:: further read
-To install the complete :ref:`SearXNG suite (includes searx, morty & filtron)
-<lxc-searxng.env>` into all LXC_ use::
+ - :ref:`working in containers`
+ - :ref:`FORCE_TIMEOUT <FORCE_TIMEOUT>`
+To install the complete :ref:`SearXNG suite <lxc-searxng.env>` into **all** LXC_
+containers leave the container argument empty and run::
+
+ $ sudo -H ./utils/lxc.sh build
$ sudo -H ./utils/lxc.sh install suite
+To *build & install* suite only in one container you can use by example::
+
+ $ sudo -H ./utils/lxc.sh build searxng-archlinux
+ $ sudo -H ./utils/lxc.sh install suite searxng-archlinux
+
The command above installs a SearXNG suite (see :ref:`installation scripts`).
To :ref:`install a nginx <installation nginx>` reverse proxy (or alternatively
use :ref:`apache <installation apache>`)::
- sudo -H ./utils/lxc.sh cmd -- FORCE_TIMEOUT=0 ./utils/searxng.sh install nginx
+ $ sudo -H ./utils/lxc.sh cmd -- FORCE_TIMEOUT=0 ./utils/searxng.sh install nginx
+
+Same operation just in one container of the suite::
+
+ $ sudo -H ./utils/lxc.sh cmd searxng-archlinux FORCE_TIMEOUT=0 ./utils/searxng.sh install nginx
+
+The :ref:`FORCE_TIMEOUT <FORCE_TIMEOUT>` environment is set to zero to run the
+script without user interaction.
To get the IP (URL) of the SearXNG service in the containers use ``show suite``
command. To test instances from containers just open the URLs in your
@@ -137,22 +234,22 @@ WEB-Browser::
$ sudo ./utils/lxc.sh show suite | grep SEARXNG_URL
- [searxng-ubu2110] SEARXNG_URL : http://n.n.n.147/searxng
- [searxng-ubu2004] SEARXNG_URL : http://n.n.n.246/searxng
- [searxnggfedora35] SEARXNG_URL : http://n.n.n.140/searxng
- [searxng-archlinux] SEARXNG_URL : http://n.n.n.165/searxng
+ [searxng-ubu2110] SEARXNG_URL : http://n.n.n.170/searxng
+ [searxng-ubu2004] SEARXNG_URL : http://n.n.n.160/searxng
+ [searxnggfedora35] SEARXNG_URL : http://n.n.n.150/searxng
+ [searxng-archlinux] SEARXNG_URL : http://n.n.n.140/searxng
+Clean up
+--------
-Running commands
-================
+If there comes the time you want to **get rid off all** the containers and
+**clean up local images** just type::
-**Inside containers, you can use make or run scripts** from the
-:ref:`toolboxing`. By example: to setup a :ref:`buildhosts` and run the
-Makefile target ``test`` in the archlinux_ container::
+ $ sudo -H ./utils/lxc.sh remove
+ $ sudo -H ./utils/lxc.sh remove images
- sudo -H ./utils/lxc.sh cmd searxng-archlinux ./utils/searxng.sh install buildhost
- sudo -H ./utils/lxc.sh cmd searxng-archlinux make test
+.. _Setup SearXNG buildhost:
Setup SearXNG buildhost
=======================
@@ -160,7 +257,7 @@ Setup SearXNG buildhost
You can **install the SearXNG buildhost environment** into one or all containers.
The installation procedure to set up a :ref:`build host<buildhosts>` takes its
time. Installation in all containers will take more time (time for another cup
-of coffee).::
+of coffee). ::
sudo -H ./utils/lxc.sh cmd -- ./utils/searxng.sh install buildhost
@@ -174,13 +271,13 @@ To get IP of the container and the port number *live docs* is listening::
$ sudo ./utils/lxc.sh show suite | grep docs.live
...
- [searxng-archlinux] INFO: (eth0) docs.live: http://n.n.n.12:8080/
+ [searxng-archlinux] INFO: (eth0) docs.live: http://n.n.n.140:8080/
.. _lxc.sh help:
-Overview
-========
+Command Help
+============
The ``--help`` output of the script is largely self-explanatory:
@@ -189,8 +286,10 @@ The ``--help`` output of the script is largely self-explanatory:
.. _lxc-searxng.env:
-SearXNG suite
-=============
+SearXNG suite config
+====================
+
+The SearXNG suite is defined in the file :origin:`utils/lxc-searxng.env`:
.. literalinclude:: ../../utils/lxc-searxng.env
:language: bash
diff --git a/docs/utils/searxng.sh.rst b/docs/utils/searxng.sh.rst
index f6578f7b1..3a6ac6d43 100644
--- a/docs/utils/searxng.sh.rst
+++ b/docs/utils/searxng.sh.rst
@@ -5,6 +5,9 @@
``utils/searxng.sh``
====================
+To simplify the installation and maintenance of a SearXNG instance you can use the
+script :origin:`utils/searxng.sh`.
+
.. sidebar:: further reading
- :ref:`architecture`
@@ -12,8 +15,11 @@
- :ref:`installation nginx`
- :ref:`installation apache`
-To simplify the installation and maintenance of a SearXNG instance you can use the
-script :origin:`utils/searxng.sh`.
+.. contents:: Contents
+ :depth: 2
+ :local:
+ :backlinks: entry
+
Install
=======
@@ -28,8 +34,8 @@ The installation is described in chapter :ref:`installation basic`.
.. _searxng.sh overview:
-Overview
-========
+Command Help
+============
The ``--help`` output of the script is largely self-explanatory: