BOINC in a box: Walking you through the preparation of a BOINC server project package with Debian

This document summarises how to prepare a fully functional BOINC project out of the box as a Debian package.

You may be interested in this page since you have already manually set up a BOINC project yourself and consider your problem to be of general interest, but you do not feel like maintaining such project for others.

Preparation

You become a 'packager' for Debian/Ubuntu now, i.e. a 'developer' in the distros' lingo. To be on the safe side, we install a bit more than you truly need, please get:

by running

sudo apt-get install build-essential dh-make

For this walk-through we are using the BASH shell. If you already have your very own meaning on what shell is the best, you will have no problem to just ignore those bits that may not work for your shell. Otherwise, just start the bash from your shell with 'bash'. To help you with abstracting from the example towards your own needs, we are using some variables:

With BASH, you get the content of those variable by prepending the variable name with a dollar sign. For the assignment, have the equal sign right next to the variable name, i.e. do not leave a blank.

Off you go

Configuring the variables:

export projectname=autodock
export projectversion=0.01
export DEBEMAIL=moeller@debian.org

Create a project folder and enter it

mkdir boinc-server-$projectname
cd !$

We will create a debian folder that is half-reasonably prefilled

dh_make --native -i -c gpl -p boinc-server-autodock_0.01

Now you have something that is not too bad already. It just hosts too much we do not need. So we clean it up:

# man pages
rm debian/man*
# text editor's configurations
rm debian/emacs*
# fancy documentation
rm debian/*doc-base*
# menu
rm debian/menu.*
# version updates
rm debian/watch.*
# we do not change source code but provide our own
rm debian/README.source debian/README

The remainder we shall leave in for now.

Package description

Well, this is the part that the user will see when searching for a package. It is all stored in the file 'debian/control'. Some bits we can adjust immediately:

sed -i 's/^Section: .*/Section: science/' debian/control
sed -i 's%^Homepage:.*%Homepage: http://wiki.debian.org/BOINC%' debian/control
# remove some comment lines that we do not want to bother you with for this tutorial
sed -i '/^#/d' debian/control
sed -i "s/^Description:.*/Description: BOINC server package for $projectname/" debian/control
sed -i "s/^ .*/ This package installs a web site for the management of a BOINC (Berkeley\n Open Infrastructure for Network Computing) project distributing work\n with $projectname./" debian/control

There would be a series of ways to craft the package. To mind come especially

  1. We build everything we need _now_ while we create the package
  2. We build nothing but just put everything in place for the post-inst script

and since there is nothing to build, really, we opt for the post-inst. This may have the advantage that when the boinc-server-maker package updates, the boinc-server-application package would not necessarily need to be also updated, but it would just run the same commands in the post-inst. The disadvantage is that when the boinc-server-maker changes, the post-inst might possibly fail, while with a pre-made server, you'd just continue with the older setup and do not have the boinc-server-maker as a pre-inst dependency.

sed -i 's/^Depends:.*/Depends: ${misc:Depends}, boinc-server-maker/' debian/control

From the technical side, the 'debian/control' file is not sufficiently edited. We already did too much :) Anyway, give it all some better project-specific description by opening the file with your favorite editor and doing the obvious. Do not leave empty lines. The first character of every line needs to be a blank. For a new paragraph have a line " ." (blank, dot).

Another file to inspec sed -i 's/^.*delete this file.$/This is an experimental package to explore the options for Debian to provide a "BOINC Server in a Box"/' debian/README.Debian

Package changelog

The version of your package and what is special about it, you describe in the file 'debian/changelog'. You should not need to change anything. For a later version of this package consider using the tool 'dch' from the 'devscripts' package.

We have two differnet parts of this package. Firstly, there is the scientific parts with scripts to create workunits etc. This is yours. Give it the license you consider to be fitting your purpose.

The files in the debian folder we have started. The copyright here is with us and the changes you do to it are yours. Since this effort was started under the GPL, that license is fairly likely to stick. Just add your name in a separate line.

When following these instructions just leave everything as it is.

Package building

Just to help the learning a bit, create a Debian package from what we have already

dpkg-buildpackage -rfakeroot -uc -us

and after a while you will see a package to inspect. We start with an investigation of packaging problems

$ lintian ../boinc-server-${projectname}_*.changes
W: boinc-server-autodock source: dh-make-template-in-source debian/boinc-server-autodock.cron.d.ex
W: boinc-server-autodock source: dh-make-template-in-source debian/boinc-server-autodock.default.ex
W: boinc-server-autodock source: dh-make-template-in-source debian/init.d.ex
W: boinc-server-autodock source: dh-make-template-in-source debian/postinst.ex
W: boinc-server-autodock source: dh-make-template-in-source debian/postrm.ex
W: boinc-server-autodock source: dh-make-template-in-source debian/preinst.ex
W: boinc-server-autodock source: dh-make-template-in-source debian/prerm.ex

which is all right.

BOINC project setup

There is a series of commands and subsequent editing steps to get the website of a project locally installed. Those scripts are all in the 'boinc-server-maker' project. Respective instructions are given on the BOINC ?ServerGuide [1]. Conceptionally it shall be ensured that there is no difference, or not much of a difference, between the automated setup procedure and a manual one. And the manual setup shall always have an option to overrun something performed by the automated procedure.

Let's place a file with default parameters in the Debian directory:

root=debian/boinc-server-${projectname}/usr/share/boinc-server-$projectname
mkdir -p $root
cat <<EOCONFIG > $root/.config
#
# MySQL configuration
#

# how the boinc user for the database should log in
pw=MYSQLPASSWORDFORBOINCUSER
# name of the MySQL database
dbprojectname=$projectname

#
# project configuration
#

# address of host (via DNS or IP number) at which project server shall be reached
hosturl=http://127.0.0.1
# name of folder in which data shall be stored, also becomes part of project URL
fileprojectname=$dbprojectname
# more human-compatible way to read the project name
niceprojectname="$projectname@Home"
# location at which sources shall be kept
installroot=/var/lib/boinc-server-$projectname
EOCONFIG
chmod 400 $root/.config

The password is something that we still need to work on. The maintainer needs to be asked for it.

References

[1] http://wiki.debian.org/BOINC/ServerGuide