confusa

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.2confusa-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