12.40. DD 40: Distro Packaging¶
12.40.1. 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.
12.40.2. 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
).
12.40.3. 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.
12.40.4. Proposed Solution¶
This section contains the new guidelines that we want to apply to all our distro packages, specifically the Debian packages.
12.40.4.1. General Considerations¶
Packages may not enable a systemd service by default.
12.40.4.2. 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.
12.40.4.3. 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 notsites-enabled
.
12.40.4.4. 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. Thetaler-merchant
package currently breaks when the user chooses anything else thanident
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:
Creates the database and adjusts permissions
Checks if the database is accessible
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.
12.40.5. 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.
12.40.6. Alternatives¶
Do not ship with distro-specific configuration files, instead only ship tooling to generate config files and set up the database.
12.40.7. Discussion / Q&A¶
(This should be filled in with results from discussions on mailing lists / personal communication.)