Deploying Proprietary Java Software on Ubuntu Linux
Contents
Background
Ubuntu is the most popular Linux distro in world at the time of writing. We use Ubuntu as our primary development environment at OffByZero, but also spend a fair bit of time in MacOS X and Microsoft Windows, too.
The need to get at our passwords and other company secrets from a wide range of operating systems led us to develop OBZVault, a cross-platform encrypted text editor. Once we decided to use Java it was a straightforward process to get it running on all the operating systems we use, but it proved quite challenging to build an installer for Ubuntu Linux.
.deb Packages
Software is distributed for Ubuntu in the form of .deb packages (in fact the Ubuntu distribution itself is basically made up of many, many .deb packages). They are called .deb packages because they follow the same format as packages for the Debian distro, upon which Ubuntu is based.
Confusingly, although Ubuntu packages are .deb packages, and although Ubuntu is built upon Debian, .deb packages designed for Debian are frequently incompatible with Ubuntu and vice versa. To be clear, in this article all .deb packages mentioned are intended to run on Ubuntu.
This article will explain how to structure and build a .deb package to install a proprietary Java application on Ubuntu, using the .deb package we built for OBZVault as an example. If you have any questions or comments, please contact us.
Structure of the .deb Package
A .deb package is built with command-line tools from a number of files. The tools themselves can be installed on Ubuntu with the following command:
sudo apt-get install debhelper lintian
The file tree of the .deb package for OBZVault is as follows (courtesy the tree utility):
obzvault-3.3.1424/
|-- build-stamp
|-- debian
| |-- changelog
| |-- compat
| |-- control
| |-- dirs
| |-- input
| | |-- AbsoluteLayout.jar
| | |-- app.png
| | |-- appframework-1.0.3.jar
| | |-- application-offbyzero.obzvault.png
| | |-- copyright
| | |-- doc.png
| | |-- obzvault.jar
| | |-- swing-layout-1.0.3.jar
| | |-- swing-worker-1.1.jar
| | |-- ui.jar
| | `-- vault
| |-- install
| |-- obzvault.desktop
| |-- obzvault.sharedmimeinfo
| |-- postinst
| |-- postrm
| `-- vault.1
`-- rulesWe'll be going through each file explaining what it does, what it contains, and whether there's any magic involved.
obzvault-3.3.1424
This is the name of the directory that contains all the files for the package. The name itself is signficant to the tools that build the package from its contents; the format is package_name-X.Y.ZZZZ where X, Y and ZZZZ comprise the version of the package. The version number is specified nowhere else; it is solely derived from the name of this directory.
changelog
This is a simple text file that contains the changes that have been made to an application since its creation.
compat
5
This file specifies what version of the debhelper tools is required to build this package. We explicitly set ours to '5' because we are not using any of the newer debhelper functionality.
control
Source: obzvault
Section: editors
Priority: optional
Maintainer: OFFBYZERO PTY. LTD. <support@offbyzero.com>
Build-Depends: debhelper (>= 5), sun-java5-jre, sun-java5-jdk
Standards-Version: 3.8.0
Homepage: http://offbyzero.com/obzvault
Package: obzvault
Architecture: all
Depends: sun-java5-jre | sun-java6-jre
Replaces: obzvaulttrial
Description: OffByZero Vault Secure Text Editor
OffByZero Vault is a secure text editor that uses the
TripleDES symmetric encryption algorithm. OBZVault is
available on MS Windows, Linux, and Mac OS X.
The control file contains a description of the package, which is used by the Debian package management system to control installation, and also by package management tools to display information about the package itself.
Most of this file is self-explanatory. Given that most software for Debian is free and open-source, there are two separate sections. The first describes the source of the package and the dependencies required to build it. The second section describes the resultant package itself, and its installation dependencies.
Of particular interest is the Replaces entry; we have another similar package for a trial version of OBZVault, which is named obzvaulttrial. The Replaces entry ensures that when you install the full version, it silently replaces the trial version.
Note the Depends line specifies two JRE packages (5 and 6), separated by a pipe. This creates a package that depends on either of those two packages.
dirs
/usr/share/obzvault
/usr/share/obzvault/lib
/usr/share/doc/obzvault
This file lists the directories that will be created by the installer, and deleted during uninstallation. Note that at uninstallation only files that are included in the package are removed. So if OBZVault were to create a file in /usr/share/obzvault during operation, that directory would not be removed during uninstallation because of the presence of that file.
input
This directory contains all the files to be installed as part of the package. Most of them solely relate to our application (for example, icons, .jar files, shell scripts etc.).
The only file of particular interest is the shell script vault; this contains the code necessary to execute our application:
#!/bin/sh
java -jar /usr/share/obzvault/obzvault.jar "$@"
install
debian/input/app.png /usr/share/obzvault
debian/input/doc.png /usr/share/obzvault
debian/input/application-offbyzero.obzvault.png /usr/share/icons/hicolor/128x128/mimetypes
debian/input/obzvault.jar /usr/share/obzvault
debian/input/AbsoluteLayout.jar /usr/share/obzvault/lib
debian/input/appframework-1.0.3.jar /usr/share/obzvault/lib
debian/input/swing-layout-1.0.3.jar /usr/share/obzvault/lib
debian/input/swing-worker-1.1.jar /usr/share/obzvault/lib
debian/input/ui.jar /usr/share/obzvault/lib
debian/input/copyright /usr/share/doc/obzvault
debian/input/vault /usr/bin
debian/obzvault.desktop /usr/share/applications
Here we specify the location of each file we include in the package. Note that if a directory specified in install doesn't already exist, then you need to create it by listing it in the dirs file.
obzvault.desktop
[Desktop Entry]
Name=OBZVault
Comment=Edit and encrypt text files
Exec=vault %f
Terminal=false
Type=Application
StartupNotify=true
Icon=/usr/share/obzvault/app.png
Categories=GNOME;GTK;Utility;TextEditor
MimeType=application/offbyzero.obzvault;
This is one of the two files responsible for the way OBZVault integrates so nicely with the Ubuntu desktop and start menu. It's pretty self-explanatory, with the only trick being the specification of MimeType. Ubuntu does all file associations by MIME type, and if we want file associations then we need to tell Ubuntu what MIME type the application opens.
obzvault.sharedmimeinfo
<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<mime-type type="application/offbyzero.obzvault">
<comment>OBZVault Encrypted Text File</comment>
<glob pattern="*.vault"/>
</mime-type>
</mime-info>
This is the other file responsible for desktop integration. Whereas obzvault.desktop describes the application and specifies which MIME type it opens, this file describes the MIME type itself and the wildcard (in the case of OBZVault, *.vault files) associated with the MIME type.
postinst & postrm
#!/bin/bash
postinst is a shell script that's run following a successful installation, and postrm is run after a successful uninstallation. OBZVault doesn't do anything particularly fancy as part of installation, so these files are both empty except for the shebang.
vault.1
.TH VAULT 1 "May 3, 2009"
.SH NAME
vault \- starts the OffByZero Vault Secure Text Editor
.SH SYNOPSIS
.B vault
.RI "[file]"
.SH DESCRIPTION
This manual page documents briefly the
.B vault
command.
.PP
\fBOBZVault\fP is a text editor that encrypts files using the TripleDES
encryption algorithm.
.SH AUTHOR
OBZVault is sold by OFFBYZERO PTY. LTD. See http://offbyzero.com/obzvault
.PP
This manual page was written by OFFBYZERO PTY. LTD. .
This is the source file for the OBZVault manpage. It should have the same root name as the application executable, which in this case is vault (which you'll also see in the input directory and the install file).
build-stamp
This unassuming file is touched every time the package is built.
rules
#!/usr/bin/make -f
build: clean build-stamp binary
build-stamp:
touch build-stamp
clean:
dh_testdir
dh_testroot
rm -f build-stamp
dh_clean
binary:
dh_testdir
dh_testroot
dh_clean -k
dh_install
dh_installchangelogs
dh_installman debian/vault.1
dh_installmime
dh_desktop
dh_icons
dh_compress
dh_fixperms
dh_installdeb
dh_gencontrol
dh_md5sums
dh_builddeb
As the shebang line makes clear, rules is a Makefile; in particular it's the file that's executed to build the .deb package. The vast majority of lines simply invoke tools that were installed as part of the debhelper tools; these tools are prefixed with dh_. Documentation on the debhelper tools can be obtained by running:
info debhelper
... in a console. You can see from the documentation what each tool does (although the names are fairly self-explanatory) and get an idea of the input they require. The documentation is unfortunately quite sparse (in particular, in the area of file associations and MIME types) but will make some sense now that you understand the structure of a .deb package, and the basic conventions.
Building
Once you've built up a file tree similar to that described above, building your .deb package is simplicity itself. Just change into the directory containing your package, and execute rules (the sudo is important; the debhelper tools do things that require root privileges):
cd obzvault-3.3.1424
sudo ./rules
This should result in the file obzvault_3.3.1424_all.deb being created at the same level as the obzvault-3.3.1424 directory.
Testing and Installing
Once you have your .deb package built, you can install it from the command line:
sudo dpkg -i obzvault_3.3.1424.deb
... or by opening it in your favourite graphical package tool (I suggest gdebi as it's what most Ubuntu users will see, and it shows a file list, details, dependencies etc.)
You should also validate your .deb package. This step is very important; we identified a number of issues with the OBZVault installer that we were able to rectify before we shipped.
lintian obzvault_3.3.1424.deb