Print | confusa Space

The tools provided by debhelper, as they are used in the Debian new maintainer's guide are somewhat aimed towards Makefile projects. Since Confusa is a LAMP-web-application, the tools have to be used a bit differently than described in the guide. Nevertheless, one can start by

We assume version 0.3.1 in this document. You should of-course replace any occurences of this with the respective version.

1. Start of by getting a SCM-content-free tarball (i.e. without the .git directories) of Confusa by invoking the following in a checkout out source directory

git archive --format=tar --prefix=confusa-0.6.1/ v0.6.1 | gzip > confusa_v0.6.1.orig.tar.gz

2. Extract the package to it's own directory:

tar xvzf confusa_v0.6.1.orig.tar.gz

This will create a folder called confusa-0.6.1 with Confusa's source.

3. Move into the newly created directory and generate the Debian structure using

cd confusa-0.6.1/
dh_make -e your.maintainer@address -f ../confusa_0.6.1.orig.tar.gz

Confusa does not have a Makefile, so it is probably best to go for the 4th (makefileless) option. Get rid of possible leftover .gitignore files by invoking

 find . -type f -name ".gitignore" -delete

Make .sh-files executable by calling

find . -type f -name "*.sh" -exec chmod -v u+x {} \;

Any possible more-finegrained concept of yours to deal with permissions and SCM files will probably be better than this chainsaw method - it's just "something that works", not more.

4. Now adapt the files in the folder debian/. Important ones to change are along with an example of how they are used in Confusa

Changelog - determine the Confusa version

confusa (0.6.1-1) unstable; urgency=low

  * Fix Do not follow empty subscriber references.
  * Fix Make sure db-password is included when using db_lib.sh

 -- Henrik Austad   Mon, 03 May 2010 13:10:10 +0200

.....

confusa (v0.3.1) unstable; urgency=low

  * Bugfix release
  * Unsubscribed and suspended subscriber-users can not issue certificates any
    more
  * Adapt authentication to new simplesamlphp SAML:SP Auth module
  * NREN admin now able to initially set his/her subscriber

 -- Thomas Zangerl <email@address>  Wed, 28 Oct 2009 15:59:59 +0100

Control - identify dependencies, package section, description and architecture

Source: confusa
Section: web
Priority: extra
Maintainer: Henrik Austad 
Build-Depends: debhelper (>= 7)
Standards-Version: 3.8.3

Package: confusa
Architecture: all
Depends: php5 (>= 5.2.0), apache2.2-common (>=2.2.9), libapache2-mod-php5 (>= 5.2.0) | php5-cgi (>= 5.2.0), openssl (>=0.9.8g), php-xml-parser (>= 1.2.8), php5-mhash (>= 5.2.0), php5-mcrypt (>= 5.2.0), openssl-blacklist (>= 0.4.2), simplesamlphp, mysql-server-5.0 (>= 5.0.0), php5-mysql (>= 5.2.0), libphp-phpmailer (>= 1.73), php5-curl (>= 5.2.0), php-pear, smarty(>=2.6.20), dbconfig-common (>= 1.8.39), ucf (>= 3.0000), ${misc:Depends}
Suggests: pwgen, logrotate
Conflicts: confusa-disco
Description: A webportal for mapping a federated identity onto a X.509 certificate
 Confusa is a secure and configurable portal written in PHP that issues
 end-entity X.509 certificates based on assertions by identity providers (IdPs).
 Confusa can sign these certificates with its own private key or contact an
 Online-CA for signing them.

Compat - determine the version of the debhelper tools that are used for building, e.g 7
copyright - put your copyright information here. If the software has a known license like GPLv3, LGPL or apache-license, reference the respective file in /usr/share/common-licenses instead of printing the full text

dirs - directories that the package will create, for confusa this is for example

usr/share
usr/share/confusa
var/cache/confusa
var/lib/confusa
etc/confusa
etc/logrotate.d/
usr/share/dbconfig-common/data/confusa/install
usr/share/dbconfig-common/data/confusa/upgrade/mysql

docs - the documents that are going to be installed in /usr/share/doc, e.g. README
files - the .deb packages that will be the result of the package build process. In our case that is
```
confusa_0.6.1_all.deb web extra
```

rules - the most important file. This is a makefile-like sequence of debhelper scripts that are to be executed in order to build the package. Most of the dh_* names are self-explanatory, otherwise there is a manpage for all of them. Confusa's current rules file looks as follows (probably that could be done much simpler, the first configuration that proved to work was simply kept in that case).

 #!/usr/bin/make -f

# Add here any variable or target overrides you need.
clean:
	dh_testdir
	dh_testroot
	dh_clean

build:

