utils/filtron.sh: add generic documentation

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/admin/filtron.rst

@@ -37,6 +37,7 @@ installed by ``go get`` package management (see `filtron README`_).  If you use
 filtron as middleware, a more isolated setup is recommended.  To simplify such
 an installation and the maintenance of, use our script :ref:`filtron.sh`.
 
+.. _Sample configuration of filtron:
 
 Sample configuration of filtron
 ===============================

docs/build-templates/filtron.rst

@@ -0,0 +1,52 @@
+.. START create user
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: sh
+
+      $ sudo -H useradd --shell /bin/bash --system \\
+          --home-dir "$SERVICE_HOME" \\
+          --comment "Privacy-respecting metasearch engine" $SERVICE_USER
+
+      $ sudo -H mkdir "$SERVICE_HOME"
+      $ sudo -H chown -R "$SERVICE_GROUP:$SERVICE_GROUP" "$SERVICE_HOME"
+
+.. END create user
+
+.. START install go
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: bash
+
+       $ cat > "$GO_ENV" <<EOF
+       export GOPATH=${SERVICE_HOME}/go-apps
+       export PATH=\$PATH:${SERVICE_HOME}/local/go/bin:\$GOPATH/bin
+       EOF
+       $ sudo -i -u "${SERVICE_USER}"
+       (${SERVICE_USER}) $ echo 'source $GO_ENV' >> ~/.profile
+       (${SERVICE_USER}) $ mkdir ${SERVICE_HOME}/local
+       (${SERVICE_USER}) $ wget --progress=bar -O "${GO_TAR}" \\
+                   "${GO_PKG_URL}"
+       (${SERVICE_USER}) $ tar -C ${SERVICE_HOME}/local/go -xzf "${GO_TAR}"
+       (${SERVICE_USER}) $ which go
+       ${SERVICE_HOME}/local/go/bin/go
+
+.. END install go
+
+.. START install filtron
+
+.. tabs::
+
+  .. group-tab:: bash
+
+    .. code-block:: bash
+
+       $ sudo -i -u "${SERVICE_USER}"
+       (${SERVICE_USER}) $ go get -v -u github.com/asciimoo/filtron
+
+.. END install filtron

docs/utils/filtron.sh.rst

@@ -36,6 +36,38 @@ into this user account:
    <utils/templates/lib/systemd/system/filtron.service>`
    (``/lib/systemd/system/filtron.service``).
 
+
+Create user
+===========
+
+.. include:: ../../build/docs/includes/filtron.rst
+   :start-after: START create user
+   :end-before: END create user
+
+
+Install go
+==========
+
+.. include:: ../../build/docs/includes/filtron.rst
+   :start-after: START install go
+   :end-before: END install go
+
+
+Install filtron
+===============
+
+Install :origin:`rules.json <utils/templates/etc/filtron/rules.json>` at
+``/etc/filtron/rules.json`` (see :ref:`Sample configuration of filtron`) and
+install filtron software and systemd unit:
+
+.. include:: ../../build/docs/includes/filtron.rst
+   :start-after: START install filtron
+   :end-before: END install filtron
+
+.. include:: ../../build/docs/includes/filtron.rst
+   :start-after: START install systemd unit
+   :end-before: END install systemd unit
+
 .. _filtron.sh overview:
 
 Overview

utils/filtron.sh

@@ -186,11 +186,7 @@ main() {
                 debug-off)  echo; disable_debug ;;
                 *) usage "$_usage"; exit 42;;
             esac ;;
-        doc)
-            echo
-            echo ".. generic utils/filtron.sh documentation"
-            ;;
-
+        doc) rst-doc ;;
         *) usage "unknown or missing command $1"; exit 42;;
     esac
 }
@@ -469,6 +465,32 @@ This removes apache site ${APACHE_FILTRON_SITE}."
     apache_remove_site "$APACHE_FILTRON_SITE"
 }
 
+rst-doc() {
+
+    eval "echo \"$(< "${REPO_ROOT}/docs/build-templates/filtron.rst")\""
+
+    echo -e "\n.. START install systemd unit"
+    cat <<EOF
+.. tabs::
+
+   .. group-tab:: systemd
+
+      .. code:: bash
+
+EOF
+    eval "echo \"$(< "${TEMPLATES}/${SERVICE_SYSTEMD_UNIT}")\"" | prefix_stdout "         "
+    echo -e "\n.. END install systemd unit"
+
+    # for DIST_NAME in ubuntu-20.04 arch fedora; do
+    #     (
+    #         DIST_ID=${DIST_NAME%-*}
+    #         DIST_VERS=${DIST_NAME#*-}
+    #         [[ $DIST_VERS =~ $DIST_ID ]] && DIST_VERS=
+    #         # ...
+    #     )
+    # done
+}
+
 # ----------------------------------------------------------------------------
 main "$@"
 # ----------------------------------------------------------------------------

utils/searx.sh

@@ -248,7 +248,6 @@ main() {
                 *) usage "$_usage"; exit 42;;
             esac ;;
         doc) rst-doc;;
-
         *) usage "unknown or missing command $1"; exit 42;;
     esac
 }