diff options
Diffstat (limited to 'design-documents/040-distro-packaging.rst')
| -rw-r--r-- | design-documents/040-distro-packaging.rst | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/design-documents/040-distro-packaging.rst b/design-documents/040-distro-packaging.rst new file mode 100644 index 00000000..13131359 --- /dev/null +++ b/design-documents/040-distro-packaging.rst @@ -0,0 +1,139 @@ +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. + +The guidelines in this document are based on pratical experience +with third parties setting up Taler based on the Debian packages +and scripting supplied by us (i.e. ``deployment.git/netzbon``). + +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 (but not in-place, only in ``etc/``!) +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 + + * In particular, file names like ``sites-available/exchange.$domain`` + are unacceptable, as they are very difficult to uninstall + or remove when ``$domain`` is changed. + +* 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: + +* ``dbconfig-common`` is lacking in documentation and very difficult + to use for packagers. +* ``dbconfig-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. + +Instead, each package should document how to set up +the database and *optionally* ship an executable named +``taler-$component-dbconfig`` that: + +1. Creates the database and adjusts permissions +2. Checks if the database is accessible +3. Runs ``taler-$component-dbinit`` if applicable + and unless supressed by the user. + +For now, our tooling shall only support PostgreSQL and only set up ``ident`` +authentication or set up ``password`` authentication with a random password for +components that do not support DB connections via unix domain sockets. + +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.) |