Note: this quick start guide requires god 0.12.0 or above. You can check your version by running:

$ god --version

The easiest way to understand how god will make your life better is by trying out a simple example. To get you up and running quickly, I'll show you how to keep a trivial server running.

Open up a new directory and write a simple server. Let's call it simple.rb :

loop do puts 'Hello' sleep 1 end

Now we'll write a god config file that tells god about our process. Place it in the same directory and call it simple.god :

God . watch do | w | w . name = "simple" w . start = "ruby /full/path/to/simple.rb" w . keepalive end

This is the simplest possible god configuration. We start by declaring a God.watch block. A watch in god represents a process that we want to watch and control. Each watch must have, at minimum, a unique name and a command that tells god how to start the process. The keepalive declaration tells god to keep this process alive. If the process is not running when god starts, it will be started. If the process dies, it will be restarted.

In this example the simple process runs foreground, so god will take care of daemonizing it and keeping track of the PID for us. When possible, it's best to let god daemonize processes for us, that way we don't have to worry about specifying and keeping track of PID files. Later on we'll see how to manage processes that can't run foreground or that require PID files to be specified.

To run god, we give it the configuration file we wrote with -c . To see what's going on, we can ask it to run foreground with -D :

$ god -c path/to/simple.god -D

There are two ways that god can monitor your process. The first and better way is with process events. Not every system supports it, but those that do will automatically use it. With events, god will know immediately when a process exits. For those systems without process event support, god will use a polling mechanism. The output you see throughout this section will show both ways.

After starting god, you should see some output like the following:

# Events I [2011-12-10 15:24:34] INFO: Loading simple.god I [2011-12-10 15:24:34] INFO: Syslog enabled. I [2011-12-10 15:24:34] INFO: Using pid file directory: /Users/tom/.god/pids I [2011-12-10 15:24:34] INFO: Started on drbunix:///tmp/god.17165.sock I [2011-12-10 15:24:34] INFO: simple move 'unmonitored' to 'init' I [2011-12-10 15:24:34] INFO: simple moved 'unmonitored' to 'init' I [2011-12-10 15:24:34] INFO: simple [trigger] process is not running (ProcessRunning) I [2011-12-10 15:24:34] INFO: simple move 'init' to 'start' I [2011-12-10 15:24:34] INFO: simple start: ruby /Users/tom/dev/mojombo/god/simple.rb I [2011-12-10 15:24:34] INFO: simple moved 'init' to 'start' I [2011-12-10 15:24:34] INFO: simple [trigger] process is running (ProcessRunning) I [2011-12-10 15:24:34] INFO: simple move 'start' to 'up' I [2011-12-10 15:24:34] INFO: simple registered 'proc_exit' event for pid 23298 I [2011-12-10 15:24:34] INFO: simple moved 'start' to 'up' # Polls I [2011-12-07 09:40:18] INFO: Loading simple.god I [2011-12-07 09:40:18] INFO: Syslog enabled. I [2011-12-07 09:40:18] INFO: Using pid file directory: /Users/tom/.god/pids I [2011-12-07 09:40:18] INFO: Started on drbunix:///tmp/god.17165.sock I [2011-12-07 09:40:18] INFO: simple move 'unmonitored' to 'up' I [2011-12-07 09:40:18] INFO: simple moved 'unmonitored' to 'up' I [2011-12-07 09:40:18] INFO: simple [trigger] process is not running (ProcessRunning) I [2011-12-07 09:40:18] INFO: simple move 'up' to 'start' I [2011-12-07 09:40:18] INFO: simple start: ruby /Users/tom/dev/mojombo/god/simple.rb I [2011-12-07 09:40:19] INFO: simple moved 'up' to 'up' I [2011-12-07 09:40:19] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 09:40:24] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 09:40:29] INFO: simple [ok] process is running (ProcessRunning)

Here you can see god starting up, noticing that the simple process isn't running, starting it, and then checking every five seconds to make sure it's up. If you'd like to see god work its magic, go ahead and kill the simple process. You should then see something like this:

