2. Bootstrapping Cog

Since interactions with Cog require a user account, you’ll need to bootstrap your system before you can do anything interesting with it. This process will create the necessary administrator role and user group, as well as create the first user account and place it into that administrator group. At this point, you can interact with Cog as this first privileged user in order to create other user accounts (to which you can also grant administrative access), install bundles, and perform other tasks.

There are a few ways you can bootstrap. If your Cog system is automated in any way (using Chef, Puppet, Ansible, or some flavor of AWS or Heroku deployment, for example), you may find it convenient to automatically bootstrap your new system using environment variables.

Alternatively, you can use the cogctl bootstrap command, as detailed below.

Whichever way you choose, read further on this page, as the underlying principles are the same.

cogctl bootstrap http://cog.mycompany.com:4000
Bootstrapping the server

Note

You can run cogctl bootstrap multiple times; if the system is already bootstrapped, cogctl will alert you and return a 1 exit code, but the Cog system itself will remain unaffected.

If you take a look in ~/.cogctl, you’ll begin to see what has happened.

cat ~/.cogctl
[defaults]
profile=cog.mycompany.com

[cog.mycompany.com]
url=http://cog.mycompany.com:4000
password=BgEocTFGzON$U39srRt5^fi(ZD0KxV*1
user=admin

Here, we can see that a user named admin has been created for us on the Cog instance running on this machine. A password has also been generated for this user. Now, whenever we run any cogctl commands from this machine, these credentials will be used by default to make authenticated API calls.

Cog’s REST API is guarded by Cog’s authorization system, which means that the admin user must have permissions to access the API somehow. As detailed in Permissions and Rules, permissions must be attached to a user somehow through a combination of roles and groups. As you can probably guess, the bootstrapping process handles all this. Let’s use cogctl to examine what has been done.

First, let’s just check that we actually exist :smile:

cogctl user
USERNAME  FULL NAME          EMAIL ADDRESS
admin     Cog Administrator  cog@localhost

phew!

Now let’s examine the core permissions of the Cog system. These govern fine-grained access to the various REST API endpoints and chat commands.

cogctl permission
NAME                         ID
operable:manage_commands     a8cd921d-49a9-497a-a977-79ad50512df9
operable:manage_groups       fa9d0311-2791-462a-9bf9-05fe29299109
operable:manage_permissions  cf604203-f546-43cb-8677-51c698140867
operable:manage_relays       365228d2-d082-4bfa-ac7d-ff731a92100d
operable:manage_roles        fec52faa-5106-4982-ad0b-cbe5307c26ec
operable:manage_triggers     4b6b01d7-0d54-4435-befd-c9bb23212404
operable:manage_users        65de7570-7b3f-4ebd-98fd-786f9e9b5cc2

That’s a lot of permissions; Cog helps us out by creating a cog-admin role to collect them all together.

cogctl role info cog-admin
Name         cog-admin
ID           15c77231-e53f-4ab9-b438-64b4a2f636d6
Permissions  manage_commands, manage_groups, manage_permissions, manage_relays, manage_roles, manage_triggers, manage_user_pipeline, manage_users
Groups       cog-admin

To complete the loop, we have a group that is also named cog-admin with the admin user as its sole member. This group is granted the cog-admin role.

cogctl group info cog-admin
ID     88f30dec-ca13-4d92-a6bd-4631acc7424b
Name   cog-admin
Users  admin
Roles  cog-admin

Though the Cog admin user is named admin, there’s nothing particularly special about that name. As this tour of the bootstrapping process has shown us, the admin user functions as an administrator, able to perform any task in the Cog system, only because it resides in a group that has been granted all the core permissions. Any user in this group would have the same capabilities.

This also shows how to make any Cog user an administrator; simply add them to the cog-admin group.