diff options
author | Markus Heiser <markus.heiser@darmarit.de> | 2023-05-21 18:12:39 +0200 |
---|---|---|
committer | Markus Heiser <markus.heiser@darmarit.de> | 2023-05-21 18:12:39 +0200 |
commit | c9833ded9f4518f258e6b5d7eb4cc8ec79ade56d (patch) | |
tree | 0ae00c7e3da899be6a962db443f903a78997f98d /docs/utils | |
parent | d867bf17e6d2f9a7c83c9a1ffafda5184a24c0e3 (diff) | |
download | searxng-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.rst | 2 | ||||
-rw-r--r-- | docs/utils/lxc.sh.rst | 211 | ||||
-rw-r--r-- | docs/utils/searxng.sh.rst | 14 |
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: |