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