appman

Appman

Appman is a scriptable Node.js apps manager

Features

1. Easy integration with other tools - Because appman is executed contextually in the present working directory, it can be easily integrated with tools like upstart, cron, and programatically-connected SSH connections, just by cding to the directory of interest.
2. Scriptable - You can add event handlers app start, startFail, restart, restartFail, stop, and crashDetect events. More events and methods coming soon.
3. Status and info query - You can quickly query the status of the app or its details from the commandline.
4. Developer API - Appman provides an API for interacting with data in your app.
5. Plugins and custom commands - Coming in 0.3.x, you can create Appman plugins and write custom commands to suite your especial needs.

Notes

1. Local - The appman command is executed in the context of the current directory - you don't have to specify the file name to manage the app.
2. One app per directory - Because of the local context of appman, a single app is run per directory.
3. Node specific - Appman built specifically for Node apps. appman will not run in a directory which is not a valid Node application directory - uses package.json to validate.
4. Deafult main file - To start your app without having to specify a file name, specify the main field of package.json to the main file of your app.

Installation

Commandline tool

$ sudo npm install appman -g

Dependency package

If you want to use the Appman API in your app, install the module locally as well.

$ npm install appman --save

The Appman API currently allows you to add custom fields to the info object via appman.info.set().

Commands

###start

Start the app with various options.

• -d, --daemon - Daemonize the app - enables the app to continue running after logging out of the shell.
• -f, --filename - Start the app using a file (in the app directory) different from the main file specified in package.json.
• -w, --watch - Watch for file changes, and restart if it happens.
• --watch-files - Files to watch for, to be used with -w. Make sure to quote the files. Eg: --watch-file '*.js,app/js/*.js,app/views/*.jade'
• -r, --revive - Attempt to restart app if it crashes.
• --crash-check-interval - How frequently to check for crashes (in milliseconds). Defaults to 5000.
• --revival-attempts - Number of revival atempts. Defaults to 5.
• -e, --enable-api - Enable API. The appman module must be loaded in the app.
• --no-script - Don't load appman script, even if it exists

Appman uses gaze for watching file activities, refer the gaze docs for details about file pattern specifications.

Examples

$ appman start - starts the app

$ appman start -d - starts the app and daemonizes it

$ appman start -w - starts the app and watches it for changes and restarts the app on file changes

$ appman start -dw - starts the app, daemonizes it, and watches it for changes and restarts the app on file changes

For convenience, you can specify the start options in a file named appman.js (appman script) in the app directory. For details, refer the Scripting section.

Commandline options will override those specified in the appman script. Also note that there is no way to unset an option from the commandline, you can only overwrite the current value.

###list

List the apps started by Appman.

Short flag: -l

###stop

Stop the running app.

Short flag: -S

###restart

Restart the app. Starts the app, if it is not running already.

Short flag: -R

###status

Get the status of the app.

Short flag: -s

###info

Get detailed info about the app.

Short flag: -i

You can add additional fields to the info object via the Appman API in your code.

var appman = require('appman');
appman.info.set('port', 3000);

To enable this feature, you will need to install a local copy appman in the app directory and start your app with the -e / --enable-api option.

###clean

Stop the Appman monitor and kill any runaway processes.

Short flag: -c

###reset

In the current directory, delete all files related to Appman, stop all processes started by Appman.

Short flag: -C

API

Appman provides an API for deveopers to add key-value data to the app information object which can be queried via the info command.

Install the appman Node module in the app dir.

$ npm install appman --save

Load the module in the app.

var appman = require('appman');

###info

Currently info is the only object from the API exposed to the developer. It provides two methods.

Set the value of the key key to value.

appman.info.set(<key>, <value>)

Get the value of the key key.

appman.info.get(<key>)

Scripting

Appman can be configured and programmed using a the appman script in the application directory.

Load the appman module in the appman file to script various aspects of Appman and the app started by it.

var appman = require('appman');

Appman options

Start options can be set using the appman.set() function.

appman.set() can accept a key and a value to set:

appman.set('daemon', true);

or an object specifying the values:

appman.set({
  'file': 'neo.js',
  'watch': true,
  'watch-files': '*.js, *.jade',
  'revive': true,
  'crash-check-interval': 2000,
  'revival-attempts': 5,
  'enable-api': true,
  'daemon': true
});

To get an option use appman.get():

console.log(appman.get('file'));

For edited options to take effect, the app has to be restarted.

Event listeners

You can add event listeners to the app started by Appman.

var appman = require('appman');
var app = appman.app();

app.on('start', function(start) {
  console.log('STARTED: ', start.time, start.pid);
});

The event handler functions will receive an object with the following properties: pid, event, and time.

Currently start, startFail, restart, restartFail, stop, and crashDetect are supported. In future you will be able to start, restart, and stop the app programmatically, as well.

Edited event handlers will be reflected in a watched app, no need to restart the app.

Notes

• Start options provided via the commandline will override those specified in the appman script.
• console.log() in appman script will print at the console only for attached apps. For daemonized apps, it will be logged to .appman/script.log.
• To listen for crashDetect event, you will need to start the app with -r / --revive option.
• crashDetect event will be triggered only when the crash is detected, not when it happens. You can adjust crash detection accuracy using the --crash-check-interval option.
• Appman script will be loaded when there is a commandline start or hard restart. It will not be reloaded for restarts via watch and revive.
• You can load and use any Node module in the appman script.
• If you don't want Appman to load the script, start it with the --no-script option

Logs

Appman logs are located at the following locations in the app directory:

.appman/appman.log - From appman .appman/monitor.log - From appman monitor .appman/stdout.log - From the app's stdout .appman/stderr.log - From the app's stderr .appman/script.log - From appman script

Developer Notes

You might want to add .appman/ to your .gitignore file.

License (MIT)

Copyright (c) 2014 Hage Yaapa [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.