Merge pull request #66 from return42/docker-buildx

review of docker entry point & docker documentation

Dockerfile

@@ -10,7 +10,7 @@ ARG SEARX_UID=977
 RUN addgroup -g ${SEARX_GID} searx && \
     adduser -u ${SEARX_UID} -D -h /usr/local/searx -s /bin/sh -G searx searx
 
-ENV INSTANCE_NAME=searx \
+ENV INSTANCE_NAME=searxng \
     AUTOCOMPLETE= \
     BASE_URL= \
     MORTY_KEY= \

Makefile

@@ -54,6 +54,8 @@ PHONY += test ci.test test.shell
 ci.test: test.pep8 test.pylint test.unit test.robot
 test:    test.pep8 test.pylint test.unit test.robot test.shell
 test.shell:
+	$(Q)shellcheck -x -s dash \
+		dockerfiles/docker-entrypoint.sh
 	$(Q)shellcheck -x -s bash \
 		utils/brand.env \
 		./manage \

dockerfiles/docker-entrypoint.sh

@@ -1,62 +1,66 @@
 #!/bin/sh
 
 help() {
-	printf "Command line:\n\n"
+    cat <<EOF
-	printf "  -h  Display this help\n"
+Command line:
-	printf "  -d  Dry run to update the configuration files.\n"
+  -h  Display this help
-	printf "  -f  Always update on the configuration files (existing files are renamed with the .old suffix)\n"
+  -d  Dry run to update the configuration files.
-	printf "      Without this option, the new configuration files are copied with the .new suffix\n"
+  -f  Always update on the configuration files (existing files are renamed with
-	printf "\nEnvironment variables:\n\n"
+      the .old suffix).  Without this option, the new configuration files are
-	printf "  INSTANCE_NAME settings.yml : general.instance_name\n"
+      copied with the .new suffix
-	printf "  AUTOCOMPLETE  settings.yml : search.autocomplete\n"
+Environment variables:
-	printf "  BASE_URL      settings.yml : server.base_url\n"
+  INSTANCE_NAME settings.yml : general.instance_name
-	printf "  MORTY_URL     settings.yml : result_proxy.url\n"
+  AUTOCOMPLETE  settings.yml : search.autocomplete
-	printf "  MORTY_KEY     settings.yml : result_proxy.key\n"
+  BASE_URL      settings.yml : server.base_url
-	printf "  BIND_ADDRESS  uwsgi bind to the specified TCP socket using HTTP protocol. Default value: \"${DEFAULT_BIND_ADDRESS}\"\n"
+  MORTY_URL     settings.yml : result_proxy.url
-	printf "\nVolume:\n\n"
+  MORTY_KEY     settings.yml : result_proxy.key
-	printf "  /etc/searx    the docker entry point copies settings.yml and uwsgi.ini in this directory (see the -f command line option)\n"
+  BIND_ADDRESS  uwsgi bind to the specified TCP socket using HTTP protocol.
-	echo
+                Default value: ${DEFAULT_BIND_ADDRESS}
-	exit 0
+Volume:
+  /etc/searx    the docker entry point copies settings.yml and uwsgi.ini in
+                this directory (see the -f command line option)"
+
+EOF
 }
 
 export DEFAULT_BIND_ADDRESS="0.0.0.0:8080"
-if [ -z "${BIND_ADDRESS}" ]; then
+export BIND_ADDRESS="${BIND_ADDRESS:-${DEFAULT_BIND_ADDRESS}}"
-    export BIND_ADDRESS="${DEFAULT_BIND_ADDRESS}"
-fi
-
-# Parse special command line
-# see docs/admin/installation-docker.rst
-# display the help message without the version
-if [ "$1" = "help" ]; then
-	help
-fi
-
-# Version
-export SEARX_VERSION=$(su searx -c 'python3 -c "import six; import searx.version; six.print_(searx.version.VERSION_STRING)"' 2>/dev/null)
-printf 'searx version %s\n\n' "${SEARX_VERSION}"
 
 # Parse command line
 FORCE_CONF_UPDATE=0
 DRY_RUN=0
+
 while getopts "fdh" option
 do
     case $option in
-	f)
+
-	    FORCE_CONF_UPDATE=1
+        f) FORCE_CONF_UPDATE=1 ;;
-	    ;;
+        d) DRY_RUN=1 ;;
-	d)
+
-	    DRY_RUN=1
-	    ;;
         h)
             help
+            exit 0
+            ;;
+        *)
+            echo "unknow option ${option}"
+            exit 42
+            ;;
     esac
 done
 
