Goku

Goku Configuration File

This is a configuration file in its full glory:

# a full process configuration
Name         = "My Process"
Command      = "unicorn"
Args         = ["-r", "-speed=fast"]
Directory    = "/var/jungle"
UseEnv       = false
Envs         = ["MY_ENV=1", "HERE_IS_ANOTHER_ONE=yes"]
User         = "user"
Group        = "group"
AllowDrain   = true
Tags         = ["tag1", "tag2"]
CallbackId   = "cc695a98f39847dea67dfd0df41c8688"
[[StopSequence]]
Signal = "term"
Wait   = "10s"
[[StopSequence]]
Signal = "kill"
Wait   = "1s"
[DrainSignal]
Signal = "usr2"
Wait   = "1m"

Let's see what each parameter means

Name – Required

Unique name for the process. Used to address it in command line or the API.

Command – Required

Name of the executable to run. It should not contain path or any parameters. Goku always tries to find the full path of the command in $PATH.

Args

List of arguments passed into the command. All arguments should be strings.
Default: []

UseEnv

Boolean If true gokud will run the process with the same environment variables running gokud itself.
Default: true

Envs

A list of environment variables with their values that will be made available to the process. This is only used when UseEnv is false
Default: []

User

Name of the Unix user running the process. If not present, the same user running gokud is used.
Default: ""

Group

Name of the Unix group running the process. If not present, the same group running gokud is used.
Default: ""

AllowDrain

Boolean. If true it indicates this process supports draining. See DrainSignal
Default: false

CallbackId

Used by notifications. When the process status changes and Goku sends a notification, this Id is sent back so the server can identify it.
Default: ""

StopSequence

Array. This specifies the sequence of Unix signals that should be sent to the process and the time that's needed to wait between each one in order to stop the process.

The valid values for Signal are:abrt,alrm,bus,chld,cont,fpe,hup,ill, int,io,iot,kill,pipe,prof,quit,segv,stop,sys,term,trap,tstpttin,ttou,urg,usr1,usr2,vtalrm,winch,xcpu,xfsz

Wait is the duration that gokud waits before checking to see if the process is stopped. If the process is still running after the wait, it will send the next signal in the sequence.

Valid values for Wait consist of a positive number and a unit. Units can be one of these: ms, s, m, h for Millisecond, Second, Minues and Hours. It could also be a combination like 2h45m or 1m25s. A 0 wait duration means "no wait".

StopSequence is a toml array. In the example above, a term signal is sent to the process followed by a kill signal, 10 seconds later if the process is still running.

If a process is still running after all signals in the sequence have been sent and waits is over, goku will try to forcefully kill the process.

Default: term for 5s, quit for 5s, kill for 0s

DrainSignal

Draining (or recycling) is the process of trying to stop a process from taking on new work while starting a new similar process to handle new workload. This will result in a smooth and seamless restart (hot restart).

An example of this could be a web server. Restarting a web server can result in loss of traffic or service interruption. If the web server supports hot restarts (like unicorn for example), a restart can be performed by sending a "drain" signal to the running process which stops it from serving any new clients. While the old process is finishing the existing clients it is serving, we can start a new process with the same configuration to take on new clients. Once the old process has finished serving its old clients, it can be killed.

DrainSignal configures the Unix signal to be sent to the process to start draining as well as the wait needed after that before the process is stopped. Once the wait is over, a StopSequence is started to stop the process gracefully. If the process is still running at the end of the StopSequence, it will be forcefully killed.

Default: None