ema

 _______ _______ _______
|    ___|   |   |   _   |
|    ___|       |       |
|_______|__|_|__|___|___|

ema -- Simple process manager for node.js app.

install

npm i -g ema

synopsis

ema [-hVtqd] [-s signal] [-p dirname] [-c filename] [-g directives]

options

-h, --help                    output usage information
-V, --version                 output the version number
-t, --test                    test configuration and exit
-q, --quiet                   suppress non-error messages during configuration testing
-d, --daemon                  daemonize process
-s, --signal <signal>         send signal to a master process: stop, quit, reload
-p, --prefix <dirname>        set prefix path
-c, --config <filename>       set configuration json file
-g, --directives <directive>  set master directives out of configuration file

-h, help

Print help.

-V, version

Print the ema version.

-t, test

Do not run, just test the configuration file.

ema checks the configuration file syntax.

-q, --quiet

Supress non-error messages during configuration testing.

-d, --daemon

Respawn the process as a daemon.

The parent process will exit at the point of this call.

-s, --signal

Send a signal to the master process.

The arguments signal can be on of: stop, quit, reload.

The following table shows the corresponding system signals:

ARG	SIGNAL
stop	SIGTERM
quit	SIGQUIT
reload	SIGHUP

-p, --prefix

Set the prefix path.

The default value is a directory package.json exists.

-c, --config

Use an alternative configuration file.

-g, --directives

Override or set global configuration directives.

JavaScript object format acceptable. (e.g. -g "{pid: './tmp/em2.pid'}")

signals

The master process of ema can handle the following signals:

SIGNAL	operation
SIGINT, SIGTERM	Shut down quickly.
SIGQUIT	Shut down gracefully.
SIGHUP	Reload configuration, start the new worker process with a new configuration, and gracefully shut down old worker processes.

configuration

configuration file example. ema supports json5.

{                                       // global directive
  name       : 'myapp'
  pid_path   : '%h/.myapp.pid',
  access_log : 'log/access.%t.%n.log',
  error_log  : 'log/error.%t.%n.log',
  clustering : 2,
  server: {                             // server directive
    dev: {
      script      : 'config/app.coffee',
      clustering  : 'inherit',
      unmatch_env : 'production',
      env: {
        PORT: 3000
      }
    },
    web: {
      script      : 'config/app.coffee',
      clustering  : 'auto',
      unmatch_env : 'development',
      env: {
        PORT: 3030
      }
    },
    test: {
      script      : 'tests/test.coffee',
      match_env   : 'test'
    }
  }
}

this configuration file wakes following named processes:

$ ema -d
$ ps ax | grep -v grep | grep myapp:
10000 s002  S+     0:00.12 myapp:master
10001 s002  S+     0:00.41 myapp:worker:dev.1
10002 s002  S+     0:00.41 myapp:worker:dev.2
$ ls -a ~ | grep .pid
.myapp.pid

with production (4 core cpu):

$ NODE_ENV=production ema -d
$ ps ax | grep -v grep | grep myapp:
10000 s002  S+     0:00.12 myapp:master
10001 s002  S+     0:00.41 myapp:worker:web.1
10002 s002  S+     0:00.41 myapp:worker:web.2
10003 s002  S+     0:00.41 myapp:worker:web.3
10004 s002  S+     0:00.41 myapp:worker:web.4

configuration keys

common directive

key	description	defaults
access_log	access log path.	String '%d/tmp/log/access.log'
error_log	error log path.	String '%d/tmp/log/error.log'
clustering	num of clustering.	Number `os.cpus().length`

global directive

key	description	defaults
name	name for your application.	String ema
pid_path	pid path.	String '%d/tmp/ema.pid'
timeout	processes disconnect timeout.	Number 2400
server	server directives.	Object {}

server directive

directive key name set to process.title.

key	description	defaults
script	main script name.	String null
match_env	starts only it matched to env.	String null
unmatch_env	starts only it unmatched to env.	String null
env	exports to process.env.	Object {}

conversion specifier

specifier	description	directive	e.g.
%h	user home directory	global, server	/home/user
%d	project root path	global, server	/home/user/project
%p	port number	global, server	3000
%e	node env	global, server	development
%t	process title label	server	web
%c	clustered order	server	/[0-3]/
%C	number of clusters	server	4

files

${prefix}/tmp/ema.pid

Contains the process ID of ema. The contents of this file are not sensitive, so it can be world-readable.

${prefix}/Emafile{,.json}

The main configuration file. To set alternative, use [-c filename] option.

${prefix}/tmp/log/access.log

Log file. To set alternative, check configuration section.

${prefix}/tmp/log/error.log

Error log file. To set alternative, check configuration section.

exit status.

Exit status is 0 on success, or 1 if the command fails.

examples

Test configuration file $PROJECT/config/process.json with global directives for PID:

ema -t -c ./config/process.json -g "{ pid_path: '/tmp/.ema.pid' }"