Goku

Getting Started

Getting started with Goku is easy.

goku and gokud

Goku comes in two parts:

  1. gokud is the main engine. It owns, starts, stops and recycles the processes on the server.
  2. goku is the controller part. It uses gokud control API to allow you control the engine through command line if you want.

goku communicates with gokud through JSON-RPC through HTTP. This menas you can write gokud API clients in almost any lauguage and integrate them into your own applications.

In this tutorial, Goku (with capital G) is used to refer to the project. goku and gokud are used to refer to the executables.

Starting with Goku

When installing Goku, you have two options: download the binaries or build it from the source. Goku is written in Go so building it from the source is easy. We also provide compiled binaries for OS X and Linux (64-bit architecture only).

Downloading Binaries

Currently there are no plans to support and provide binaries for other platforms and architectures.

Building from Source

Clone the git repository and build it:

$ git clone https://github.com/cloud66/goku.git goku
$ cd goku/gokud
$ go build
$ cd ../goku
$ go build

This will build both goku and gokud.

Goku Configuration Files

Goku uses toml as the format for its configuration files. Toml is human readable and isn't too precious about tabs and spaces. Here is an example of a Goku configuraiton file:

# just a simple sleepy process
Name         = "My Sleepy Process"
Command      = "sleep"
Args         = ["1"]

This defines a simple process that runs the sleep 1 command. The configuration file is self explainatory but some points might be worth mentioning:

  • Before running the process, Goku tries to find the exact location of the executable within $PATH. In this case it will run /bin/sleep
  • All arguments are passed in strings
  • Name is used to refer to the process through the API

Read Goku Configuraion Files for detailed information about all the parameters in configuration files.

Configuration Directory

gokud expects all configuration toml files to be in the same directory. The path to this directory is passed into gokud with -d parameter when starting gokud.

$ gokud -d /path/to/configuration/directory

Any file with .toml extension will be read and loaded. By default processes are not started when gokud starts. This can be changed with -autostart parameter is used when starting gokud.

Using Command Line

gokud does not run as a daemon. This is intentional. We didn't want to build a replacement for upstart or systemd and wanted to make sure you can run gokud in the foreground if you would like to debug your configuration files. If you would like to run gokud as a daemon, you can use Upstart or Systemd.

Once you have gokud running, in a different terminal window, run the following command

$ goku list

This should return something list this:

Sidekiq       0  [worker]      unmonitored
Unicorn       0  [web worker]  unmonitored
ElasticSearch 0  [web search]  unmonitored

This shows the names of the processes loaded, their pid, their tags and status. Possible statuses are:

  • unmonitored
  • unknown
  • starting
  • up
  • stopping
  • draining

You can now try and start a process:

$ goku start -p unicorn

or you can use the tags to start multiple processes with the -t parameter:

$ goku start -t web

This will start both Unicorn and ElasticSearch processes.

You can also address processes by parts of their name as long as it results in a unique process:

$ goku start -p u

This will start the Unicorn process.

Use the stop command to stop the process. This will start the StopSequence.

$ goku stop -p unicorn

If your process supports draining, you can start recycling it with the recycle command:

$ goku recycle -p unicorn

This will start draining the process while starting a new process with the same configuration. This means the pid you see in the list command is always the pid of the active process. To see the list of all processes (active and draining), use the -v option with the list command:

$ goku list -v

Getting More

You can use the help command with both goku and gokud to see the list of all commands and options available.