The Shepherd -------- Manage groups of processes. Install: `npm install the-shepherd` Usage: `shep [options]` Global options: --quiet or -q --verbose or -v --force or -f --path - Use `/.shep` instead of searching. Commands: | Command | | Example | | ------- | ----------- | ------- | | init | Create a `.shep` folder here. | `shep init` | | up | Ensure the daemon is running. | `shep up` | | down | Stop the daemon. | `shep down` | | add | Add a process group. | `shep add echo --exec "node echo.js" --port 8081` | | remove | Remove a process group. | `shep remove echo` | | replace | Replace a group with new settings. | `shep replace echo --exec "node foo.js"` | | start | Start processes (autostarts the daemon). | `shep start echo-1` | | stop | Stop processes. | `shep stop echo` | | restart | Restart processes. | `shep restart echo-1` | | disable | Disable an instance or group. | `shep disable --group foo` | | enable | Enable an instance or group. | `shep enable --instance foo-1` | | status | Report the current status. | `shep status --verbose` | | config | Manage the config file. | `shep config --list` | | health | Manage a health-check on a group. | `shep health --group foo --status 200 --interval 3` | | log | Manage the log output. | `shep log --tail` | | nginx | Configure the nginx integration. | `shep nginx --file '%/nginx'` | | scale | Scale a process group to a new size. | `shep scale echo --count 2` | Files ----- `shep` reads and writes state from a `.shep` directory. You can specify this directory using `SHEPHERD_PATH` in the environment, or using the `--path` argument to any command. If unspecified, `shep` will search for a `.shep` directory using the same rule Git uses to search for a `.git` folder: Start in the working directory, and check each parent until you find one. `shep init` is the only command that skips this search. Files inside the `.shep` directory: config - A list of commands to execute at daemon startup. defaults - Will be copied to config by 'shep init'. This file should be in source control. socket - A unix socket used by the daemon to listen for commands. pid - Contains the pid of any currently running daemon. log - The (default) location to log output from all managed processes. nginx - The (default) location to keep an up-to-date set of nginx upstreams. When reading the `config` file, any occurrence of "%" will be replaced with the full path to the `.shep` directory. `> shep init` ----------- `init` ensures that a `.shep` folder exists in the working directory. If a `.shep` folder already exists, and has a `defaults` file, but no `config` file, it will copy `defaults` to `config`. `> shep up` --------- `up` ensures that a daemon has been spawned to manage the current `.shep` directory. --verbose - Launch the daemon with verbose logging. If `.shep/config` exists, each line will be read in as if it had been given as a command to `shep`, eg: log --file "%/log" add echo --cd test/echo --exec "node echo_server.js" --count 4 --port 9001 nginx --disable start When the daemon starts, it will create `.shep/socket` and `.shep/pid`, and possibly others. Where indicated below, many commands cause the currently running configuration to be written to the `config` file (overwriting that file). `> shep down` --------- `down` stops the current daemon, and all processes it was managing. `> shep add` ---------- `add` will add a group, it accepts a standard set of options for specifying a group: --group - Required. Process ids will be like -1, etc. --cd - The working directory for new processes. Optional. Default "." --exec - The shell command to launch the process. Required. --count - Optional. Default 1 --port - The starting port. If n > 0 then port will be incremented. Optional. --grace - How long to allow the process to startup. Optional. Default 9000 If `--port` is specified, each new process is given `PORT` in it's environment. The process is `"started"` once it is listening on it's given `PORT`. Failure to listen on `PORT` within the `--grace` timeout will cause that process to become `"failed"` and not restarted. If `--port` is not specified, then the process is `"started"` if it stays up for it's full `--grace` period. Be careful if you use long `--grace` times, with no `--port`, and high `--count`; this combination will lead to a slow `start` for that group. This command causes `config` to be re-written. `> shep remove` ------------- `remove` will (stop and) remove a current process group. --group This command causes `config` to be re-written. `> shep replace` -------------- `replace` will first `remove` then re-`add` a group, using the new options. Uses the same options as `add`. All the processes in the group will be stopped (during the remove), and started (after the add). This command causes `config` to be re-written. `> shep scale` ------------ `scale` will change just the `--count` option for a group, and will only effect current processes if the new `` is smaller. --group --count If the `--group` is started, then processes will be started or stopped immediately. This command causes `config` to be re-written. The new config will not contain a `--scale` command directly, but instead this scaling will be reflected in the corresponding `add --group` command. `> shep start` ------------ `start` can start specified groups, or processes. --group --instance If no options are given, everything will be started. If the daemon is not running, `up` will be called automatically. `> shep stop` ----------- `stop` can stop specified group, or processes. --group --instance If no options are given, everything will be stopped. `> shep restart` ------------ `restart` can start specified groups, or processes. --group --instance If no options are given, everything will be started. Processes will be restarted serially within a group, but multiple groups will restart in parallel. `> shep log` `log` controls the combined output of all managed processes. --file - eg, the default is "%/log". --disable - Don't write any log file to disk. --tail - Stream the log output. Works even when log file is disabled. When using `--tail`, it will keep the process open until you hit `Ctrl-C`, and behaves like `tail -f api.log`. The difference is that it streams from inside the daemon, through the `socket` file, and to the `shep` client (no file needed). `> shep nginx` ------------ `nginx` controls the built-in nginx integration. --file - Where to keep an up-to-date set of upstreams. --keepalive - How many connections should nginx keep-alive to each pool. --reload - How to notify nginx to reload an updated config. --disable - Don't write any nginx configuration (default). The generated upstreams file might look like this: upstream group_name { server 127.0.0.1:9001 weight=0 down; # disabled server 127.0.0.1:9002 weight=1; # started server 127.0.0.1:9003 weight=1 down; # enabled, but not started keepalive 32; } This file is re-generated, and nginx is notified to (gently) check for configuration changes as process statuses change.