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.
Gaffer allows you to launch OS processes and supervise them. 3 command line tools allows you to use it for now:
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.
To use gaffer tools you need to:
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/plugun
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 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:
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.
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.
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
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
have a look on the Gaffer page for more informations about the commands.
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.
For more informations go on the Gafferctl page.