Getting started

This tutorial exposes the usage of gaffer as a tool. For a general overview or how to integrate it in your application you should read the overview page.

Introduction

Gaffer allows you to launch OS processes and supervise them. 3 command line tools allows you to use it for now:

  • Gafferd is the process supervisor and should be launched first before to use other tools.
  • Gaffer is a Procfile application manager and allows you to load your Procfile applications in gafferd and watch their status.
  • gafferctl is a more generic tool than gaffer and is more admin oriented. It allows you to setup any process templates and manage your processes. You can also use it to watch the activity in gafferd (process activity or general activity)

A process template is the way you describe the launch of an OS process, how many you want to launch on startup, how many time you want to restart it in case of failures (flapping)…. A process template can be loaded using any tool or on gafferd startup using its configuration file.

Workflow

To use gaffer tools you need to:

  1. First launch gafferd
  2. Use either gaffer or gafferctl to manage your processes

Launch gafferd

For more informations of gafferd go on its documentation page .

To launch gafferd run the following command line:

$ gafferd -c /path/to/gaffer.ini

If you want to launch custom plugins with gafferd you can also set the path to them:

$ gafferd -c /path/to/gaffer.ini -p /path/to/plugin

Note

default plugin path is relative to the user launching gaffer and is set to ~/.gaffer/plugins.

Note

To launch it in daemon mode use the --daemon option.

Then with the default configuration, you can check if gafferd is alive

The configuration file

The configuration file can be used to set the global configuration of gafferd, setup some processes and webhooks.

Note

Since the configuration is passed to the plugin you can also use this configuration file to setup your plugins.

Here is a simple example of a config to launch the dumy process from the example folder:

[process:dummy]
cmd = ./dummy.py
numprocesses = 1
redirect_output = stdout, stderr

Note

Process can be grouped. You can then start and stop all processes of a group and see if a process is member of a group using the HTTP api. (sadly this is not yet possible to do it using the command line).

For example if you want dummy be part of the group test, then [process:dummy] will become [process:test:dummy] . A process template as you can see can only be part of one group.

Groups are useful when you want to manage a configuration for one application or processes / users.

Each process section should be prefixed by process:. Possible parameters are:

  • cmd: the full command line to launch. eg. ./dummy.p¨
  • args: arguments to pass as a string. eg. -some value --option=a
  • cwd: path to working directorty
  • uid: user name or id used to execute the process
  • gid: group name or id used to execute the process
  • detach: if you wnt to completely detach the process from gafferd (gaffer will still continue to supervise it)
  • shell: The process is executed in a shell (unix only)
  • flapping: flapping rule. eg. 2, 1., 7., 5 which means attempts=2, window=1., retry_in=7., max_retry=5
  • redirect_input: to allows you to interract with stdin
  • redirect_output: to watch both stdout & stderr. output names can be whatever you cant. For example you. eg. redirect_output = mystdout, mystderr stdout will be labelled mysdtout in this case.
  • graceful_timeout: time to wait before definitely kill a process. By default 30s. When killing a process, gaffer is first sending a SIGTERM signal then after a graceful timeout if the process hasn’t stopped by itself send a SIGKILL signal. It allows you to handle the way your process will stop.
  • os_env: true or false, to pass all operating system variables to the process environment.
  • priority: Integer. Allows you to fix the order in which gafferd will start the processes. 0 is the highest priority. By default all processes have the same order.

Sometimes you also want to pass a custom environnement to your process. This is done by creating a special configuration section named env:processname. Each environmenets sections are prefixed by env:. For example to pass a special PORT environment variable to dummy:

[env:dummy]
port = 80

All environment variables key are passed in uppercase to the process environment.

Manage your Procfile applications

The gaffer command line tool is an interface to the gaffer HTTP api and include support for loading/unloading Procfile applications, scaling them up and down, … .

It can also be used as a manager for Procfile-based applications similar to foreman but using the gaffer framework. It is running your application directly using a Procfile or export it to a gafferd configuration file or simply to a JSON file that you could send to gafferd using the HTTP api.

Example of use

For example using the following Procfile:

dummy: python -u dummy_basic.py
dummy1: python -u dummy_basic.py

You can launch all the programs in this procfile using the following command line:

$ gaffer start
_images/gafferp.png

Or load them on a gaffer node:

$ gaffer load

All processes in the Procfile will be then loaded to gafferd and started.

If you want to start a process with a specific environment file you can create a .env in he application folder (or use the command line option to tell to gaffer which one to use). Each environmennt variables are passed by lines. Ex:

PORT=80

and then scale them up and down:

$ gaffer scale dummy=3 dummy1+2
Scaling dummy processes... done, now running 3
Scaling dummy1 processes... done, now running 3
_images/gaffer_ps.png

have a look on the Gaffer page for more informations about the commands.

Control gafferd with gafferctl

gafferctl can be used to run any command listed below. For example, you can get a list of all processes templates:

$ gafferctl processes

You can simply add a process using the load command:

$ gafferctl load_process ../test.json
$ cat ../test.json | gafferctl load_process -
$ gafferctl load_process - < ../test.json

test.json can be:

{
    "name": "somename",
    "cmd": "cmd to execute":
    "args": [],
    "env": {}
    "uid": int or "",
    "gid": int or "",
    "cwd": "working dir",
    "detach: False,
    "shell": False,
    "os_env": False,
    "numprocesses": 1
}

You can also add a process using the add command:

gafferctl add name inc

where name is the name of the process to create and inc the number of new OS processes to start.

To start a process run the following command:

$ gafferctl start name

And stop it using the stop command.

To scale up a process use the add command. For example to increase the number of processes from 3:

$ gafferctl add name 3

To decrease the number of processes use the command stop/

The command watch allows you to watch changes n a local or remote gaffer node.

_images/gaffer_watch.png

Demo