DD 40: Distro Packaging

10.40. DD 40: Distro Packaging#

Metadata

Status

proposed

10.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.

10.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).

10.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.

10.40.4. Proposed Solution#

This section contains the new guidelines that we want to apply to all our distro packages, specifically the Debian packages.

10.40.4.1. General Considerations#

  • Packages may not enable a systemd service by default.

10.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.

10.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 not sites-enabled.

10.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. 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.

10.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.

10.40.6. Alternatives#

  • Do not ship with distro-specific configuration files, instead only ship tooling to generate config files and set up the database.

10.40.7. Discussion / Q&A#

(This should be filled in with results from discussions on mailing lists / personal communication.)