|
| 1 | + |
| 2 | +# Building a Botkit-based Slack Bot that uses the GCP NL API and runs on Google Container Engine |
| 3 | + |
| 4 | + |
| 5 | +This example shows a Slack bot built using the [Botkit](https://github.com/howdyai/botkit) library. |
| 6 | +It runs on a Google Container Engine (Kubernetes) cluster, and uses one of the Google Cloud Platform's ML |
| 7 | +APIs, the Natural Language (NL) API, to interact in a Slack channel. |
| 8 | + |
| 9 | +It uses the NL API in two different ways. |
| 10 | +First, it uses the [Google Cloud NL API](https://cloud.google.com/natural-language/) to assess |
| 11 | +the [sentiment](https://cloud.google.com/natural-language/docs/basics) of any message posted to |
| 12 | +the channel, and if the positive or negative magnitude of the statement is |
| 13 | +sufficiently large, it sends a 'thumbs up' or 'thumbs down' in reaction. |
| 14 | + |
| 15 | +Additionally, it uses the NL API to identify [entities](https://cloud.google.com/natural-language/docs/basics) in each |
| 16 | +posted message, and tracks them in a database (using sqlite3). Then, at any time you can query the NL slackbot to ask |
| 17 | +it for the top N entities used in the channel. |
| 18 | + |
| 19 | +The example uses [Google Container |
| 20 | +Engine](https://cloud.google.com/container-engine/), a hosted version of |
| 21 | +[Kubernetes](http://kubernetes.io), to run the bot, and uses [Google Container |
| 22 | +Registry](https://cloud.google.com/container-registry/) to store a Docker image |
| 23 | +for the bot. |
| 24 | + |
| 25 | + |
| 26 | +## Setting up your environment |
| 27 | + |
| 28 | +### Container Engine prerequisites |
| 29 | + |
| 30 | +First, set up the Google Container Engine |
| 31 | +[prerequisites](https://cloud.google.com/container-engine/docs/before-you-begin), including [installation of the Google Cloud SDK](https://cloud.google.com/sdk/downloads). |
| 32 | + |
| 33 | +### NL API prerequisites |
| 34 | + |
| 35 | +Next, enable the NL API for your project and authenticate to your service account as described [here](https://cloud.google.com/natural-language/docs/getting-started). (The service account step is not necessary when running the bot on Container Engine, but it is useful if you're testing locally). |
| 36 | + |
| 37 | +### Create a cluster |
| 38 | + |
| 39 | +Next, |
| 40 | +[create a Kubernetes cluster](https://cloud.google.com/container-engine/docs/clusters/operations#creating_a_container_cluster) using Container Engine as follows: |
| 41 | + |
| 42 | +```bash |
| 43 | +gcloud container clusters create "slackbot-cluster" --scopes "https://www.googleapis.com/auth/cloud-platform" |
| 44 | +``` |
| 45 | + |
| 46 | +You can name the cluster something other than "slackbot-cluster" if you like. |
| 47 | + |
| 48 | +### Install Docker |
| 49 | + |
| 50 | +If you do not already have [Docker](https://www.docker.com/) installed locally, follow the [installation instructions](https://docs.docker.com/engine/installation/) on the Docker site. |
| 51 | + |
| 52 | +## Get a Slack token and invite the bot to a Slack channel |
| 53 | + |
| 54 | +Then, create a [Slack bot user](https://api.slack.com/bot-users) and get an |
| 55 | +authentication token. |
| 56 | + |
| 57 | +Then, 'invite' your new bot to a channel on a Slack team. |
| 58 | + |
| 59 | +## Running the slackbot on Kubernetes |
| 60 | + |
| 61 | +### Upload the slackbot token to Kubernetes |
| 62 | + |
| 63 | +We will be loading this token in our bot using |
| 64 | +[secrets](http://kubernetes.io/v1.1/docs/user-guide/secrets.html). |
| 65 | + |
| 66 | +Run the following script to create a secret .yaml file (replacing `MY-SLACK-TOKEN` with your token), then use that yaml file to create a secret on your Kubernetes cluster. |
| 67 | + |
| 68 | +```bash |
| 69 | +./generate-secret.sh MY-SLACK-TOKEN |
| 70 | +kubectl create -f slack-token-secret.yaml |
| 71 | +``` |
| 72 | + |
| 73 | +### Build the bot's container |
| 74 | + |
| 75 | +We'll run the slackbot app in our Kubernetes cluster as a [Replication Controller](http://kubernetes.io/docs/user-guide/replication-controller/) with one replica. |
| 76 | + |
| 77 | +So, first, we need to build its Docker container. Replace `my-cloud-project-id` below with your |
| 78 | +Google Cloud Project ID. This tags the container so that gcloud can upload it to |
| 79 | +your private Google Container Registry. |
| 80 | + |
| 81 | +```bash |
| 82 | +export PROJECT_ID=my-cloud-project-id |
| 83 | +docker build -t gcr.io/${PROJECT_ID}/slack-bot . |
| 84 | +``` |
| 85 | + |
| 86 | +Once the build completes, upload it to the Google Container registry: |
| 87 | + |
| 88 | +```bash |
| 89 | +gcloud docker -- push gcr.io/${PROJECT_ID}/slack-bot |
| 90 | +``` |
| 91 | + |
| 92 | + |
| 93 | +### Running the container |
| 94 | + |
| 95 | +First, create a Replication Controller configuration, populated with your Google |
| 96 | +Cloud Project ID, so that Kubernetes knows where to find the Docker image. |
| 97 | + |
| 98 | +```bash |
| 99 | +./generate-rc.sh $PROJECT_ID |
| 100 | +``` |
| 101 | + |
| 102 | +Now, tell Kubernetes to create the bot's replication controller. This will launch 1 pod replica running the bot. |
| 103 | + |
| 104 | +```bash |
| 105 | +kubectl create -f slack-bot-rc.yaml |
| 106 | +``` |
| 107 | + |
| 108 | +You can check the status of your bot with: |
| 109 | + |
| 110 | +```bash |
| 111 | +kubectl get pods |
| 112 | +``` |
| 113 | + |
| 114 | +Now your bot should be online. As a sanity check, check that it responds to a "Hello" message directed to it. |
| 115 | + |
| 116 | +Note: if you have forgotten to create the secret first, the pod won't come up successfully. |
| 117 | + |
| 118 | +## Running the bot locally |
| 119 | + |
| 120 | +If you want, you can run your slackbot locally instead. This is handy if |
| 121 | +you've made some changes and want to test them out before redeploying. To do |
| 122 | +this, first run: |
| 123 | + |
| 124 | +```bash |
| 125 | +npm install |
| 126 | +``` |
| 127 | + |
| 128 | +Then, set GCLOUD_PROJECT to your project id: |
| 129 | + |
| 130 | +```bash |
| 131 | +export GCLOUD_PROJECT=my-cloud-project-id |
| 132 | +``` |
| 133 | + |
| 134 | +Then, create a file containing your Slack token, and point 'SLACK_TOKEN_PATH' to that file when you run the script |
| 135 | +(substitute 'my-slack-token with your actual token): |
| 136 | + |
| 137 | + echo my-slack-token > slack-token |
| 138 | + SLACK_TOKEN_PATH=./slack-token node demo_bot.js |
| 139 | + |
| 140 | +## Using the Bot |
| 141 | + |
| 142 | +Once you've confirmed the bot is running, you can start putting it through its paces. |
| 143 | + |
| 144 | +### Sentiment Analysis |
| 145 | + |
| 146 | +The slackbot will give a 'thumbs up' or 'thumbs down' if it thinks a message is above a certain magnitude in positive or negative sentiment. |
| 147 | + |
| 148 | +E.g., try posting this message to the channel (you don't need to explicitly mention the bot in this message): |
| 149 | + |
| 150 | +``` |
| 151 | +I hate bananas. |
| 152 | +``` |
| 153 | + |
| 154 | +You should see that bot give a thumbs down in reply, indicatig that the NL API |
| 155 | +reported negative sentiment for this sentence. Next, try: |
| 156 | + |
| 157 | +``` |
| 158 | +I love coffee. |
| 159 | +``` |
| 160 | + |
| 161 | +This should generate a thumbs up. Posted text won't get a reply from the bot |
| 162 | +unless the magnitude of the sentiment is above a given threshold, 30 by |
| 163 | +default. E.g., with a neutral statement like `The temperature is seventy |
| 164 | +degrees.` the bot is unlikely to give a response. |
| 165 | + |
| 166 | +### Entity Analysis |
| 167 | + |
| 168 | +For every message posted to the channel, the bot-- behind the scenes-- is |
| 169 | +analyzing and storing information about the entities it detects. At any time |
| 170 | +you can query the bot to get the current N most frequent entities, where N is |
| 171 | +20 by default. It will be more interesting if you wait until a few messages |
| 172 | +have been posted to the channel, so that the bot has the chance to identify |
| 173 | +and log some entities. |
| 174 | + |
| 175 | +E.g., suppose your bot is called `nlpbot`. |
| 176 | +To see the top entities, send it this message: |
| 177 | + |
| 178 | +``` |
| 179 | +@nlpbot top entities |
| 180 | +``` |
| 181 | + |
| 182 | + |
| 183 | +## Shutting down |
| 184 | + |
| 185 | +To shutdown your bot, we tell Kubernetes to delete the replication controller. |
| 186 | + |
| 187 | +```bash |
| 188 | +kubectl delete -f slack-bot-rc.yaml |
| 189 | +``` |
| 190 | + |
| 191 | + |
| 192 | +## Cleanup |
| 193 | + |
| 194 | +If you have created a container cluster, you may still get charged for the |
| 195 | +Google Compute Engine resources it is using, even if they are idle. To delete |
| 196 | +the cluster, run: |
| 197 | + |
| 198 | +```bash |
| 199 | +gcloud container clusters delete slackbot-cluster |
| 200 | +``` |
| 201 | + |
| 202 | +(If you used a different name for your cluster, substitute that name for `slackbot-cluster`.) |
| 203 | +This deletes the Google Compute Engine instances that are running the cluster. |
| 204 | + |
0 commit comments