# Events I [2011-12-10 15:33:38] INFO: simple [trigger] process 23416 exited (ProcessExits) I [2011-12-10 15:33:38] INFO: simple move 'up' to 'start' I [2011-12-10 15:33:38] INFO: simple deregistered 'proc_exit' event for pid 23416 I [2011-12-10 15:33:38] INFO: simple start: ruby /Users/tom/dev/mojombo/god/simple.rb I [2011-12-10 15:33:38] INFO: simple moved 'up' to 'start' I [2011-12-10 15:33:38] INFO: simple [trigger] process is running (ProcessRunning) I [2011-12-10 15:33:38] INFO: simple move 'start' to 'up' I [2011-12-10 15:33:38] INFO: simple registered 'proc_exit' event for pid 23601 I [2011-12-10 15:33:38] INFO: simple moved 'start' to 'up' # Polls I [2011-12-07 09:54:59] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 09:55:04] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 09:55:09] INFO: simple [trigger] process is not running (ProcessRunning) I [2011-12-07 09:55:09] INFO: simple move 'up' to 'start' I [2011-12-07 09:55:09] INFO: simple start: ruby /Users/tom/dev/mojombo/god/simple.rb I [2011-12-07 09:55:09] INFO: simple moved 'up' to 'up' I [2011-12-07 09:55:09] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 09:55:14] INFO: simple [ok] process is running (ProcessRunning)

While keeping a process up is useful, it would be even better if we could make sure our process was behaving well and restart it when resource utilization exceeds our specifications. With a few additions, we can easily have our process restarted when memory usage or CPU goes above certain limits. Edit your sample.god config file to look like this:

God . watch do | w | w . name = "simple" w . start = "ruby /full/path/to/simple.rb" w . keepalive ( :memory_max => 150 . megabytes , :cpu_max => 50 . percent ) end

Here I've specified a :memory_max option to the keepalive command. Now if the process memory usage goes above 150 megabytes, god will restart it. Similarly, by setting the :cpu_max , god will restart my process if its CPU usage goes over 50%. By default these properties will be checked every 30 seconds and will be acted upon if there is an overage for three out of any five checks. This prevents the process from getting restarted for temporary resource spikes.

To test this out, modify your simple.rb server script to introduce a memory leak:

data = '' loop do puts 'Hello' 100000 . times { data << 'x' } end

Ctrl-C out of the foregrounded god instance. Notice that your current simple server will continue to run. Start god again with the same command as before. Now instead of starting the simple process, it will notice that one is already running and simply switch to the up state.

# Events I [2011-12-10 15:36:00] INFO: Loading simple.god I [2011-12-10 15:36:00] INFO: Syslog enabled. I [2011-12-10 15:36:00] INFO: Using pid file directory: /Users/tom/.god/pids I [2011-12-10 15:36:00] INFO: Started on drbunix:///tmp/god.17165.sock I [2011-12-10 15:36:00] INFO: simple move 'unmonitored' to 'init' I [2011-12-10 15:36:00] INFO: simple moved 'unmonitored' to 'init' I [2011-12-10 15:36:00] INFO: simple [trigger] process is running (ProcessRunning) I [2011-12-10 15:36:00] INFO: simple move 'init' to 'up' I [2011-12-10 15:36:00] INFO: simple registered 'proc_exit' event for pid 23601 I [2011-12-10 15:36:00] INFO: simple moved 'init' to 'up' # Polls I [2011-12-07 14:50:46] INFO: Loading simple.god I [2011-12-07 14:50:46] INFO: Syslog enabled. I [2011-12-07 14:50:46] INFO: Using pid file directory: /Users/tom/.god/pids I [2011-12-07 14:50:47] INFO: Started on drbunix:///tmp/god.17165.sock I [2011-12-07 14:50:47] INFO: simple move 'unmonitored' to 'up' I [2011-12-07 14:50:47] INFO: simple moved 'unmonitored' to 'up' I [2011-12-07 14:50:47] INFO: simple [ok] process is running (ProcessRunning)

In order to get our new simple server running, we can issue a command to god to have our process restarted:

$ god restart simple

From the logs you can see god killing and restarting the process:

