node-deb
Debian packaging for Node.js projects written 100% in bash
.
Simple.
Installation
npm install node-deb
or
git clone ${url} && cd node-deb && npm run node-deb && sudo dpkg -i $(find . -maxdepth 1 -type f -name '*.deb' | tail -n 1)
Usage
A simple project can be packaged with the following command.
node-deb -- index.js lib/
This command will add all of the above files and directories to a Debian package as well as generate the scripts
necessary to install, uninstall, start, and stop your application. On installation, via dpkg -i $your_package_name
,
dedicated Unix users and groups will be created and your distribution's default init system will start and monitor
the process.
node-deb
uses sane defaults, so the only thing you need to add to your package.json
is the app/cli entrypoint.
However, if you don't like these, there are two options for overrides: command line options, or the JSON object
node_deb
at the top level of your package.json
. A full explanation of the different options can be found by
running node-deb --help
.
By default, if any of the following files exist, they will be included in the Debian package: package.json
,
npm-shrinkwrap.json
and package-lock.json
.
For example, here are some sample node_deb
overrides. The full list can be found by running
node-deb --list-json-overrides
.
{
"name": "some-app",
...
"node_deb": {
"init": "systemd",
"version": "1.2.3-beta",
"entrypoints": {
"daemon": "foo.js --config /etc/some-app/config.js"
}
}
}
Command line options always override values found in the node_deb
object, and values found in the node_deb
object
always override the values found in the rest of package.json
.
Examples
Ex. 1
package.json
:
{
"name": "some-app",
"version": "1.2.3",
"node_deb": {
"entrypoints": {
"daemon": "app.js arg1 arg2"
}
}
}
cmd
: node-deb -- app.js lib/
You will get:
- A Debian package named
some-app_1.2.3_all.deb
- Containing the files
app.js
& package.json
and the directory lib
- Installed via
apt-get install some-app
apt-get install some-app=1.2.3
On install, you will get.
- An executable named
some-app
- That starts the app with the command
app.js arg1 arg2 arg3
- An
upstart
init script installed to /etc/init/some-app.conf
- A
systemd
unit file installed to /lib/systemd/system/some-app.service
- A
sysv
int script installed to /etc/init.d/some-app
- A Unix user
some-app
- A Unix group
some-app
Ex. 2
package.json
:
{
"name": "some-other-app",
"version": "5.0.2",
"node_deb": {
"entrypoints": {
"daemon": "index.js --daemon"
}
}
}
cmd
: node-deb -u foo -g bar -v 20150826 -- index.js lib/
You will get:
- A Debian package named
some-other-app_20150826_all.deb
- Containing the files
index.js
, package.json
, & npm-shrinkwrap.json|package-lock.json
and the directories lib
&
node_modules
- Installed via
apt-get install some-other-app
apt-get install some-other-app=20150826
On install, you will get.
- An executable named
some-other-app
- That starts the app with the command
index.js --daemon
- An
upstart
init script installed to /etc/init/some-other-app.conf
- A
systemd
unit file installed to /lib/systemd/system/some-other-app.service
- A
sysv
int script installed to /etc/init.d/some-other-app
- A Unix user
foo
- A Unix group
bar
Ex. 3
package.json
:
{
"name": "a-third-app",
"version": "0.10.1",
"node_deb": {
"init": "none",
"dependencies": "apparmor, tor",
"templates": {
"postinst": "my-teplates/my-postinst-template.txt"
},
"entrypoints": {
"cli": "app.js"
}
}
}
cmd
: node-deb -- app.js lib/
You will get:
- A Debian package named
a-third-app_0.10.1_all.deb
- Containing the files
index.js
, package.json
, & npm-shrinkwrap.json|package-lock.json
and the directories lib
&
node_modules
- With additional dependencies on
apparmor
and tor
- Installed via
apt-get install a-third-app
apt-get install a-third-app=0.10.1
- With the
postinst
script rendered from the template my-postinst-template.txt
On install, you will get.
- An executable named
a-third-app
- That starts the app with the command
app.js
- No
upstart
, systemd
, or sysv
scripts - No Unix user or group
Ex. 4
package.json
:
{
"name": "a-forth-app",
"version": "0.10.1",
"node_deb": {
"init": "none",
"dependencies": "apparmor, tor, nodejs",
"templates": {
"postinst": "my-teplates/my-postinst-template.txt"
},
"entrypoints": {
"cli": "app.js"
}
}
}
cmd
: node-deb --no-default-package-dependencies -- app.js lib/
You will get:
- A Debian package named
a-forth-app_0.10.1_all.deb
- Containing the files
index.js
, package.json
, & npm-shrinkwrap.json|package-lock.json
and the directories lib
&
node_modules
- With dependencies on
apparmor
, tor
and nodejs
only. No default dependencies added - Installed via
apt-get install a-forth-app
apt-get install a-forth-app=0.10.1
- With the
postinst
script rendered from the template my-postinst-template.txt
On install, you will get.
- An executable named
a-forth-app
- That starts the app with the command
app.js
- No
upstart
, systemd
, or sysv
scripts - No Unix user or group
&c.
Note: Removal via apt-get purge
will attempt to remove the user and group defined in the Debian package.
This can have serious consequences if the user or group is shared by other applications!
node-deb
can Debian-package itself. Just run npm run node-deb
.
More complete examples can be found by looking at test.sh
and the corresponding projects in the test
directory.
Options
This section incldues addtional details about the more advanced functionality of node-deb
--install-strategy
The install strategy determines how dependencies in node_modules
are included in the final Debian package.
auto
: This attempts to take a minimal subset of package from the node_modules
director using
npm ls --prod
. If this is not possible, it falls back to the copy
method. On install, if node_modules
is
present, it runs npm rebuild --prod
. If node_modules
is not present, it runs npm install --prod
. If npm
is not present, it issues a warning that dependencies may be missing and continues with the Debian package installation.copy
: This runs a blind cp -rf
on the node_modules
directory and includes everything in the Debian package.
No actions are taking during package installation.npm-install
: This option does not include the node_module
in the Debian package and runs
npm install --production
as part of the postinst
maintainer script.
Requirements
These are all available through apt
and brew
.
Dev Requirements
Tests are run via docker
. This is also available through apt
and brew
.
Support
node-deb
only officially supports the currently supported versions of Debian and Ubuntu (LTS). This includes both
for building packages and deploying packages. At the time of this update, this translates to Debian Wheezy through
Stretch and Ubuntu Trusty through Xenial. Care has been taken to ensure this packages correctly on macOS, and macOS
specific issues should still be reported.
Contributing
Please make all pull requests to the develop
branch.
Please make sure all pull requests pass the test suite locally.