install_app_data:
	dh_testdir
	dh_testroot
	dh_clean -k
	dh_installdirs
	cp -Rf cert_handle debian/confusa/usr/share/confusa/
	cp config/* debian/confusa/etc/confusa/
	cp -Rf dictionaries debian/confusa/usr/share/confusa/
	cp -Rf include debian/confusa/usr/share/confusa/
	cp -Rf init debian/confusa/usr/share/confusa/
	cp -Rf programs debian/confusa/usr/share/confusa/
	cp -Rf robot_www debian/confusa/usr/share/confusa/
	cp -Rf www debian/confusa/usr/share/confusa/
	cp -Rf lib debian/confusa/usr/share/confusa/
	cp VERSION debian/confusa/usr/share/confusa/
	# dbconfig-common
	# All files needed to upgrade the database from the initial revision to current point (look at what's done in existing packages)
	cp mysql_create.sql debian/confusa/usr/share/dbconfig-common/data/confusa/install/mysql
	cp upgrade_0.4.0~rc0.sql debian/confusa/usr/share/dbconfig-common/data/confusa/upgrade/mysql/0.4.0~rc0
	cp upgrade_0.4.0.sql debian/confusa/usr/share/dbconfig-common/data/confusa/upgrade/mysql/0.4.0
	cp upgrade_0.5.0~rc1.sql debian/confusa/usr/share/dbconfig-common/data/confusa/upgrade/mysql/0.5.0~rc1
	cp upgrade_0.5.3.sql debian/confusa/usr/share/dbconfig-common/data/confusa/upgrade/mysql/0.5.3
	cp upgrade_0.6.0~rc0.sql debian/confusa/usr/share/dbconfig-common/data/confusa/upgrade/mysql/0.6.0~rc0
	cp confusa debian/confusa/etc/logrotate.d/


install_package_data:
	dh_installchangelogs
	dh_compress
	dh_installdebconf
	dh_installdeb
	dh_installdocs
	dh_fixperms
	dh_gencontrol
	dh_md5sums
	dh_builddeb
	dh_lintian


install: install_app_data install_package_data
binary-indep: build install
binary-arch: binary-indep
binary: binary-indep
.PHONY: clean install

5.Copy and move extra files needed to create the package

Rename INSTALL to CONFUSA_CONFIGURATION
```
mv INSTALL CONFUSA_CONFIGURATION
```

Concatenate init/table_create.sql and init/table_create.sql into a single file

cat init/table_create.sql > mysql_create.sql
cat init/views_create.sql >> mysql_create.sql

Make the logrotate script needed. It should be called 'confusa' and have the following content:
```
/var/log/confusa.log {
        rotate 8
        weekly
        compress
        missingok
}
```

6. Build the package using debuild (found in devscripts)

debuild

If you don't have a public/private key pair in GnuPG, you will need to create one for signing the .dsc file. Just invoke

gpg --gen-key

7. Check if the package conforms to Debian policy by calling

lintian confusa_0.6.1_all.deb

8. Confusa has a database, so we use dbconfig-common for setting it up. The directory for the population of the fields in /usr/share/dbconfig-common was already specified in dirs and the the respective SQL script already copied there in rules. What remains to be done is to specify the installation-time scripts that call the dbconfig-functionality. dbconfig-common is based upon debconf, so first we need a config-script loading the dbconfig-common debhelper code. The content of debian/config is the following:

#!/bin/sh
#DEBHELPER#
# config maintainer script for confusa
set -e
. /usr/share/debconf/confmodule

dbc_dbtypes="mysql"
if [ -f /usr/share/dbconfig-common/dpkg/config.mysql ]; then
    . /usr/share/dbconfig-common/dpkg/config.mysql
    dbc_go confusa $@
fi

Then, we need to call dbconfig's own postinstall hook in the postinstall script of our package. Again, we need to source confmodule, so debconf is availabe, in the beginning and then call dbconfig's postinstall-hook. The hack with ucf prevents ucf from trying to start another debconf instance and printing an ugly error message and the dbc_generate_include variable definition instructs dbconfig to write the configuration settings to a PHP config file which we can easily include in Confusa. So, the file debian/postinst has the content:

#!/bin/sh
#DEBHELPER#
set -e
. /usr/share/debconf/confmodule

#ugly hack
alias ucf="ucf --debconf-ok"
dbc_generate_include=php:/etc/confusa/confusa_config.inc.php
. /usr/share/dbconfig-common/dpkg/postinst.mysql
dbc_go confusa $@

If users purge the Confusa package, they'll probably also want to loose the PHP config file that was written by dbconfig-common, so we add that to the script debian/postrm:

#!/bin/sh
#DEBHELPER#
set -e

. /usr/share/debconf/confmodule

if [ "$1" = "purge" ]; then
    rm -f /etc/confusa/confusa_config.inc.php

    if which ucf >/dev/null 2>&1; then
        ucf --purge /etc/confusa/confusa_config.inc.php
    fi
fi

Adding the packages to the apt-repository

The repository is graciously hosted by the University of Tilburg (Universiteit van Tilburg, and the repository can be found here.

Once the packages are created, send an email to lis-unix[-at-]uvt.nl and kindly ask our helping heros to add the packages.

Creating a Confusa debian package

Adding the packages to the apt-repository