# Events I [2011-12-10 15:38:13] INFO: simple move 'up' to 'restart' I [2011-12-10 15:38:13] INFO: simple deregistered 'proc_exit' event for pid 23601 I [2011-12-10 15:38:13] INFO: simple stop: default lambda killer I [2011-12-10 15:38:13] INFO: simple sent SIGTERM I [2011-12-10 15:38:14] INFO: simple process stopped I [2011-12-10 15:38:14] INFO: simple start: ruby /Users/tom/dev/mojombo/god/simple.rb I [2011-12-10 15:38:14] INFO: simple moved 'up' to 'restart' I [2011-12-10 15:38:14] INFO: simple [trigger] process is running (ProcessRunning) I [2011-12-10 15:38:14] INFO: simple move 'restart' to 'up' I [2011-12-10 15:38:14] INFO: simple registered 'proc_exit' event for pid 23707 I [2011-12-10 15:38:14] INFO: simple moved 'restart' to 'up' # Polls I [2011-12-07 14:51:13] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 14:51:13] INFO: simple move 'up' to 'restart' I [2011-12-07 14:51:13] INFO: simple stop: default lambda killer I [2011-12-07 14:51:13] INFO: simple sent SIGTERM I [2011-12-07 14:51:14] INFO: simple process stopped I [2011-12-07 14:51:14] INFO: simple start: ruby /Users/tom/dev/mojombo/god/simple.rb I [2011-12-07 14:51:14] INFO: simple moved 'up' to 'up' I [2011-12-07 14:51:14] INFO: simple [ok] process is running (ProcessRunning)

God will now start reporting on memory and CPU utilization of your process:

# Events and Polls I [2011-12-07 14:54:37] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 14:54:37] INFO: simple [ok] memory within bounds [2032kb] (MemoryUsage) I [2011-12-07 14:54:37] INFO: simple [ok] cpu within bounds [0.0%%] (CpuUsage) I [2011-12-07 14:54:42] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 14:54:42] INFO: simple [ok] memory within bounds [2032kb, 13492kb] (MemoryUsage) I [2011-12-07 14:54:42] INFO: simple [ok] cpu within bounds [0.0%%, *99.7%%] (CpuUsage) I [2011-12-07 14:54:47] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 14:54:47] INFO: simple [ok] memory within bounds [2032kb, 13492kb, 25568kb] (MemoryUsage) I [2011-12-07 14:54:47] INFO: simple [ok] cpu within bounds [0.0%%, *99.7%%, *100.0%%] (CpuUsage) I [2011-12-07 14:54:52] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 14:54:52] INFO: simple [ok] memory within bounds [2032kb, 13492kb, 25568kb, 37556kb] (MemoryUsage) I [2011-12-07 14:54:52] INFO: simple [trigger] cpu out of bounds [0.0%%, *99.7%%, *100.0%%, *98.4%%] (CpuUsage) I [2011-12-07 14:54:52] INFO: simple move 'up' to 'restart'

On the last line of the above log you can see that CPU usage has gone above 50% for three cycles and god will issue a restart operation. God will continue to monitor the simple process for as long as god is running and the process is set to be monitored.

Now, before you kill the god process, let's kill the simple server by asking god to stop it for us. In a new terminal, issue the command:

$ god stop simple

You should see the following output:

Sending 'stop' command The following watches were affected: simple

And in the foregrounded god terminal window, you'll see the log of what happened:

# Events I [2011-12-10 15:41:04] INFO: simple stop: default lambda killer I [2011-12-10 15:41:04] INFO: simple sent SIGTERM I [2011-12-10 15:41:05] INFO: simple process stopped I [2011-12-10 15:41:05] INFO: simple move 'up' to 'unmonitored' I [2011-12-10 15:41:05] INFO: simple deregistered 'proc_exit' event for pid 23707 I [2011-12-10 15:41:05] INFO: simple moved 'up' to 'unmonitored' # Polls I [2011-12-07 09:59:59] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 10:00:04] INFO: simple [ok] process is running (ProcessRunning) I [2011-12-07 10:00:07] INFO: simple stop: default lambda killer I [2011-12-07 10:00:07] INFO: simple sent SIGTERM I [2011-12-07 10:00:08] INFO: simple process stopped I [2011-12-07 10:00:08] INFO: simple move 'up' to 'unmonitored' I [2011-12-07 10:00:08] INFO: simple moved 'up' to 'unmonitored'

Now feel free to Ctrl-C out of god. Congratulations! You've just taken god for a test ride and seen how easy it is to keep your processes running.