Building Debian Packages - The Easy Way

The process for building custom Debian packages described on this page is obsolete, and will not work out of the box. This process has been replaced by koha-dpkg-docker. See the documentation in that project for details. 
Please also see: Building Debian Packages 
It provides steps for you to create your own customized Koha packages.
==Getting set up==
The current packages are being built on a deb10 (buster) system, using a deb10 pbuilder environment (aka chroot) 
It's currently recommended to use a deb10 pbuilder chroot
=== Install pbuilder packages, and create a pbuilder ===
Install pbuilder
sudo apt-get -y install devscripts pbuilder dh-make fakeroot debian-archive-keyring
Enable network access for pbuilder
 sudo echo "USENETWORK=yes" >> /etc/pbuilderrc
Create a pbuilder on Debian 
sudo pbuilder create --distribution buster
Or, if you are running Ubuntu and want a Debian stretch pbuilder, you can add a --mirror option, like this...
sudo pbuilder create --distribution buster --mirror http://ftp.us.debian.org/debian/
==Enter pbuilder==
Pbuilder will need to get packages from the Koha Debian repository. To access it, you have to add the repository in the pbuilder environment. 
Log into pbuilder
sudo pbuilder --login --save-after-login
Install wget and gnupg2
apt-get update
apt-get -y install \
 ca-certificates \
 apt-transport-https \
 wget \
 gnupg2
So the GPG key can be added:
wget -O- http://debian.koha-community.org/koha/gpg.asc | apt-key add -
Add Koha package repo to pbuilder
echo "deb http://debian.koha-community.org/koha stable main" > /etc/apt/sources.list.d/koha.list
Add latest stable npm/gulp/nodejs packages to pbuilder
echo "deb https://dl.yarnpkg.com/debian/ stable main" > /etc/apt/sources.list.d/yarn.list
 wget -O- -q https://dl.yarnpkg.com/debian/pubkey.gpg \
 | gpg --dearmor \
 | tee /usr/share/keyrings/yarnkey.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/yarnkey.gpg] https://dl.yarnpkg.com/debian stable main" \
 | tee /etc/apt/sources.list.d/yarn.list
wget -O- -q https://deb.nodesource.com/setup_18.x | bash -
apt-get update
apt-get -y install nodejs yarn
mkdir -p /nonexistent/.yarn
mkdir -p /nonexistent/.cache/yarn
chmod -R 777 /nonexistent
npm install gulp-cli -g
Check npm/gulp/nodejs package versions
yarn --version
 1.22.19
node -v
 v18.17.1 # needs to be at least version 18
which gulp
 /usr/bin/gulp
gulp -v
 CLI version: 2.3.0
 Local version: Unknown
==Exit pbuilder==
exit
==Clone Koha git repository==
Clone the Koha Git repository, (or use an existing koha repo)
sudo apt-get -y install git
git clone git://git.koha-community.org/koha.git kohaclone
cd kohaclone
Checking out a branch to base your packages on is probably a good idea. Here's how to create a branch that tracks 21.11.x, the stable release branch of version 21.11: 
git checkout origin/21.11.x -b 21.11.x
Create a directory for storing the packages you make, so you don't have to look for them in some obscure place afterwards. Create a directory called "debian" in your home directory, for example:
mkdir ~/debian
==Make any changes to Koha==
One reason for building your own packages is that you want to alter Koha in some way compared to the official packages, and now is the time to do it. Just remember that in order for build-git-snapshot to work, you can not have any uncomitted changes in your repository. 
===Local changes===
Make the changes you need and commit them: 
vim somefile
git commit -a -m "I changed somefile"
===Patches===
You might want to apply patches that others have created: 
wget -O <name_of_patch_file> http://bugs.koha-community.org/bugzilla3/attachment.cgi?id=<attachment_number>
git am -3iu <name_of_patch_file>
Alternatively, see https://wiki.koha-community.org/wiki/Git_bz_configuration for using 'git bz'
===Translations===
The po files are now no longer part of the main Koha repository and will are built as a separate dependency.
==Build the packages==
Now run build-git-snapshot, making sure you are in the root directory of your cloned repository first:
sudo ./debian/build-git-snapshot -r ~/debian -v 21.11.01git -d
* -r tells the script where to put the packages you build.
* -v designates the version you are building, using 21.11.01git for example. Convention is upstream_version[-custom_revision_number][comment] - See debdocs for more information on version numbering. Do not put a - in the name, as Debian interprets that as a revision number you are not allowed to set anymore. You will get dpkg-source: error: can't build with source format '21.11 (native)': native package version may not have a revision. You may use a + though.
* -d is for debug, which gives you a little more output, so you can see what is happening.
Be patient, building packages does take some time! 
When build-git-snapshot is finished, you should have several files in ~/debian: 
* koha_21.11.01-1git+20110522163502.cdf32da0_all.deb
* koha_21.11.01-1git+20110522163502.cdf32da0.dsc
* koha_21.11.01-1git+20110522163502.cdf32da0_i386.changes
* koha_21.11.01-1git+20110522163502.cdf32da0.tar.gz
* koha-common_21.11.01-1git+20110522163502.cdf32da0_all.deb
The ones you can actually use are the ones that end in ".deb". See Koha 3.x on Debian Squeeze for the difference between koha and koha-common.
Note: When building packages from main, sometime the tests may fail. If you still wish to proceed with a package build, you'll need to prepend the above command with DEB_BUILD_OPTIONS=nocheck, for instance:
sudo DEB_BUILD_OPTIONS=nocheck ./debian/build-git-snapshot -r ~/debian -v 21.11.01git -d
Note: In Koha 23.05 and higher, you can include the CUSTOM_PACKAGE=1 parameter to prevent the build from failing if your package includes custom atomic updates.
 sudo CUSTOM_PACKAGE=1 ./debian/build-git-snapshot -r ~/debian -v 21.11.01git -d
==Deploy the packages==
===Creating your own APT repository===
This instructions explain how to manually install the new packages. It is recommended for several reasons that you setup your own APT repository for deploying as explained in Create your own APT repository.
===Manual install method===
Move the .deb files to wherever you need them, using tools such as an FTP client or the scp command. 
When the files are where you want them, you can install them like this: 
sudo dpkg -i koha-common_21.11.01-1git+20110522163502.cdf32da0_all.deb
sudo apt-get -f install
This should install koha-common along with all it's prerequisites, along with all the tools it provides, as well as the customizations you added, whatever they were. Congratulations!
(Running sudo dpkg -i will most likely result in a list of errors like "koha-common needs tinymce2 but tinymce2 is not installed". Don't worry, this is taken care of by the next step, sudo apt-get -f install.)
====Unmet dependencies====
After doing the steps above you might still be missing some dependencies. The best way to get everything correctly installed is to run
sudo apt-get -f install
==Updating your packages==
After a while you will probably want to create new versions of your packages - because you want to get the latest and greatest bugfixes or you want updated translations or you thought about some more changes you wanted to do to the code. 
To get the latest bugfixes, make sure you are in your cloned repository and then fetch and rebase: 
git fetch
git rebase origin/21.11.x
As always, remember to commit all your changes! when you are happy with your work build the packages: 
sudo ./debian/build-git-snapshot -r ~/debian -v 21.11.02git -d
Notice the (manual) change from 21.11.01git to 21.11.02git - this is so you can tell your packages apart easily. 
Now move the .deb files to where you want to use them, and deploy with: 
sudo dpkg -i koha-common_21.11.02git+20110617001823.a5aa2215_all.deb
and everything should be taken care of for you, including any necessary changes to the database.
Category:Debian_Packages