Skip to end of metadata
Go to start of metadata

Debian uses the package system apt, with packages named *.deb. Usually, debian packages live in a repository that is accessed over the Internet. For deployment of project specific packages, we can save the work for that and rely on copying the deb package to the server.

Why packaging ?

Deployments are done using Debian packages, as they provide a good way to define a line of responsibilities.

Do not deploy thru git or svn

The SCM approach to deploy websites has several flaws :

  • When doing a new deployment, you have to make sure that all the dependencies are installed on the target machine (Apache, PHP, PHP modules, Apache modules, etc)
  • The upgrade is done in a 2-way procedure : first you update the code, then you run update scripts. It means that if your update scripts go wrong, you're left with a semi-working site and you're never sure when your site will be fully working again. Also it means that you're at risk of forgetting to run a script or do something required by the deployment.
  • The uninstall is painful. If you fail your install and you want to clean the system, you have to remove everything by hand.
  • You must have an SCM tool (which is a dev tool) available on your target machine.
  • You must have an external access to your repository so that you can pull the source from the target machine.
  • You must have a flexible configuration structure: of course you don't want to have a configuration file that holds the prod passwords versioned. But you want to be able to script configuration changes, for example if the IP address of your database server changes, so you don't have to search for the configuration file that holds the setting you want to change

Do package and deploy

Debian packages solve most of the above issues:

  • Debian packages allow you to define dependencies for your package. For example if you know that you're using PHP curl functions in your project, you'll add php-curl as a dependency for your package and it will automatically get installed when you install your package
  • The upgrade is done with a single command, so you don't have the risk of missing something : that makes you sure that every deployment is exactly the same and if it works on staging, it will work on prod. Also if something gets wrong during the upgrade, the package is left in a broken state, which clearly indicates you that your install is broken. Once your package gets in a stable state, that usually means that your install/upgrade is successful and your website is working.
  • You can uninstall the package using a single command, and it will take care of removing all the files and purging the database if you want to.
  • The packaging stuff is done on a dev machine, so you don't need any dev tool on your target server. Also you can securely transfer your packages using scp.
  • Most of the configuration is done through the packaging system, so all the configuration is centralised. You specify site-specific configuration (like database credentials) only during the first deployment. You can always change them at any time using dpkg-reconfigure without having to know where the configuration files are located.

How to package

The dev server automatically checks out the git trunk, there you are done as soon as the code is checked into git.

  • apt-get update
  • apt-get upgrade or apt-get install xxx (the debian package enables modules and runs updatedb to make database changes)

Debian Packaging Guide explains how to build a debian package from scratch

The project uses Debian packages for everything that gets deployed onto a server. Replace project with your project name:

  • drupal-site-project-common: Drupal source code, apache config and postinst routines (upgrading drupal, etc)
  • drupal-site-project-pgsql: Postgres dependencies
  • solr-project: The project solr configuration and schema
  • shibboleth-project: The project shibboleth configuration

Packaging files description

First of all there is the file, called by the Makefile. It reads the file, populates the template files, creates the install file, and finally builds the package. Every other file is in the debian_templates/ dir. For files that don't appear in the following table, refer to the Debian Packaging Guide.

The basic workflow of Drupal packaging is as follows : make -> Makefile -> -> templating -> config -> preinst -> dirs -> install -> postinst.




Apache configuration related files


helper functions for the config


operations to be executed by cron


database connection test


Drupal settings.php template file


empty file populated by, contains the list of files to install (ie. the whole website structure including php, css, js etc)


install a new Drupal install by using curl (Drupal 6 packaging only)


install a new Drupal install by using drush (Drupal 7 packaging only)


logrotate script for apache logs

Upgrading a package

When installing a new version of a package, a database dump is made and placed in the /var/tmp directory.

  • None