diekershoff.net

/pub/diekershoff/tobias

In the End, it was almost easy

misc #debian #apt #package
Estimated time to read: 6 min.
So 10 Dezember 2017

Though the way towards building my first package for the Debian package manager was hard. And I don't even know anymore for sure why. Because in the end, once knowing the progress, building the package was almost easy. Said after N failed attempts to do so.

As hinted at a different place I used some time at the Friendica Hackathon the other week in Berlin, to build a preliminary Debian package for the project. Actually it is two, one for the core and one for the addons. They are not ready, and there is a long way to go until they are. At least I think so.

Nevertheless I wanted to write down some notes about the process to keep them somewhere and maybe help others in the process.

Links

Before I begin, let me drop some links that were helpful for me:

And you should have installed dpkg-dev, fakeroot and lintian packages.

Directory structure

So, Friendica sources are programming fun and hence the git-repository clones sit in $HOME/programming/friendica. To be precise in the friendica and friendica-addons sub-directories. Just clone them into there.

Furthermore we need a directory, per package, that contains the files that should be packed in the places where we expect them to be once the package is installed. Every package needs a place to store the documentation files in /usr/share/doc/. Another place is for the other contents of the package usr/share/friendica. And for all the configuration of the package itself, there has to be a special DEBIAN subdirectory.

So we got a basic layout of the directory structure like:

$HOME/programming/friendica/friendica-3.5.4-1
├── DEBIAN
└── usr
    └── share
        ├── doc
        │   └── friendica
        └── friendica

First checkout version 3.5.4 in $HOME/programming/friendica/friendica and then copy over the files to the appropriate locations in the fake filesystem under $HOME/programming/friendica/friendica-3.5.4. The contents of the doc directory, all go into usr/share/doc/friendica. The Webapps Policy Manual says the proper place for static and dynamic interpreted content is usr/share/friendica/www so the files from the repository (except the documentation) goes there. As Friendica needs to be able to access the documentation files from http://example.com/help I added a symlink from the usr/share/doc/friendica directory to usr/share/friendica/www/doc.

Friendica has some example configuration files for lighttpd and nginx in the mods directory, that is not needed for running the communications server with Apache. On the other hand I don't want to exclude this information from the package. So I placed them into the usr/share/friendica/example directory.

$HOME/programming/friendica/friendica-3.5.4-1
├── DEBIAN
└── usr
    └── share
        ├── doc
        │   └── friendica
        └── friendica
            └── examples
            └─── www

So with all of the files from the Friendica repository in place, there are some important files needed to build a Debian package.

Important files

Every package must have a copyright file in their documentation directory, alongside with a README.debian and changelog.debian file. For the configuration of the package you need a control file in the DEBIAN subdirectory. Additionally I needed a postinst file in the DEBIAN subdirectory to perform some commands after the installation of the package to simplify the setup process by the user of the package.

The DEBIAN/control file contains some meta information about the package. Its name, version, which package section it belongs to, who the maintainer is. But also on which other packages it depends upon and what packages might be good to have. For the Friendica package mine looks like this at the moment:

Package: friendica
Version: 3.5.4-1
Section: web
Priority: optional
Architecture: all
Depends: php (>=5.4), php-cli (>=5.4), php-curl, php-gd, php-mbstring, php-mcrypt, php-mysql, php-xml, python, python3, default-mysql-server (>= 1.0.2), default-mysql-client (>= 1.0.2), default-mta
Recommends: friendica-addon (=3.5.4-1)
Suggests: php-imagick, certbot, php-imap
Maintainer: Tobias Diekershoff 
Description: Friendica Social Communications Server
 Welcome to the free social web.
 .
 Friendica is a communications platform for integrated social communications
 utilising decentralised communications and linkage to several indie social
 projects - as well as popular mainstream providers.
 .
 Our mission is to free our friends and families from the clutches of
 data-harvesting corporations, and pave the way to a future where social
 communications are free and open and flow between alternate providers
 as easily as email does today.

The description text is taken from the project README file. We recommend the installation of the addon package, of the same version, as well. The PHP packages for imagick and IMAP would be nice for some of Friendicas features, but not a must have. And with the certbot package it may be easier to get a certificate for HTTPS configuration, but again, it is not a must have. The package clearly aims at Apache2 as a web server, ensures that all needed PHP packages are installed and that there is a MySQL compatible database server (in the case of Debian Stretch this will be MariaDB) alongside a working MTA.

The changelog.Debian(.gz) file looks like this at the moment:

friendica (3.5.4-1) stable; urgency=low

  * initial work on a DEB package

 -- Tobias Diekershoff   Mon, 04 Dec 2017 21:37:00 +0100

The desired format is documented here in the Debian guidelines. In time I guess this will grow somewhat.

And the README.debian file just contains some information on how to proceed with the Friendica installation after the package was installed.

The changelog.DEBIAN and the project changelog file need to be zipped, without timestamps; gzip --best -n will do this.

The copyright file must be located in the usr/share/doc/friendica directory and must contain all copyright information about all shipped files. In the simplest form it would look something like this:

Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: Friendica
Source: https://github.com/friendica/friendica

Files: * Copyright: 2017-2017 Friendica Community License: AGPL-3+

but as Friendica ships with the needed libraries it gets more lenghy. Every library needs it own information block attributing the author and the license. These blocks contain the Files, Copyright and License lines with an empty line above each block for separation.

Building the Package

So, lets build the package. This has to be done from the parent directory of the directory containing the fake-filesystem. In my case this is $HOME/programming/friendica.

The command for building the package is

fakeroot dpkg-deb --build friendica-3.5.4-1

which will generate a DEB archive with the name friendica-3.5.4-1.deb in the current directory. Note that the version numbers have to match between the call above, the version in the DEBIAN/control file and the directory name. The fakeroot command is used to get the file ownership to the root user and not your account.

Now you should check the generated package with lintian for errors and warnings.

lintian friendica-3.5.4-2.deb --no-tag-display-limit

Even if we don't plan to include the package in the Debian repositories ATM, I think it is good to minimize the warnings and erase all the errors if possible. Normally lintian would only show one warning a couple of times, with the --no-tag-display-limit you get to see all orrurences of a warning or error.

And this was my, finally successful, very pragmatic way on building packages for Debian.

Please note, this packages for Debian assume some things (the policy manual explicitely says one should not assume anything) like that one wants to run Friendica on top of the Apache2, MySQL, PHP stack--not using any other webserver. So if these packages become available, and you want to use e.g. nginx, you will have to perform a manual installation most likely.


theme last update

november 2017

License

Unless otherwhise noted the contents of this homepage are governed by a Creative Commins license (CC-BY) that essentially means you may use my content to remix it into your work but name me.

Contact

You can send me an email to tobiasdiekershoff.net or see the imprint for further contacts channels.

Made with

Powered by Pelican. Theme inspired by Bootply using the Sandstone color schema.