{"__v":0,"_id":"5821f10f63e87b25000cbcb3","category":{"version":"5821f10e63e87b25000cbc90","project":"570e9147a5da5e0e005fdec3","_id":"5821f10e63e87b25000cbc91","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-04-14T14:28:46.764Z","from_sync":false,"order":0,"slug":"getting-started","title":"Getting Started"},"parentDoc":null,"project":"570e9147a5da5e0e005fdec3","user":"570e90fda5da5e0e005fdec1","version":{"__v":1,"_id":"5821f10e63e87b25000cbc90","project":"570e9147a5da5e0e005fdec3","createdAt":"2016-11-08T15:36:46.296Z","releaseDate":"2016-11-08T15:36:46.296Z","categories":["5821f10e63e87b25000cbc91","5821f10e63e87b25000cbc92","5821f10e63e87b25000cbc93","5821f10e63e87b25000cbc94","5821f10e63e87b25000cbc95","5821f10e63e87b25000cbc96","5821f10e63e87b25000cbc97","5821f10e63e87b25000cbc98","5821f10e63e87b25000cbc99","5821f10e63e87b25000cbc9a","5821f10e63e87b25000cbc9b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"0.16.0","version":"0.16"},"updates":["57c58b9beebbdc1700089a54","57f1043dcb63a83400a42d1a","5803a26d75e4cd23008af9f4","580779426d47320f007a2f82"],"next":{"pages":[],"description":""},"createdAt":"2016-04-14T14:29:48.202Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Depreciated Content\",\n  \"body\": \"This documentation section has been deprecated, but we've got a better one already written! Please refer to the [Installation Guide](https://cog-book.operable.io/#_installation_guide) section of The Cog Book for up to date information.\\n\\nThanks!\\n\\nOperable Team\"\n}\n[/block]\n\n**Fantastic, you've made it!** Let's get Cog up and running so you can see what it's really like to use Cog from chat. In this guide we'll explain how to:\n- Install and run Cog with Docker (+ high level Docker prerequisites)\n- Connect Cog to Slack\n- Configure a relay, relay group, your admin user, and an admin group\n- Test Cog in Slack\n- Install your first bundle (`mist` an AWS management bundle)\n- Have fun and run some commands in Slack (operable and mist commands)\n\n## Want some help installing Cog along the way?\n\nIf you want do this install with the Cog community at your side, join our [Public Cog Slack channel](http://slack.operable.io) and give the room a shout out, \"Hey, I am about to install Cog!\" The community will probably fill you with praise and happy thoughts for being such an smart and beautiful human being.\n\n## Docker prerequisites\nTo make things easier we have a `docker-compose.yml` file to run all the necessary components to get Cog up and running. You'll need to have the following installed. For instructions on how to install and configure Docker take a look at their well written [Docker Installation Guide](https://docs.docker.com/engine/installation/).\n\n1. `docker`\n2. `docker-machine`\n3. `docker-compose`\n\n_Warning_ Docker sometimes does silly things, so if things don't go smoothly as you work through this tutorial, chat with us in the public [Cog Slack](https://www.slack.operable.io).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Start Cog, Relay, and Postgres with Docker\"\n}\n[/block]\n## Download the Docker bits\n\nDownload the example `docker-compose.yml` from the 0.15.1 Cog release.\n\n```\ncurl https://raw.githubusercontent.com/operable/cog/0.15.1/docker-compose.yml \\\n    -o docker-compose.yml\ncurl https://raw.githubusercontent.com/operable/cog/0.15.1/docker-compose.override.slack_example.yml -o docker-compose.override.yml\n```\n\nThe `docker-compose.override.yml` contains default values used to configure Cog and create an admin user used while bootstrapping and running commands from `cogctl`. Change these as you see fit.\n\n## Set environment variables\nSet two environment variables and start Cog with docker compose\n\n* `SLACK_API_TOKEN` - This is the Slack bot token Cog will use to send and receive messages from Slack. Create a new one on Slack's [New Bot Integration Page](https://my.slack.com/services/new/bot).\n* `COG_HOST` - Cog uses this to build urls that correctly route to the Cog container. If you're using a docker machine named default, you can set it to `$(docker-machine ip default)`. Or, if you're using Docker for Mac you can just set it to `127.0.0.1`.\n\n```\nexport SLACK_API_TOKEN=xoxb-00000000000-0000000000000000000\nexport COG_HOST=$(docker-machine ip default)\n\n# When using Docker for Mac you can set COG_HOST to 127.0.0.1\n#     export COG_HOST=\"127.0.0.1\"\n#\n# When using Docker for Windows and running from a PowerShell console:\n#     $Env:SLACK_API_TOKEN=...\n#     $Env:COG_HOST=...\n#\n# Or when running from the standard command prompt (cmd.exe):\n#     set SLACK_API_TOKEN=...\n#     set COG_HOST=...\n\ndocker-compose up\n```\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Managing Container Data\",\n  \"body\": \"For real use of Cog in a Docker environment (i.e., not using the example file directly), you'll want to give consideration to how you want to manage the data created in the containers, particularly the contents of the Postgres database and the `/home/operable/.cogctl` configuration file that is created by the bootstrap process (see below), which contains administrator credentials for accessing the system.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configure Cog from Cog Docker Container\"\n}\n[/block]\nBefore we can start running commands we need to bootstrap Cog, configure Relay, and setup an account for ourselves. For communicating with Cog we will be using `cogctl` a command line application in the Cog container that was previously downloaded.\n\n## Work in the correct Docker container\nLet's jump into the Cog container where all of the example commands below will be run from.\n\n```\ndocker exec -it $(docker-compose ps -q cog) bash\n```\n\n## Create User, Chat-Handle, and Group\nNext let's create a user for you and make sure you have the right permissions to start running commands. Your Cog user can be anything you want and is not specific to any chat adapter. When creating a chat handle you *must* set the handle to your Slack username.\n\n```\ncogctl users create \\\n  --first-name=\"Patrick\" \\\n  --last-name=\"Van Stee\" \\\n  --email=\"patrick:::at:::operable.io\" \\\n  --username=\"patrick\" \\\n  --password=\"supersecret\"\n\ncogctl chat-handles create \\\n  --user=\"patrick\" \\\n  --chat-provider=\"slack\" \\\n  --handle=\"vanstee\"\n\ncogctl groups add cog-admin \\\n  --user=patrick\n```\n\n##  Congrats, you've configured Cog! :sparkles: \nYou've not only configured Cog, you've also created a default relay and set yourself as the admin-user. Now Cog should know who you are when you run a command, and since you're in the cog-admin group you should have all the permissions needed to run Cog's embedded Operable commands. Try it out and ask Cog for help in Slack; you'll need to at-mention the username (eg. `@cog help`) you used for your bot. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/f5de202-160901_DocsGraphics_cog_help.png\",\n        \"160901_DocsGraphics_@cog_help.png\",\n        1059,\n        146,\n        \"#d9d4da\"\n      ],\n      \"caption\": \"Example of asking Cog for help in Slack.\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Install your first bundle\"\n}\n[/block]\nNow that we've configured Cog, let's install our first bundle. Bundles are groups of commands, permissions, and templates that can be installed with a config file. Let's start by installing [mist](https://github.com/cog-bundles/mist), a bundle for talking with Amazon Web Services.\n\n## Clone the bundle\n```\ngit clone https://github.com/cog-bundles/mist.git\n```\n\n## Install the bundle\n\n```\ncogctl bundle install mist/config.yaml \\\n  --templates=\"mist/templates\" \\\n  --enable \\\n  --relay-groups=\"default\"\n```\n\nNow that we've added a new bundle with it's own permissions, we need to make sure our user has those new permissions before we can run any of its commands.\n\n```\ncogctl roles create mist-admin\n\ncogctl permissions | grep mist | awk '{print $1 \":\" $2}' | xargs echo | xargs -n1 cogctl permissions grant --role=mist-admin\n\ncogctl roles grant mist-admin --group=cog-admin\n```\n\nThen all we have to do is tell relay our AWS credentials. For this we'll need to copy a file onto the Relay container so you'll have to exit out of the Cog container.\n\n```\ntouch config.yaml\necho 'AWS_ACCESS_KEY_ID: \"ABCDEFGHIJKLMNOPQRST\"' >> config.yaml\necho 'AWS_SECRET_ACCESS_KEY: \"U/nV0+l/Some0Obvious1Fake2Key3For4AWS5\"' >> config.yaml  \n\ndocker exec -it $(docker-compose ps -q relay) mkdir -p /tmp/bundle_configs/mist\ndocker cp config.yaml $(docker-compose ps -q relay):/tmp/bundle_configs/mist/config.yaml\n```\n\nYay! Now you should be able to ask Cog to run mist commands. Try it out:\n`@cog ec2-find --region=\"us-east-1\"`\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e13f863-160901_DocsGraphics_Slack_MistCommand.png\",\n        \"160901_DocsGraphics_Slack_MistCommand.png\",\n        1059,\n        146,\n        \"#d6d6d6\"\n      ],\n      \"caption\": \"Cog running a mist command.\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"\\\"We've only just begun...\\\" (aka. Next Steps)\"\n}\n[/block]\nCog is still growing and learning new things with the help of you and the open-source community. Here are a few things you can do next.\n  * Join [Cog's public Slack channel](https://www.slack.operable.io) if you haven't already done so\n  * Use the Suggest Edits button at the top of this page to suggest improvements for this guide.\n  * Install some more [Commands and Bundles](https://github.com/cogcmd)\n  * Have needs that our current set of bundles don't cover? [Build a Command Bundle](doc:building-command-bundles)\n  * Read up on [Cog's Architecture](doc:cog-architecture), flying buttresses and all.\n  * Lastly, enjoy Cog + thanks!","excerpt":"","slug":"installation","type":"basic","title":"Installation Guide"}

Installation Guide


[block:callout] { "type": "danger", "title": "Depreciated Content", "body": "This documentation section has been deprecated, but we've got a better one already written! Please refer to the [Installation Guide](https://cog-book.operable.io/#_installation_guide) section of The Cog Book for up to date information.\n\nThanks!\n\nOperable Team" } [/block] **Fantastic, you've made it!** Let's get Cog up and running so you can see what it's really like to use Cog from chat. In this guide we'll explain how to: - Install and run Cog with Docker (+ high level Docker prerequisites) - Connect Cog to Slack - Configure a relay, relay group, your admin user, and an admin group - Test Cog in Slack - Install your first bundle (`mist` an AWS management bundle) - Have fun and run some commands in Slack (operable and mist commands) ## Want some help installing Cog along the way? If you want do this install with the Cog community at your side, join our [Public Cog Slack channel](http://slack.operable.io) and give the room a shout out, "Hey, I am about to install Cog!" The community will probably fill you with praise and happy thoughts for being such an smart and beautiful human being. ## Docker prerequisites To make things easier we have a `docker-compose.yml` file to run all the necessary components to get Cog up and running. You'll need to have the following installed. For instructions on how to install and configure Docker take a look at their well written [Docker Installation Guide](https://docs.docker.com/engine/installation/). 1. `docker` 2. `docker-machine` 3. `docker-compose` _Warning_ Docker sometimes does silly things, so if things don't go smoothly as you work through this tutorial, chat with us in the public [Cog Slack](https://www.slack.operable.io). [block:api-header] { "type": "basic", "title": "Start Cog, Relay, and Postgres with Docker" } [/block] ## Download the Docker bits Download the example `docker-compose.yml` from the 0.15.1 Cog release. ``` curl https://raw.githubusercontent.com/operable/cog/0.15.1/docker-compose.yml \ -o docker-compose.yml curl https://raw.githubusercontent.com/operable/cog/0.15.1/docker-compose.override.slack_example.yml -o docker-compose.override.yml ``` The `docker-compose.override.yml` contains default values used to configure Cog and create an admin user used while bootstrapping and running commands from `cogctl`. Change these as you see fit. ## Set environment variables Set two environment variables and start Cog with docker compose * `SLACK_API_TOKEN` - This is the Slack bot token Cog will use to send and receive messages from Slack. Create a new one on Slack's [New Bot Integration Page](https://my.slack.com/services/new/bot). * `COG_HOST` - Cog uses this to build urls that correctly route to the Cog container. If you're using a docker machine named default, you can set it to `$(docker-machine ip default)`. Or, if you're using Docker for Mac you can just set it to `127.0.0.1`. ``` export SLACK_API_TOKEN=xoxb-00000000000-0000000000000000000 export COG_HOST=$(docker-machine ip default) # When using Docker for Mac you can set COG_HOST to 127.0.0.1 # export COG_HOST="127.0.0.1" # # When using Docker for Windows and running from a PowerShell console: # $Env:SLACK_API_TOKEN=... # $Env:COG_HOST=... # # Or when running from the standard command prompt (cmd.exe): # set SLACK_API_TOKEN=... # set COG_HOST=... docker-compose up ``` [block:callout] { "type": "warning", "title": "Managing Container Data", "body": "For real use of Cog in a Docker environment (i.e., not using the example file directly), you'll want to give consideration to how you want to manage the data created in the containers, particularly the contents of the Postgres database and the `/home/operable/.cogctl` configuration file that is created by the bootstrap process (see below), which contains administrator credentials for accessing the system." } [/block] [block:api-header] { "type": "basic", "title": "Configure Cog from Cog Docker Container" } [/block] Before we can start running commands we need to bootstrap Cog, configure Relay, and setup an account for ourselves. For communicating with Cog we will be using `cogctl` a command line application in the Cog container that was previously downloaded. ## Work in the correct Docker container Let's jump into the Cog container where all of the example commands below will be run from. ``` docker exec -it $(docker-compose ps -q cog) bash ``` ## Create User, Chat-Handle, and Group Next let's create a user for you and make sure you have the right permissions to start running commands. Your Cog user can be anything you want and is not specific to any chat adapter. When creating a chat handle you *must* set the handle to your Slack username. ``` cogctl users create \ --first-name="Patrick" \ --last-name="Van Stee" \ --email="patrick@operable.io" \ --username="patrick" \ --password="supersecret" cogctl chat-handles create \ --user="patrick" \ --chat-provider="slack" \ --handle="vanstee" cogctl groups add cog-admin \ --user=patrick ``` ## Congrats, you've configured Cog! :sparkles: You've not only configured Cog, you've also created a default relay and set yourself as the admin-user. Now Cog should know who you are when you run a command, and since you're in the cog-admin group you should have all the permissions needed to run Cog's embedded Operable commands. Try it out and ask Cog for help in Slack; you'll need to at-mention the username (eg. `@cog help`) you used for your bot. [block:image] { "images": [ { "image": [ "https://files.readme.io/f5de202-160901_DocsGraphics_cog_help.png", "160901_DocsGraphics_@cog_help.png", 1059, 146, "#d9d4da" ], "caption": "Example of asking Cog for help in Slack." } ] } [/block] [block:api-header] { "type": "basic", "title": "Install your first bundle" } [/block] Now that we've configured Cog, let's install our first bundle. Bundles are groups of commands, permissions, and templates that can be installed with a config file. Let's start by installing [mist](https://github.com/cog-bundles/mist), a bundle for talking with Amazon Web Services. ## Clone the bundle ``` git clone https://github.com/cog-bundles/mist.git ``` ## Install the bundle ``` cogctl bundle install mist/config.yaml \ --templates="mist/templates" \ --enable \ --relay-groups="default" ``` Now that we've added a new bundle with it's own permissions, we need to make sure our user has those new permissions before we can run any of its commands. ``` cogctl roles create mist-admin cogctl permissions | grep mist | awk '{print $1 ":" $2}' | xargs echo | xargs -n1 cogctl permissions grant --role=mist-admin cogctl roles grant mist-admin --group=cog-admin ``` Then all we have to do is tell relay our AWS credentials. For this we'll need to copy a file onto the Relay container so you'll have to exit out of the Cog container. ``` touch config.yaml echo 'AWS_ACCESS_KEY_ID: "ABCDEFGHIJKLMNOPQRST"' >> config.yaml echo 'AWS_SECRET_ACCESS_KEY: "U/nV0+l/Some0Obvious1Fake2Key3For4AWS5"' >> config.yaml docker exec -it $(docker-compose ps -q relay) mkdir -p /tmp/bundle_configs/mist docker cp config.yaml $(docker-compose ps -q relay):/tmp/bundle_configs/mist/config.yaml ``` Yay! Now you should be able to ask Cog to run mist commands. Try it out: `@cog ec2-find --region="us-east-1"` [block:image] { "images": [ { "image": [ "https://files.readme.io/e13f863-160901_DocsGraphics_Slack_MistCommand.png", "160901_DocsGraphics_Slack_MistCommand.png", 1059, 146, "#d6d6d6" ], "caption": "Cog running a mist command." } ] } [/block] [block:api-header] { "type": "basic", "title": "\"We've only just begun...\" (aka. Next Steps)" } [/block] Cog is still growing and learning new things with the help of you and the open-source community. Here are a few things you can do next. * Join [Cog's public Slack channel](https://www.slack.operable.io) if you haven't already done so * Use the Suggest Edits button at the top of this page to suggest improvements for this guide. * Install some more [Commands and Bundles](https://github.com/cogcmd) * Have needs that our current set of bundles don't cover? [Build a Command Bundle](doc:building-command-bundles) * Read up on [Cog's Architecture](doc:cog-architecture), flying buttresses and all. * Lastly, enjoy Cog + thanks!