Builder

An introduction to Debian packaging (in general) can be found here.

Requirements

We recommend you use a clean Debian as your build machine. Currently we recommend you to use Debian 13.

$ sudo apt install \
 debian-archive-keyring \
 ubuntu-archive-keyring \
 devscripts \
 rsync \
 aptitude \
 build-essential \
 debootstrap \
 apt-cacher-ng \
 sbuild \
 pkg-php-tools \
 golang-go \
 dh-golang \
 dh-sysuser \
 dh-python \
 python3-setuptools \
 python3-wheel \
 python3-sphinx \
 apache2-dev \
 reprepro \
 git-buildpackage \
 dh-make

Make sure your user is a member of the sbuild group:

$ sudo usermod -a -G sbuild $(whoami)
$ newgrp sbuild

Make sure you have a PGP key, .e.g.:

$ gpg \
 --batch \
 --passphrase '' \
 --quick-generate-key "Repository Signing Key <me+repo@example.org>" \
 default \
 sign \
 10y

Clone Repository

$ git clone https://codeberg.org/eduVPN/nbuilder.deb

All commands below are executed inside the nbuilder.deb folder.

Create Chroots

The script create_update_chroots.sh can be used to create the chroots and update them.

If you want to update the suites, you can copy create_update_chroots.config.default to create_update_chroots.config and modify it as needed.

Then run the script:

$ ./create_update_chroots.sh

sbuild

The new sbuild backend will be unshare, see #6. The sbuild command will inform us about that quite loudly, we can silence this. Until such time we areable to adopt unshare, you need to update your sbuild configuration:

$ mkdir -p ${HOME}/.config/sbuild
$ cat << 'EOF' > ${HOME}/.config/sbuild/config.pl
$chroot_mode = "schroot";
$schroot = "schroot";
$clean_source=0;
$build_dep_resolver = "aptitude";
EOF

The clean_source option is because of this issue which prevents build dependencies from being installed, or something.

We also switch to aptitude as a dependency resolver, which works better than the default apt.

Configuration

To start building packages, know which one you want to run. We'll use eduVPN 3.x as the example below.

Copy eduvpn_v3.config.default to eduvpn_v3.config. Modify the file by setting the KEY_ID to the Key ID of your PGP key you generated above, e.g.:

KEY_ID=me+repo@example.org

You can also modify DISTRO_SUITE_LIST, REPO_URL_BRANCH_LIST if necessary. You will need to update UPLOAD_SERVER_PATH_LIST to specify the account, server and path where you want to upload the package repository. It is recommended to configure SSH keys for authenticating to the SSH server.

Export your public key to the keys/ folder so it can be found by the builder and uploader:

$ gpg --export -a me+repo@example.org > keys/me+repo@example.org.asc

Updated Go Compiler

If you are building Go software, you may benefit from using the latest Go compiler. Look here on how to enable that.

Building

The builder performs 4 steps:

1. Download the current repository from the remote server (UPLOAD_SERVER_PATH_LIST), if there is >1 listed, e.g. mirrors, only the first one is used;
2. Build the packages that are not yet in the repository;
3. Sign the repository;
4. Upload the repository.

To run the builder:

$ ./eduvpn_v3.sh

Updating Packages

NOTE: only do this if you want to package newer versions of the software, NOT run the builder.

Environment

Make sure the variables DEBFULLNAME and DEBEMAIL are set. This makes sure dch below uses this information to update the debian/changelog file. Add this to the bottom of ${HOME}/.profile:

export DEBFULLNAME="François Kooman"
export DEBEMAIL=fkooman@deic.dk

After this make sure you logout and in again.

Updating

In order to update a package, you can use the following commands, if necessary first fork the repository to a place where you can "push" to:

$ git clone git@codeberg.org:eduVPN/vpn-user-portal.deb

We need to make the upstream branch available locally, not sure how to do that properly, but this works:

$ git checkout upstream
$ git checkout v3

Download the latest upstream tar release and verify the signature:

$ uscan

Import the new release in the Git repository:

$ gbp import-orig ../vpn-user-portal_3.0.5.orig.tar.xz

Update the debian/changelog file. Your editor will be opened.

$ dch -v 3.0.5-1

The update message could be "update to 3.0.5". If you make any other changes to the package, note them here as well. Finalize the changes:

$ dch -r --distribution unstable

Review the changes:

$ git diff

If all looks good, commit and push the changes:

$ git commit -a -m 'update to 3.0.5'

Now push all branches/tags to the server:

$ git push origin --all
$ git push origin --tags

New Package

It is not so easy to create a new package. Especially when starting from scratch. Even using an existing package to get it under version control is not trivial. I'm making notes now where I am creating a new package. This is not really a complete instruction on how to create a package from scratch. It involves some random stuff that is very hard to document, but this is sort of the basics.

First install dh-make package. You can then use it to create a new package.

$ curl -O https://codeberg.org/fkooman/php-radius/releases/download/2.0.0/php-radius-2.0.0.tar.xz
$ tar -xJf php-radius-2.0.0.tar.xz
$ cd php-radius-2.0.0
$ dh_make -i --createorig

This will create the debian/ folder where the packaging instructions are at. You can modify them, or better, copy the contents from another similar package over and modify it.

Once done, try to create a package, it may complain and ask you to install some additional dependencies though:

$ debuild

Once this succeeds, we can use gbp to get the package under source control. We need to .dsc file for this.

$ cd ${HOME}/Projects/eduVPN-v3/deb
$ gbp import-dsc --debian-branch=main /path/to/php-radius_0.1.0-1.dsc
$ mv php-radius php-radius.deb
$ cd php-radius.deb

Test if all is good, by running uscan:

$ uscan --download-current-version
uscan: Newest version of php-radius on remote site is 0.1.0, specified download version is 0.1.0
gpgv: Signature made Mo 02 Okt 2023 12:12:44 CEST
gpgv: using RSA key 6237BAF1418A907DAA98EAA79C5EDD645A571EB2
gpgv: Good signature from "François Kooman <fkooman@tuxed.net>"
Successfully symlinked ../0.1.0.tar.gz to ../php-radius_0.1.0.orig.tar.xz.

Now we have everything we should have to feed this package to nbuilder.deb, but first upload it to a remote git repository:

$ git remote add origin git@codeberg.org:fkooman/php-radius.deb
$ git push --all
$ git push --tags

uscan

The format of debian/watch file as used by uscan is very very crazy. With lots of trial and error we made it work. I do not pretend to 100% understand, nor whether this is the best/simplest way to go.

Codeberg

For releases hosted on codeberg.org, you can use the following in debian/watch:

version=4
opts="pgpmode=auto" \
	https://codeberg.org/eduVPN/@PACKAGE@/releases \
	https://codeberg.org/eduVPN/@PACKAGE@/releases/download/(?:.*)/@PACKAGE@@ANY_VERSION@@ARCHIVE_EXT@

SourceHut

For releases hosted on sr.ht, you can use the following in debian/watch:

version=4
opts="pgpmode=auto,downloadurlmangle=s%/~fkooman/@PACKAGE@/archive/@ANY_VERSION@@ARCHIVE_EXT@%/~fkooman/@PACKAGE@/refs/download/1ドル/@PACKAGE@-1ドル.tar.xz%" \
	https://git.sr.ht/~fkooman/@PACKAGE@/refs \
	/~fkooman/@PACKAGE@/archive/@ANY_VERSION@@ARCHIVE_EXT@