forked from zaclys/searxng
5720844fcd
We have built up detailed documentation of the *settings* and the *engines* over the past few years. However, this documentation was still spread over various chapters and was difficult to navigate in its entirety. This patch rearranges the Settings & Engines documentation for better readability. To review new ordered docs:: make docs.clean docs.live Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
439 lines
13 KiB
ReStructuredText
439 lines
13 KiB
ReStructuredText
.. _lxcdev:
|
|
|
|
==============================
|
|
Developing in Linux Containers
|
|
==============================
|
|
|
|
.. _LXC: https://linuxcontainers.org/lxc/introduction/
|
|
|
|
In this article we will show, how you can make use of Linux Containers (LXC_) in
|
|
*distributed and heterogeneous development cycles* (TL;DR; jump to the
|
|
:ref:`lxcdev summary`).
|
|
|
|
.. sidebar:: Audience
|
|
|
|
This blog post is written for experienced admins and developers. Readers
|
|
should have a serious meaning about the terms: *distributed*, *merge* and
|
|
*linux container*.
|
|
|
|
**hint**
|
|
|
|
If you have issues with the internet connectivity of your containers read
|
|
section :ref:`internet connectivity docker`.
|
|
|
|
|
|
.. contents::
|
|
:depth: 2
|
|
:local:
|
|
:backlinks: entry
|
|
|
|
|
|
Motivation
|
|
==========
|
|
|
|
Most often in our development cycle, we edit the sources and run some test
|
|
and/or builds by using ``make`` :ref:`[ref] <makefile>` before we commit. This
|
|
cycle is simple and perfect but might fail in some aspects we should not
|
|
overlook.
|
|
|
|
**The environment in which we run all our development processes matters!**
|
|
|
|
The :ref:`makefile` and the :ref:`make install` encapsulate a lot for us, but
|
|
these tools do not have access to all prerequisites. For example, there may
|
|
have dependencies on packages that are installed on developer's desktop, but
|
|
usually are not preinstalled on a server or client system. Another example is;
|
|
settings have been made to the software on developer's desktop that would never
|
|
be set on a *production* system.
|
|
|
|
**Linux Containers are isolate environments**, we use them to not mix up all
|
|
the prerequisites from various projects on developer's desktop.
|
|
|
|
The scripts from :ref:`searx_utils` can divide in those to install and maintain
|
|
software
|
|
|
|
- :ref:`searxng.sh`
|
|
|
|
and the script
|
|
|
|
- :ref:`lxc.sh`
|
|
|
|
with we can scale our installation, maintenance or even development tasks over a
|
|
stack of isolated containers / what we call the:
|
|
|
|
- :ref:`searxng lxc suite`
|
|
|
|
.. _lxcdev install searxng:
|
|
|
|
Gentlemen, start your engines!
|
|
==============================
|
|
|
|
.. _LXD: https://linuxcontainers.org/lxd/introduction/
|
|
.. _archlinux: https://www.archlinux.org/
|
|
|
|
Before you can start with containers, you need to install and initiate LXD_
|
|
once:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ snap install lxd
|
|
$ lxd init --auto
|
|
|
|
And you need to clone from origin or if you have your own fork, clone from your
|
|
fork:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ cd ~/Downloads
|
|
$ git clone https://github.com/searxng/searxng.git searxng
|
|
$ cd searxng
|
|
|
|
.. sidebar:: The ``searxng-archlinux`` container
|
|
|
|
is the base of all our exercises here.
|
|
|
|
The :ref:`lxc-searxng.env` consists of several images, see ``export
|
|
LXC_SUITE=(...`` near by :origin:`utils/lxc-searxng.env#L19`.
|
|
For this blog post we exercise on a archlinux_ image. The container of this
|
|
image is named ``searxng-archlinux``.
|
|
|
|
Lets build the container, but be sure that this container does not already
|
|
exists, so first lets remove possible old one:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh remove searxng-archlinux
|
|
$ sudo -H ./utils/lxc.sh build searxng-archlinux
|
|
|
|
|
|
.. sidebar:: further read
|
|
|
|
- :ref:`lxc.sh install suite`
|
|
- :ref:`installation nginx`
|
|
|
|
To install the complete :ref:`SearXNG suite <searxng lxc suite>` and the HTTP
|
|
proxy :ref:`installation nginx` into the archlinux container run:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh install suite searxng-archlinux
|
|
$ sudo -H ./utils/lxc.sh cmd -- FORCE_TIMEOUT=0 ./utils/searxng.sh install nginx
|
|
$ sudo ./utils/lxc.sh show suite | grep SEARXNG_URL
|
|
...
|
|
[searxng-archlinux] SEARXNG_URL : http://n.n.n.140/searxng
|
|
|
|
.. sidebar:: Fully functional SearXNG suite
|
|
|
|
From here on you have a fully functional SearXNG suite (including a
|
|
:ref:`redis db`).
|
|
|
|
In such a SearXNG suite admins can maintain and access the debug log of the
|
|
services quite easy.
|
|
|
|
In the example above the SearXNG instance in the container is wrapped to
|
|
``http://n.n.n.140/searxng`` to the HOST system. Note, on your HOST system, the
|
|
IP of your ``searxng-archlinux`` container is different to this example. To
|
|
test the instance in the conatiner from outside of the container, in your WEB
|
|
browser on your desktop just open the URL reported in your installation
|
|
|
|
.. _working in containers:
|
|
|
|
In containers, work as usual
|
|
============================
|
|
|
|
Usually you open a root-bash using ``sudo -H bash``. In case of LXC containers
|
|
open the root-bash in the container is done by the ``./utils/lxc.sh cmd
|
|
searxng-archlinux`` command:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux bash
|
|
INFO: [searxng-archlinux] bash
|
|
[root@searxng-archlinux SearXNG]$
|
|
|
|
The prompt ``[root@searxng-archlinux ...]`` signals, that you are the root user
|
|
in the container (GUEST). To debug the running SearXNG instance use:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ ./utils/searxng.sh instance inspect
|
|
...
|
|
use [CTRL-C] to stop monitoring the log
|
|
...
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux ./utils/searxng.sh instance inspect
|
|
...
|
|
use [CTRL-C] to stop monitoring the log
|
|
...
|
|
|
|
|
|
Back in the browser on your desktop open the service http://n.n.n.140/searxng
|
|
and run your application tests while the debug log is shown in the terminal from
|
|
above. You can stop monitoring using ``CTRL-C``, this also disables the *"debug
|
|
option"* in SearXNG's settings file and restarts the SearXNG uwsgi application.
|
|
|
|
Another point we have to notice is that the service :ref:`SearXNG <searxng.sh>`
|
|
runs under dedicated system user account with the same name (compare
|
|
:ref:`create searxng user`). To get a login shell from these accounts, simply
|
|
call:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ ./utils/searxng.sh instance cmd bash -l
|
|
(searx-pyenv) [searxng@searxng-archlinux ~]$ pwd
|
|
/usr/local/searxng
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux ./utils/searxng.sh instance cmd bash -l
|
|
INFO: [searxng-archlinux] ./utils/searxng.sh instance cmd bash -l
|
|
(searx-pyenv) [searxng@searxng-archlinux ~]$ pwd
|
|
/usr/local/searxng
|
|
|
|
The prompt ``[searxng@searxng-archlinux]`` signals that you are logged in as system
|
|
user ``searxng`` in the ``searxng-archlinux`` container and the python *virtualenv*
|
|
``(searxng-pyenv)`` environment is activated.
|
|
|
|
|
|
Wrap production into developer suite
|
|
====================================
|
|
|
|
In this section we will see how to change the *"Fully functional SearXNG suite"*
|
|
from a LXC container (which is quite ready for production) into a developer
|
|
suite. For this, we have to keep an eye on the :ref:`installation basic`:
|
|
|
|
- SearXNG setup in: ``/etc/searxng/settings.yml``
|
|
- SearXNG user's home: ``/usr/local/searxng``
|
|
- virtualenv in: ``/usr/local/searxng/searxng-pyenv``
|
|
- SearXNG software in: ``/usr/local/searxng/searxng-src``
|
|
|
|
With the use of the :ref:`searxng.sh` the SearXNG service was installed as
|
|
:ref:`uWSGI application <searxng uwsgi>`. To maintain this service, we can use
|
|
``systemctl`` (compare :ref:`uWSGI maintenance`).
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: uwsgi@searxng
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux systemctl stop uwsgi@searxng
|
|
|
|
With the command above, we stopped the SearXNG uWSGI-App in the archlinux
|
|
container.
|
|
|
|
The uWSGI-App for the archlinux dsitros is configured in
|
|
:origin:`utils/templates/etc/uwsgi/apps-archlinux/searxng.ini`, from where at
|
|
least you should attend the settings of ``uid``, ``chdir``, ``env`` and
|
|
``http``::
|
|
|
|
env = SEARXNG_SETTINGS_PATH=/etc/searxng/settings.yml
|
|
http = 127.0.0.1:8888
|
|
|
|
chdir = /usr/local/searxng/searxng-src/searx
|
|
virtualenv = /usr/local/searxng/searxng-pyenv
|
|
pythonpath = /usr/local/searxng/searxng-src
|
|
|
|
If you have read the :ref:`Good to know` you remember, that each container
|
|
shares the root folder of the repository and the command ``utils/lxc.sh cmd``
|
|
handles relative path names **transparent**.
|
|
|
|
To wrap the SearXNG installation in the container into a developer one, we
|
|
simple have to create a smylink to the **transparent** reposetory from the
|
|
desktop. Now lets replace the repository at ``searxng-src`` in the container
|
|
with the working tree from outside of the container:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ mv /usr/local/searxng/searxng-src /usr/local/searxng/searxng-src.old
|
|
$ ln -s /share/SearXNG/ /usr/local/searxng/searxng-src
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux \
|
|
mv /usr/local/searxng/searxng-src /usr/local/searxng/searxng-src.old
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux \
|
|
ln -s /share/SearXNG/ /usr/local/searxng/searxng-src
|
|
|
|
Now we can develop as usual in the working tree of our desktop system. Every
|
|
time the software was changed, you have to restart the SearXNG service (in the
|
|
container):
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: uwsgi@searxng
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux systemctl restart uwsgi@searxng
|
|
|
|
|
|
Remember: :ref:`working in containers` .. here are just some examples from my
|
|
daily usage:
|
|
|
|
To *inspect* the SearXNG instance (already described above):
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ ./utils/searx.sh inspect service
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux ./utils/searx.sh inspect service
|
|
|
|
Run :ref:`makefile`, e.g. to test inside the container:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ make test
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux make test
|
|
|
|
|
|
|
|
To install all prerequisites needed for a :ref:`buildhosts`:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ ./utils/searxng.sh install buildhost
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux ./utils/searxng.sh install buildhost
|
|
|
|
|
|
To build the docs on a buildhost :ref:`buildhosts`:
|
|
|
|
.. tabs::
|
|
|
|
.. group-tab:: ``[root@searxng-archlinux SearXNG]`` (GUEST)
|
|
|
|
.. code:: bash
|
|
|
|
$ make docs.html
|
|
|
|
.. group-tab:: desktop (HOST)
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux make docs.html
|
|
|
|
|
|
.. _lxcdev summary:
|
|
|
|
Summary
|
|
=======
|
|
|
|
We build up a fully functional SearXNG suite in a archlinux container:
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh build searxng-archlinux
|
|
$ sudo -H ./utils/lxc.sh install suite searxng-archlinux
|
|
...
|
|
Developer install? (wraps source from HOST into the running instance) [YES/no]
|
|
|
|
To wrap the suite into a developer one answer ``YES`` (or press Enter).
|
|
|
|
.. code:: text
|
|
|
|
link SearXNG's sources to: /share/SearXNG
|
|
=========================================
|
|
|
|
mv -f "/usr/local/searxng/searxng-src" "/usr/local/searxng/searxng-src.backup"
|
|
ln -s "/share/SearXNG" "/usr/local/searxng/searxng-src"
|
|
ls -ld /usr/local/searxng/searxng-src
|
|
|searxng| lrwxrwxrwx 1 searxng searxng ... /usr/local/searxng/searxng-src -> /share/SearXNG
|
|
|
|
On code modification the instance has to be restarted (see :ref:`uWSGI
|
|
maintenance`):
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd searxng-archlinux systemctl restart uwsgi@searxng
|
|
|
|
To access HTTP from the desktop we installed nginx for the services inside the
|
|
container:
|
|
|
|
.. code:: bash
|
|
|
|
$ sudo -H ./utils/lxc.sh cmd -- FORCE_TIMEOUT=0 ./utils/searxng.sh install nginx
|
|
|
|
To get information about the SearxNG suite in the archlinux container we can
|
|
use:
|
|
|
|
.. code:: text
|
|
|
|
$ sudo -H ./utils/lxc.sh show suite searxng-archlinux
|
|
[searxng-archlinux] INFO: (eth0) docs-live: http:///n.n.n.140:8080/
|
|
[searxng-archlinux] INFO: (eth0) IPv6: http://[fd42:555b:2af9:e121:216:3eff:fe5b:1744]
|
|
[searxng-archlinux] uWSGI:
|
|
[searxng-archlinux] SEARXNG_UWSGI_SOCKET : /usr/local/searxng/run/socket
|
|
[searxng-archlinux] environment /usr/local/searxng/searxng-src/utils/brand.env:
|
|
[searxng-archlinux] GIT_URL : https://github.com/searxng/searxng
|
|
[searxng-archlinux] GIT_BRANCH : master
|
|
[searxng-archlinux] SEARXNG_URL : http:///n.n.n.140/searxng
|
|
[searxng-archlinux] SEARXNG_PORT : 8888
|
|
[searxng-archlinux] SEARXNG_BIND_ADDRESS : 127.0.0.1
|
|
|