1.7. Building and Running Cog from Scratch

To run Cog you’ll need to start three separate processes: Postgres, Relay and Cog itself, all of which will require a few dependencies.

  • Postgres 9.4+
  • Erlang 18+
  • Elixir 1.3+
  • Go 1.6+
  • Docker 1.10.3+
  • GCC

Downloading and installing Postgres 9.4+ should be straight forward. Take a look at their download page for more details.

Next, let’s build Relay. You’ll need to install Go 1.6+ and Docker 1.10.3+. Why do we still need Docker? Bundles have the option to define an image on Docker Hub in which to run the command. So, Relay needs to know how to download those images and start containers to run some commands.

Download the source in your $GOPATH and build it.

mkdir -p $GOPATH/src/github.com/operable
git clone [email protected]:operable/go-relay.git $GOPATH/src/github.com/operable/go-relay
cd $GOPATH/src/github.com/operable/go-relay

You should have an executable in _build ready to go. We’ll come back to it in a mintue.

Now, to build Cog. Cog is written in Elixir, which means you’ll need to install both Erlang 18+ and Elixir 1.3+. You can find more information about how to install Elixir on their installation guide. Once you have Elixir installed run the following to clone the Cog repo, download deps, setup the database, compile and run Cog.

git clone git@github.com:operable/cog.git
cd cog
make setup run

You’ll notice that the run target crashed as we didn’t provide a SLACK_API_TOKEN environment variable. To fully configure Cog and Relay we’ll need to set a few environment variables. If you need more customization than is explained in this guide checkout the full listing of environment variables and their descriptions for both Cog Server Configuration and Relay Configuration.

For now let’s just provide the minimum to get things up and running. For Cog, we’ll just need to set COG_SLACK_ENABLED and SLACK_API_TOKEN as everything else has a sensible default. You can get a SLACK_API_TOKEN for your bot by creating a new bot integration. So let’s try running Cog again, now with our token exported.

export SLACK_API_TOKEN=xoxb-87931061512-notarealtokenLNjTMuxxozUo
make run

To get Relay running, we’ll need to supply both RELAY_ID and RELAY_COG_TOKEN which are used to both identify our Relay and allow it to connect to Cog. I would recommend using a uuid for RELAY_ID and a random string for the RELAY_COG_TOKEN. If you have uuid and openssl installed you could use the following commands like these to generate them. After, exporting those variables we can run the run the binary we previously built.

export RELAY_ID=`uuid` && echo $RELAY_ID
export RELAY_COG_TOKEN=`openssl rand -hex 12` && echo $RELAY_COG_TOKEN
export RELAY_DYNAMIC_CONFIG_ROOT=/tmp/dynamic_configs

You’ll see a warning about a missing configuration file, which you can ignore since we’re not using one.

Ok, so now we have both Cog and Relay up and running, but they aren’t actually aware of each other yet. Because Cog was designed to be run with multiple Relays on multiple hosts, we need to tell Cog about our Relay before it can connect. It’s worth noting, that in this example we’ve bound to localhost so certain features like enforcing a matching RELAY_TOKEN are disabled. But, to add a Relay to Cog, we need to build and run Cogctl.

Cogctl is written in Python 3, but can be compiled to a standalone, self-contained binary. Setting up a Python development environment is beyond the scope of this document, but up-to-date instructions can be found in the README of the cogctl repository.

Once you build the binary, you’ll have a cogctl executable in the dist directory of your cogctl checkout. You can run this from its current location, or move it anywhere you like.

Ok, now we just need to bootstrap Cog and create a record for our Relay. Here’s a snippet:

./cogctl bootstrap http://localhost:4000
./cogctl relay create my-relay $RELAY_ID $RELAY_COG_TOKEN

And now you should be in business. But there’s one last step we need to take care of before you can run commands. You’ll need to create an account for yourself. Copying this run the Docker-based walkthrough, run this:

./cogctl user create patrick \
  --first-name="Patrick" \
  --last-name="Van Stee" \
  --email="[email protected]" \

./cogctl chat-handle create patrick slack vanstee

./cogctl group add cog-admin patrick

And now you should be all set. For a quick walkthrough of installing your first bundle and running a command, jump back up to the section titled “Installing and Configuring a Bundle.”