[taler-docs] branch master updated: draft DD40

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 89dae4a  draft DD40
89dae4a is described below

commit 89dae4ad748d0b5af8fa5dce499aadd0db5676ff
Author: Florian Dold <florian@dold.me>
AuthorDate: Tue Mar 28 13:22:33 2023 +0200

    draft DD40
---
 design-documents/040-distro-packaging.rst | 116 ++++++++++++++++++++++++++++++
 design-documents/index.rst                |   1 +
 2 files changed, 117 insertions(+)

diff --git a/design-documents/040-distro-packaging.rst 
b/design-documents/040-distro-packaging.rst
new file mode 100644
index 0000000..47b96ba
--- /dev/null
+++ b/design-documents/040-distro-packaging.rst
@@ -0,0 +1,116 @@
+DD 40: Distro Packaging
+#######################
+
+.. admonition:: Metadata
+
+   Status
+    proposed
+
+Summary
+=======
+
+This DD discusses considerations for disto packages of GNU Taler components,
+especially with regards to configuration and setup.  We focus on Debian
+packages for now.
+
+Motivation
+==========
+
+The current way that configuration files are handled does not work well with
+automated setup tools and furthermore does not easily allow restoring
+configuration files in ``/etc/`` that the admin deleted or manually modified.
+
+The database configuration is currently handled inconsistently. While some
+packages use Debian's dbconfig-common facilities, others don't, even though
+they require a database for operation.
+
+Requirements
+============
+
+* The distro package should work nicely both for a manual setup
+  process by a sysadmin, as well as for automated installation
+  via helper scripts or other tools.
+* Major differences between different distributions should be minimized, the
+  more code and config templates that can be shared the better.
+
+Proposed Solution
+=================
+
+This section contains the new guidelines that we want to apply to all our
+distro packages, specifically the Debian packages.
+
+General Considerations
+----------------------
+
+* Packages may not enable a systemd service by default.
+
+Config Files: Taler-specific
+----------------------------
+
+The "pristine" version of config files must be installed into
+``/usr/share/taler/etc-original``.  These files should not be modified by
+tooling or the user.  These files may contain direct placeholders or
+placeholder comments that are replaced when the package is configured.
+
+During the postinstall step, the files from ``/usr/share/taler/etc-original``
+are copied to ``/etc/`` (using the ``ucf`` tool on Debian) and, if required,
+placeholders are filled in.
+
+When using tooling to set up Taler, the tooling **should not**
+use files from ``/etc/`` as template, but instead from 
``/usr/share/taler/etc-original`` or alternatively generate custom 
configuration files.
+
+Rationale: Debian manages conffiles in ``/etc/`` with special logic.
+In particular, when files are deleted from ``/etc/taler`` and the package
+is reinstalled (even with ``--reinstall``), there is no easy way for
+tooling (or the admin) to restore the unmodified config files.
+The only way to restore it is ``apt install --reinstall libtalerexchange -o 
Dpkg::Options::="--force-confmiss"``, which might be unsafe as it forces
+overriding of *all* config files of the package.
+
+Config Files: HTTP Server
+-------------------------
+
+The same considerations apply to configuration files of HTTP
+servers (nginx, apache, caddy, ...).  Additionally:
+
+* Configuration files *must* either have a well-known name
+  or particular suffix to easily identify them
+* Configuration files for the HTTP server must not be
+  active by default, i.e. they must be placed in ``sites-available``
+  but not ``sites-enabled``.
+
+Database
+--------
+
+Packages should *not* use ``dbconfig-common``.  Reasons are:
+
+* ``debconfig-common`` is lacking in documentation and very difficult
+  to use for packagers.
+* ``debconfig-common`` offers too much flexibility and
+  asks too many questions to the administrator, especially when
+  reconfiguring a package. The ``taler-merchant`` package
+  currently breaks when the user chooses anything else than ``ident`` auth.
+* Using ``debconfig-common`` makes the database setup logic difficult to test.
+  That is not a problem with simple packages, but most Taler packages
+  require a non-trivial database setup.
+* Very few packages in Debian (<30) actually use ``dbconfig-common``;
+  even fewer are notable or widely used packages.
+
+Definition of Done
+==================
+
+* All Taler and Anastasis packages follow the guidelines from this DD
+* Packages installation has been manually tested
+* Automated setup scripts (``deployment.git``) have been adjusted to use the
+  configuration file templates shipped in the package,
+  instead of using their own config templates.
+
+Alternatives
+============
+
+* Do not ship with distro-specific configuration files, instead only ship
+  tooling to generate config files and set up the database.
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / 
personal communication.)
diff --git a/design-documents/index.rst b/design-documents/index.rst
index 098bca1..a53f814 100644
--- a/design-documents/index.rst
+++ b/design-documents/index.rst
@@ -48,4 +48,5 @@ and protocol.
   037-wallet-transactions-lifecycle.rst
   038-demobanks-protocol-suppliers.rst
   039-taler-browser-integration.rst
+  040-distro-packaging.rst
   999-template

-- 
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.