+get_searx_version(){
+    su searx -c \
+       'python3 -c "import six; import searx.version; six.print_(searx.version.VERSION_STRING)"' \
+       2>/dev/null
+}
+
+SEARX_VERSION="$(get_searx_version)"
+export SEARX_VERSION
+echo "searx version ${SEARX_VERSION}"
+
 # helpers to update the configuration files
 patch_uwsgi_settings() {
     CONF="$1"
-
-    # Nothing
 }
 
 patch_searx_settings() {
@@ -74,7 +78,8 @@ patch_searx_settings() {
        "${CONF}"
 
     # Morty configuration
-    if [ ! -z "${MORTY_KEY}" -a ! -z "${MORTY_URL}" ]; then
+
+    if [ -n "${MORTY_KEY}" ] && [ -n "${MORTY_URL}" ]; then
         sed -i -e "s/image_proxy : False/image_proxy : True/g" \
             "${CONF}"
         cat >> "${CONF}" <<-EOF
@@ -98,7 +103,7 @@ update_conf() {
     if [ -f "${CONF}" ]; then
         if [ "${REF_CONF}" -nt "${CONF}" ]; then
             # There is a new version
-	    if [ $FORCE_CONF_UPDATE -ne 0 ]; then
+            if [ "$FORCE_CONF_UPDATE" -ne 0 ]; then
                 # Replace the current configuration
                 printf '⚠️  Automaticaly update %s to the new version\n' "${CONF}"
                 if [ ! -f "${OLD_CONF}" ]; then
@@ -124,7 +129,7 @@ update_conf() {
 }
 
 # make sure there are uwsgi settings
-update_conf ${FORCE_CONF_UPDATE} "${UWSGI_SETTINGS_PATH}" "/usr/local/searx/dockerfiles/uwsgi.ini" "patch_uwsgi_settings"
+update_conf "${FORCE_CONF_UPDATE}" "${UWSGI_SETTINGS_PATH}" "/usr/local/searx/dockerfiles/uwsgi.ini" "patch_uwsgi_settings"
 
 # make sure there are searx settings
 update_conf "${FORCE_CONF_UPDATE}" "${SEARX_SETTINGS_PATH}" "/usr/local/searx/searx/settings.yml" "patch_searx_settings"
@@ -135,7 +140,6 @@ if [ $DRY_RUN -eq 1 ]; then
     exit
 fi
 
-#
 touch /var/run/uwsgi-logrotate
 chown -R searx:searx /var/log/uwsgi /var/run/uwsgi-logrotate
 unset MORTY_KEY

docs/admin/installation-docker.rst

@@ -1,60 +1,171 @@
+
 .. _installation docker:
 
 ===================
 Docker installation
 ===================
 
-.. contents:: Contents
+.. _ENTRYPOINT: https://docs.docker.com/engine/reference/builder/#entrypoint
-   :depth: 2
+.. _searxng-docker: https://github.com/searxng/searxng-docker
-   :local:
+.. _[filtron]: https://hub.docker.com/r/dalf/filtron
-   :backlinks: entry
+.. _[morty]: https://hub.docker.com/r/dalf/morty
+.. _[caddy]: https://hub.docker.com/_/caddy
 
-----
+.. sidebar:: info
 
-Docker image searxng/searxng
+   - :origin:`Dockerfile`
-============================
+   - `searxng/searxng @dockerhub <https://hub.docker.com/r/searxng/searxng>`_
+   - `Docker overview <https://docs.docker.com/get-started/overview>`_
+   - `Docker Cheat Sheet <https://www.docker.com/sites/default/files/d8/2019-09/docker-cheat-sheet.pdf>`_
+   - `Alpine Linux <https://alpinelinux.org>`_ `(wiki) <https://en.wikipedia.org/wiki/Alpine_Linux>`__ `apt packages <https://pkgs.alpinelinux.org/packages>`_
+   - Alpine's ``/bin/sh`` is :man:`dash`
 
+.. tip::
 
-The docker image is `searxng/searxng <https://hub.docker.com/r/searxng/searxng>`_ (based on `github.com/searxng/searxng <https://github.com/searxng/searxng>`_).
+   If you intend to create a public instance using Docker, use our well
+   maintained searxng-docker_ image which includes
 
-Make sure you have `installed Docker <https://docs.docker.com/get-docker/>`_.  For instance, you can deploy a local instance:
+   - :ref:`protection <searx filtron>` `[filtron]`_,
+   - a :ref:`result proxy <searx morty>` `[morty]`_ and
+   - a HTTPS reverse proxy `[caddy]`_.
+
+Make sure you have `installed Docker <https://docs.docker.com/get-docker/>`_ and
+on Linux, don't forget to add your user to the docker group (log out and log
+back in so that your group membership is re-evaluated):
 
 .. code:: sh
 
-    export PORT=80
+   $ sudo usermod -a -G docker $USER
-    docker pull searxng/searxng
-    docker run --rm -d -v ${PWD}/searx:/etc/searx -p $PORT:8080 -e BASE_URL=http://localhost:$PORT/ searxng/searxng
 
-Go to ``http://localhost:$PORT``.
 
-Inside ``${PWD}/searx``, you will find ``settings.yml`` and ``uwsgi.ini``.
+searxng/searxng
-You can modify these files according to your needs  and restart the Docker image.
+===============
+
+.. sidebar:: ``docker run``
+
+   - `-\-rm  <https://docs.docker.com/engine/reference/run/#clean-up---rm>`__
+     automatically clean up when container exits
+   - `-d <https://docs.docker.com/engine/reference/run/#detached--d>`__ start
+     detached container
+   - `-v <https://docs.docker.com/engine/reference/run/#volume-shared-filesystems>`__
+     mount volume ``HOST:CONTAINER``
+
+The docker image is based on :origin:`Dockerfile` and available from
+`searxng/searxng @dockerhub`_.  Using the docker image is quite easy, for
+instance you can pull the `searxng/searxng @dockerhub`_ image and deploy a local
+instance using `docker run <https://docs.docker.com/engine/reference/run/>`_:
+
+.. code:: sh
+
+   $ mkdir my-instance
+   $ cd my-instance
+   $ export PORT=8080
+   $ docker pull searxng/searxng
+   $ docker run --rm \
+                -d -p ${PORT}:8080 \
+                -v "${PWD}/searx:/etc/searx" \
+                -e "BASE_URL=http://localhost:$PORT/" \
+                -e "INSTANCE_NAME=my-instance" \
+                searxng/searxng
+   2f998.... # container's ID
+
+Open your WEB browser and visit the URL:
+
+.. code:: sh
+
+   $ xdg-open "http://localhost:$PORT"
+
+Inside ``${PWD}/searx``, you will find ``settings.yml`` and ``uwsgi.ini``.  You
+can modify these files according to your needs and restart the Docker image.
+
+.. code:: sh
+
+   $ docker container restart 2f998
+
+Use command ``container ls`` to list running containers, add flag `-a
+<https://docs.docker.com/engine/reference/commandline/container_ls>`__ to list
+exited containers also.  With ``container stop`` a running container can be
+stoped.  To get rid of a container use ``container rm``:
+
+.. code:: sh
+
+   $ docker container ls
+   CONTAINER ID   IMAGE             COMMAND                  CREATED         ...
+   2f998d725993   searxng/searxng   "/sbin/tini -- /usr/…"   7 minutes ago   ...
+
+   $ docker container stop 2f998
+   $ docker container rm 2f998
+
+.. sidebar:: Warning
+
+   This might remove all docker items, not only those from searxng.
+
+If you won't use docker anymore and want to get rid of all conatiners & images
+use the following *prune* command:
+
+.. code:: sh
+
+   $ docker stop $(docker ps -aq)       # stop all containers
+   $ docker system prune                # make some housekeeping
+   $ docker rmi -f $(docker images -q)  # drop all images
+
+
+shell inside container
+----------------------
+
+.. sidebar:: Bashism
+
+   - `A tale of two shells: bash or dash <https://lwn.net/Articles/343924/>`_
+   - `How to make bash scripts work in dash <http://mywiki.wooledge.org/Bashism>`_
+   - `Checking for Bashisms  <https://dev.to/bowmanjd/writing-bash-scripts-that-are-not-only-bash-checking-for-bashisms-and-testing-with-dash-1bli>`_
+
+Like in many other distributions, Alpine's `/bin/sh
+<https://wiki.ubuntu.com/DashAsBinSh>`__ is :man:`dash`.  Dash is meant to be
+`POSIX-compliant <https://pubs.opengroup.org/onlinepubs/9699919799>`__.
+Compared to debian, in the Alpine image :man:`bash` is not installed.  The
+:origin:`dockerfiles/docker-entrypoint.sh` script is checked *against dash*
+(``make tests.shell``).
+
+To open a shell inside the container:
+
+.. code:: sh
+
+   $ docker exec -it 2f998 sh
+
+
+Build the image
+===============
+
+It's also possible to build SearXNG from the embedded :origin:`Dockerfile`::
+
+   $ git clone https://github.com/searxng/searxng.git
+   $ cd searx
+   $ make docker.build
+   ...
+   Successfully built 49586c016434
+   Successfully tagged searxng/searxng:latest
+   Successfully tagged searxng/searxng:1.0.0-209-9c823800-dirty
+
+   $ docker images
+   REPOSITORY        TAG                        IMAGE ID       CREATED          SIZE
+   searxng/searxng   1.0.0-209-9c823800-dirty   49586c016434   13 minutes ago   308MB
+   searxng/searxng   latest                     49586c016434   13 minutes ago   308MB
+   alpine            3.13                       6dbb9cc54074   3 weeks ago      5.61MB
 
 
 Command line
-------------
+============
 
+.. sidebar:: docker run
+
+   Use flags ``-it`` for `interactive processes
+   <https://docs.docker.com/engine/reference/run/#foreground>`__.
+
+In the :origin:`Dockerfile` the ENTRYPOINT_ is defined as
+:origin:`dockerfiles/docker-entrypoint.sh`
 
 .. code:: sh
 
     docker run --rm -it searxng/searxng -h
 
-.. program-output:: ../dockerfiles/docker-entrypoint.sh help
+.. program-output:: ../dockerfiles/docker-entrypoint.sh -h
-
-
-Build the image
----------------
-
-It's also possible to build SearXNG from the embedded Dockerfile.
-
-.. code:: sh
-
-   git clone https://github.com/searxng/searxng.git
-   cd searx
-   make docker.build
-
-
-Public instance
-===============
-
-If you intend to create a public instance using Docker, see https://github.com/searx/searx-docker