Deploying Proprietary Java Software on Ubuntu Linux



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):

    |-- 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
    `-- rules

We'll be going through each file explaining what it does, what it contains, and whether there's any magic involved.


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.


This is a simple text file that contains the changes that have been made to an application since its creation.



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.


    Source: obzvault
    Section: editors
    Priority: optional
    Maintainer: OFFBYZERO PTY. LTD. <>
    Build-Depends: debhelper (>= 5), sun-java5-jre, sun-java5-jdk
    Standards-Version: 3.8.0

    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.



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.


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:


    java -jar /usr/share/obzvault/obzvault.jar "$@"


    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.


    [Desktop Entry]
    Comment=Edit and encrypt text files
    Exec=vault %f

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.


    <?xml version="1.0" encoding="UTF-8"?>
    <mime-info xmlns="">
      <mime-type type="application/offbyzero.obzvault">
        <comment>OBZVault Encrypted Text File</comment>
        <glob pattern="*.vault"/>

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


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.


    .TH VAULT 1 "May  3, 2009"
    .SH NAME
    vault \- starts the OffByZero Vault Secure Text Editor
    .B vault
    .RI "[file]"
    This manual page documents briefly the
    .B vault
    \fBOBZVault\fP is a text editor that encrypts files using the TripleDES
    encryption algorithm.
    OBZVault is sold by OFFBYZERO PTY. LTD.  See
    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).


This unassuming file is touched every time the package is built.


    #!/usr/bin/make -f

    build: clean build-stamp binary

    touch build-stamp

    rm -f build-stamp

    dh_clean -k
    dh_installman debian/vault.1

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.


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