1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
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.)
|
