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 tooll 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:
- First launch gafferd
- 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 aSIGKILL
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
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.
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.
For more informations go on the gafferctl
page.