grunt-debian-package
Create debian package from grunt build
Grunt plugin to create a Debian package, allowing JavaScript applications to be easily integration into a Debian or Ubuntu based continuous delivery pipeline.
Getting Started
This plugin requires Grunt ~0.4
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-debian-package --save-dev
You will also need to install two debian tools used to create and lint the debian package, as follows:
sudo apt-get install devscriptssudo apt-get install debhelper
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
To print out verbose messages during packaging use --verbose, for example:
grunt debian_package --verbose
To debug any issues with the debian_package task configuration:
1. use the node-inspector:
sudo npm install -g node-inspectornode --debug-brk $(which grunt) debian_package --verbose
2. in another shell process:
node-inspector
3. open the url displayed in a browser
The "debian_package" task
Overview
In your project's Gruntfile, add a section named debian_package
to the data object passed into grunt.initConfig()
.
Typically the options section would not need to be provided as these values are read from the package.json file for the project. In this example, however, custom options are used to override the default values. For more details on the default values see below.
grunt;
This will result in a package being created called prefix-package_name-postfix-2.0.0-1.deb. The configuration above will result in the package containing all *.js, *.css and *.html files in the build directory. These files will be installed into /var/wwww/ when the package is installed. In addition the package will contain /var/wwww/package_name.json as a copy of the config/package_name.json file in the project. The config above will also add two soft-links and an empty directory into the package. Both the links and directories sections can use the following placeholders ${name}
, ${version}
and ${build_name}
to refer to the package name, version and build number respectively.
Using the dpkg -c package_name-2.0.0-1.deb
command it is possible to see the package contents:
dpkg -c prefix-package_name-postfix-2.0.0-1.debdrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./usr/share/drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./usr/share/doc/drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./usr/share/doc/prefix-package_name-postfix/-rw-r--r-- jenkins/jenkins 163 2014-04-27 15:08 ./usr/share/doc/prefix-package_name-postfix/changelog.Debian.gz-rw-r--r-- jenkins/jenkins 0 2014-04-27 15:08 ./usr/share/doc/prefix-package_name-postfix/copyrightdrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/app/drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/app/package_name/drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/www/-rwxr-xr-x jenkins/jenkins 12369 2014-04-24 05:57 ./var/www/index.htmldrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/www/js/-rw-r--r-- jenkins/jenkins 1600 2014-04-24 05:57 ./var/www/js/example.min.js-rw-r--r-- jenkins/jenkins 3210 2014-04-24 05:57 ./var/www/js/example.min.mapdrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/www/css/-rw-r--r-- jenkins/jenkins 1529 2014-04-24 05:57 ./var/www/css/example.cssdrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./etc/drwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./etc/init.d/lrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./etc/init.d/tomcat7 -> package_namedrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/log/lrwxr-xr-x jenkins/jenkins 0 2014-04-27 15:08 ./var/log/tomcat7 -> package_name
Using the dpkg -I prefix-package_name-postfix-2.0.0-1.deb
command it is possible to see the package information:
dpkg -I prefix-package_name-postfix-2.0.0-1.deb new debian package, version 2.0. size 7300 bytes: control archive= 605 bytes. 226 bytes, 9 lines control 507 bytes, 7 lines md5sums Package: prefix-package_name-postfix Version: 2.0.0-1 Architecture: i386 Maintainer: James D Bloom <jamesdbloom@email.com> Installed-Size: 35 Section: misc Priority: optional Description: the short description the long description added to the debian package
To install the package use: sudo dpkg -i prefix-package_name-postfix-2.0.0-1.deb
sudo dpkg -i prefix-package_name-postfix-2.0.0-1.deb Selecting previously unselected package prefix-package_name-postfix.Unpacking prefix-package_name-postfix ...Setting up prefix-package_name-postfix ...Processing triggers
Once installed the dpkg -l
command will list the package:
dpkg -l | grep prefix-package_name-postfix prefix-package_name-postfix 2.0.0-1 the short description
And dpkg -L prefix-package_name-postfix
will list the installed files:
dpkg -L prefix-package_name-postfix/./usr/share//usr/share/doc//usr/share/doc/prefix-package_name-postfix//usr/share/doc/prefix-package_name-postfix/changelog.Debian.gz/usr/share/doc/prefix-package_name-postfix/copyright/var//var/app//var/app/package_name//var/www//var/www/index.html/var/www/js//var/www/js/example.min.js/var/www/js/example.min.map/var/www/css//var/www/css/example.css/etc//etc/init.d//etc/init.d/tomcat7 -> package_name/var/log//var/log/tomcat7 -> package_name
Options
options.maintainer.name
Type: String
Default value: process.env.DEBFULLNAME
or package.json author.name
This value specifies the maintainer's name for the debian package. The default value is taken from the standard debian environment variable DEBFULLNAME
.
options.maintainer.email
Type: String
Default value: process.env.DEBEMAIL
or package.json author.email
This value specifies the maintainer's email for the debian package. The default value is taken from the standard debian environment variable DEBEMAIL
.
options.prefix
Type: String
Default value: ''
This value specifies a prefix for the debian package name. This is useful is the package name is taken from the package.json but requires a prefix (i.e. for company name).
options.name
Type: String
Default value: package.json name
This value specifies the name of the debian package. The default value is taken from the package.json name value.
options.postfix
Type: String
Default value: ''
This value specifies a postfix for the debian package name. This is useful is the package name is taken from the package.json but requires a postfix (i.e. for git branch).
options.short_description
Type: String
Default value: package.json description
first line only
This value specifies the short description for the debian package, for example, this is displayed when listing all packages using the dpkg -l
command. The default value is taken from the first line of the package.json description value.
options.long_description
Type: String
Default value: package.json description
all except first line
This value specifies the multiple line long description for the debian package, for example, this is displayed when quering package status using the dpkg -s <package.name>
command. The default value is taken from all text after the end of the first line of the package.json description value.
options.version
Type: String
Default value: package.json version
The first part of the version number. This version number is intended to respresent the logical version of the code in the package. The default value is taken from the package.json version value.
options.build_number
Type: String
Default value: process.env.BUILD_NUMBER || process.env.DRONE_BUILD_NUMBER || process.env.TRAVIS_BUILD_NUMBER
The second part of the version number. This version number is intended to respresent a specific build of the package, for example this package might represetn the Jenkins or drone.io or TravisCI build number. The default value is taken from an environment variable called BUILD_NUMBER
or DRONE_BUILD_NUMBER
or TRAVIS_BUILD_NUMBER
which is compatible with Jenkins, drone.io and TravisCI respectively.
options.disable_debuild_deps_check
Type: Boolean
Default value: false
Some distributions like Arch Linux will fail the dpkg dependency checks causing debuild
to fail. Use with caution.
options.target_architecture
Type: String
(possible values are amd64
, i386
, all
, any
)
Default value: all
The targeted architecture
options.category
Type: String
Default value: misc
The software category. Used to fill the "section" field of the control file
options.preinst.src
Type: String
Default value: undefined
This value specifies the path of the preinst script, the contents of this file will be copied into the preinst script. If both src
and contents
are specified src
will take precedence. The preinst script is executed before the package is unpacked from its Debian archive (".deb") file. Many 'preinst' scripts stop services for packages which are being upgraded until their installation or upgrade is completed (following the successful execution of the 'postinst' script).
options.preinst.contents
Type: String
Default value: undefined
This value specifies the contents of the preinst script, the value will be copied into the preinst script. If both src
and contents
are specified src
will take precedence. The preinst script is executed before the package is unpacked from its Debian archive (".deb") file. Many 'preinst' scripts stop services for packages which are being upgraded until their installation or upgrade is completed (following the successful execution of the 'postinst' script).
options.postinst.src
Type: String
Default value: undefined
This value specifies the path of the postinst script, the contents of this file will be copied into the postinst script. If both src
and contents
are specified src
will take precedence. The postinst script typically completes any required configuration of the package foo once foo has been unpacked from its Debian archive (".deb") file. Often, 'postinst' scripts ask the user for input, and/or warn the user that if he accepts default values, he should remember to go back and re-configure that package as the situation warrants. Many 'postinst' scripts then execute any commands necessary to start or restart a service once a new package has been installed or upgraded.
options.postinst.contents
Type: String
Default value: undefined
This value specifies the contents of the postinst script, the value will be copied into the postinst script. If both src
and contents
are specified src
will take precedence. The postinst script typically completes any required configuration of the package foo once foo has been unpacked from its Debian archive (".deb") file. Often, 'postinst' scripts ask the user for input, and/or warn the user that if he accepts default values, he should remember to go back and re-configure that package as the situation warrants. Many 'postinst' scripts then execute any commands necessary to start or restart a service once a new package has been installed or upgraded.
options.prerm.src
Type: String
Default value: undefined
This value specifies the path of the prerm script, the contents of this file will be copied into the prerm script. If both src
and contents
are specified src
will take precedence. The prerm script typically stops any daemons which are associated with a package. It is executed before the removal of files associated with the package.
options.prerm.contents
Type: String
Default value: undefined
This value specifies the contents of the prerm script, the value will be copied into the prerm script. If both src
and contents
are specified src
will take precedence. The prerm script typically stops any daemons which are associated with a package. It is executed before the removal of files associated with the package.
options.postrm.src
Type: String
Default value: undefined
This value specifies the path of the postrm script, the contents of this file will be copied into the postrm script. If both src
and contents
are specified src
will take precedence. The postrm script typically modifies links or other files associated with foo, and/or removes files created by the package.
options.postrm.contents
Type: String
Default value: undefined
This value specifies the contents of the postrm script, the value will be copied into the postrm script. If both src
and contents
are specified src
will take precedence. The postrm script typically modifies links or other files associated with foo, and/or removes files created by the package.
options.links
Type: String
Default value: undefined
This value specifies a list of soft-links that should be added into the package. Each soft-link is specified using a source
and a target
value. Both the links and directories sections can use the following placeholders ${name}
, ${version}
and ${build_name}
to refer to the package name, version and build number respectively, see example above.
options.directories
Type: String
Default value: undefined
This value specifies a list of directories that should be added into the package. Both the links and directories sections can use the following placeholders ${name}
, ${version}
and ${build_name}
to refer to the package name, version and build number respectively, see example above.
options.follow_soft_links
Type: Boolean
Default value: undefined
This value specifies whether soft-links should be followed when copying files into the package. By default as this value is undefined soft-links will not be followed.
options.custom_template
Type: String
Default value: undefined
This value specifies a custom template directory. It can be used to override the files of the default template (especially useful for overridding copyright or changelog). The content of the directory should have the following structure
- MakeFile
- debian
- changelog
- compat
- control
- copyright
- dirs
- links
- rules
- source
- format
Any missing file will be replaced by the default ones (See packaging directory) The files from the custom_template directory are processed the same way than the default ones, so use of variables is possible
Files
The files configuration specifies the files to add into the package.
This task supports all the file mapping format Grunt supports. Please read Globbing patterns and Building the files object dynamically for additional details.
Usage Examples
Default Options
The following example configuration shows the default values for the options. A files section is added which will add all files in the dist
directory into the /var/www/
directory in the package.
grunt;
Not providing any options will result in the following default values:
var properties = ; options: maintainer: processenvDEBFULLNAME && processenvDEBEMAIL && name: processenvDEBFULLNAME email: processenvDEBEMAIL name: propertiesname short_description: propertiesdescription && propertiesdescription0 long_description: propertiesdescription && propertiesdescription version: propertiesversion build_number: processenvBUILD_NUMBER || processenvDRONE_BUILD_NUMBER || processenvTRAVIS_BUILD_NUMBER target_architecture: "all" category: "misc"
maintainer is taken from the standard debian environment variables DEBFULLNAME
and DEBEMAIL
. name, short_description, long_description and version are all read from the package.json. short_description is taken as the first line of the description
value and long_description is taken as the rest of the description
value. build_number is taken from the the environment variables BUILD_NUMBER
or DRONE_BUILD_NUMBER
or TRAVIS_BUILD_NUMBER
which are the build number environment variables for Jenkins, drone.io and TravisCI respectively.
Future Plans
- Add options to support custom copyright file
- Add options to support generation of changelist from git log
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Release History
- 2014-27-04 v0.1.0 Released debian_package task
- 2014-28-04 v0.1.1 Fixed issue with some dependencies
- 2014-28-04 v0.1.2 Add back missing dirs and links files
- 2014-29-04 v0.1.3 Removed requirement for long descriptions
- 2014-03-05 v0.1.4 Added test framework and fixed bugs
- 2014-15-05 v0.1.5 Added support for dput
- 2014-16-05 v0.1.6 Fixed errors with package upload
- 2014-23-06 v0.1.7 Added support for postfix
- 2014-24-06 v0.1.8 Minor tweaks and better test coverage
- 2014-09-07 v0.1.9 Added initial support for post/pre scripts
- 2014-09-07 v0.1.10 Multiple minor bug fixes and improvements
- 2014-09-07 v0.1.11 Several minor bug fixes and improvements
- 2016-10-22 v0.1.12 #22, #24 and dependency / license fixes
- 2017-04-29 v0.1.13 Updated build & other badges
- 2018-04-23 v0.1.14 Updated build & other bug fixes
Task submitted by James D Bloom