040-distro-packaging.rst (5283B)
1 DD 40: Distro Packaging 2 ####################### 3 4 .. admonition:: Metadata 5 6 Status 7 proposed 8 9 Summary 10 ======= 11 12 This DD discusses considerations for disto packages of GNU Taler components, 13 especially with regards to configuration and setup. We focus on Debian 14 packages for now. 15 16 Motivation 17 ========== 18 19 The current way that configuration files are handled does not work well with 20 automated setup tools and furthermore does not easily allow restoring 21 configuration files in ``/etc/`` that the admin deleted or manually modified. 22 23 The database configuration is currently handled inconsistently. While some 24 packages use Debian's dbconfig-common facilities, others don't, even though 25 they require a database for operation. 26 27 The guidelines in this document are based on pratical experience 28 with third parties setting up Taler based on the Debian packages 29 and scripting supplied by us (i.e. ``deployment.git/netzbon``). 30 31 Requirements 32 ============ 33 34 * The distro package should work nicely both for a manual setup 35 process by a sysadmin, as well as for automated installation 36 via helper scripts or other tools. 37 * Major differences between different distributions should be minimized, the 38 more code and config templates that can be shared the better. 39 40 Proposed Solution 41 ================= 42 43 This section contains the new guidelines that we want to apply to all our 44 distro packages, specifically the Debian packages. 45 46 General Considerations 47 ---------------------- 48 49 * Packages may not enable a systemd service by default. 50 51 Config Files: Taler-specific 52 ---------------------------- 53 54 The "pristine" version of config files must be installed into 55 ``/usr/share/taler/etc-original``. These files should not be modified by 56 tooling or the user. These files may contain direct placeholders or 57 placeholder comments that are replaced (but not in-place, only in ``etc/``!) 58 when the package is configured. 59 60 During the postinstall step, the files from ``/usr/share/taler/etc-original`` 61 are copied to ``/etc/`` (using the ``ucf`` tool on Debian) and, if required, 62 placeholders are filled in. 63 64 When using tooling to set up Taler, the tooling **should not** 65 use files from ``/etc/`` as template, but instead from ``/usr/share/taler/etc-original`` or alternatively generate custom configuration files. 66 67 Rationale: Debian manages conffiles in ``/etc/`` with special logic. 68 In particular, when files are deleted from ``/etc/taler`` and the package 69 is reinstalled (even with ``--reinstall``), there is no easy way for 70 tooling (or the admin) to restore the unmodified config files. 71 The only way to restore it is ``apt install --reinstall libtalerexchange -o Dpkg::Options::="--force-confmiss"``, which might be unsafe as it forces 72 overriding of *all* config files of the package. 73 74 Config Files: HTTP Server 75 ------------------------- 76 77 The same considerations apply to configuration files of HTTP 78 servers (nginx, apache, caddy, ...). Additionally: 79 80 * Configuration files *must* either have a well-known name 81 or particular suffix to easily identify them 82 83 * In particular, file names like ``sites-available/exchange.$domain`` 84 are unacceptable, as they are very difficult to uninstall 85 or remove when ``$domain`` is changed. 86 87 * Configuration files for the HTTP server must not be 88 active by default, i.e. they must be placed in ``sites-available`` 89 but not ``sites-enabled``. 90 91 Database 92 -------- 93 94 Packages should *not* use ``dbconfig-common``. Reasons are: 95 96 * ``dbconfig-common`` is lacking in documentation and very difficult 97 to use for packagers. 98 * ``dbconfig-common`` offers too much flexibility and 99 asks too many questions to the administrator, especially when 100 reconfiguring a package. The ``taler-merchant`` package 101 currently breaks when the user chooses anything else than ``ident`` auth. 102 * Using ``debconfig-common`` makes the database setup logic difficult to test. 103 That is not a problem with simple packages, but most Taler packages 104 require a non-trivial database setup. 105 * Very few packages in Debian (<30) actually use ``dbconfig-common``; 106 even fewer are notable or widely used packages. 107 108 Instead, each package should document how to set up 109 the database and *optionally* ship an executable named 110 ``taler-$component-dbconfig`` that: 111 112 1. Creates the database and adjusts permissions 113 2. Checks if the database is accessible 114 3. Runs ``taler-$component-dbinit`` if applicable 115 and unless supressed by the user. 116 117 For now, our tooling shall only support PostgreSQL and only set up ``ident`` 118 authentication or set up ``password`` authentication with a random password for 119 components that do not support DB connections via unix domain sockets. 120 121 Definition of Done 122 ================== 123 124 * All Taler and Anastasis packages follow the guidelines from this DD 125 * Packages installation has been manually tested 126 * Automated setup scripts (``deployment.git``) have been adjusted to use the 127 configuration file templates shipped in the package, 128 instead of using their own config templates. 129 130 Alternatives 131 ============ 132 133 * Do not ship with distro-specific configuration files, instead only ship 134 tooling to generate config files and set up the database. 135 136 Discussion / Q&A 137 ================ 138 139 (This should be filled in with results from discussions on mailing lists / personal communication.)