Skip to content

Commit 270eb34

Browse files
AllenAnthesAllenAnthes
authored
Merge pull request #125 from Jitsusama/document-test-deployment
Document Slack Integration Procedure for Developers
2 parents 04966bf + 61cf38b commit 270eb34

1 file changed

Lines changed: 170 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,176 @@ poetry run flake8
5050
poetry run isort -rc .
5151
```
5252

53+
## How to Test Integration With Slack
54+
55+
After having developed some new feature, or having in hand what you believe is
56+
a fix for an existing bug, how do you test it out in a real system in order to
57+
make sure that your changes do all that you hope they do? The answer; bring up
58+
the application in your own environment and hook it up to Slack!
59+
60+
In order to do this, you'll want to tackle the following items in order:
61+
62+
1. Setup your own Slack workspace.
63+
2. Grab a signing secret from Slack that pybot can utilize.
64+
3. Launch pybot locally, passing it your Slack signing secret.
65+
4. Attach your pybot instance to the public internet so that Slack can speak
66+
with it.
67+
5. Point Slack at your running pybot instance, and properly configure it.
68+
69+
The following sections will guide you through each of these stages.
70+
71+
### 1 - Setup Your Own Slack Workspace
72+
73+
To start, you'll want to visit Slack's [Getting
74+
Started](https://slack.com/get-started) page. From this page, follow the steps
75+
required to create a new workspace. The names/options you configure during
76+
creation don't matter so much, but make sure you associate it with an email
77+
address you have access to. Once complete it should present you with an option
78+
to login to the new workspace, make sure you go ahead and do that.
79+
80+
If you're having a hard time figuring this out, try checking out the following
81+
Slack article [Create a Slack Workspace](https://slack.com/intl/en-ca/help/articles/206845317-Create-a-Slack-workspace).
82+
83+
### 2 - Create a pybot App in Your Slack Workspace
84+
85+
The next step is to create a new bot application in your workspace. While still
86+
logged in, visit the [App Management](https://api.slack.com/apps) page and
87+
choose to create a new app. During this process, make sure to copy down the
88+
signing secret key that gets generated for your app, as you'll need it later,
89+
following this, follow the guidelines for creating a bot app as laid out in the
90+
[Enabling interactions with bots](https://api.slack.com/bot-users) article. When
91+
you get to the stage of creating the bot user, make sure to write down the bot
92+
user OAuth access token that is presented, as you'll need to use it later.
93+
94+
### 3 - Launch pybot Locally, Passing in Your Signing Secret
95+
96+
With your Slack workspace, app and bot user created, and your app signing secret
97+
and bot user OAuth access token in hand, you should now be ready to configure
98+
pybot to integrate with your new Slack workspace. To do this, you'll first want
99+
to setup the proper configuration in pybot.
100+
101+
pybot configuration is specified completely through environment variables. When
102+
running locally, you can configure the _./docker/pybot.env_ file with the
103+
environment variable name/value pairings, which will get evaluated on
104+
application start. Otherwise, make sure to export or pass in the correct
105+
environment variables through your shell when launching pybot.
106+
107+
Here's an example of configuring these through the _pybot.env_ file:
108+
109+
```bash
110+
SLACK_BOT_SIGNING_SECRET=APP-SIGNING-SECRET
111+
BOT_OATH_TOKEN=BOT-USER-OAUTH-TOKEN
112+
```
113+
114+
**NOTE**: More configuration settings than these may be specified. Please see
115+
the _Known Configuration Settings_ section near the bottom of this document
116+
for details on other settings that can be set.
117+
118+
### 4 - Attach Your pybot Instance to the Public Internet
119+
120+
With an instance of pybot running, you now need to expose this instance to the
121+
public internet so Slack can send in API requests. You can easily utilize serveo
122+
for this purpose if you wish. To do so; run the following command from your UNIX
123+
like workstation to setup an SSH port tunnel to serveo:
124+
125+
```bash
126+
ssh -R 80:localhost:5000 serveo.net
127+
```
128+
129+
Pay attention to copy out the response you get and keep this command running.
130+
Here's an example output from the command:
131+
132+
```text
133+
Forwarding HTTP traffic from https://supersecret.serveo.net
134+
Press g to start a GUI session and ctrl-c to quit.
135+
```
136+
137+
With this done, serveo will now expose the instance of pybot running locally
138+
on port 5000 on port 443 via the Base-URI it returns.
139+
140+
### 5 - Point Slack at Your Running pybot Instance
141+
142+
With the initial Slack configuration complete and your instance of pybot
143+
running on the public internet, it is now the perfect time to fully configure
144+
Slack to interact with your bot. Depending on the interactions you're wanting to
145+
play with, there are various configurations you can specify, which can be
146+
broken down into the following parts:
147+
148+
* Event Subscriptions - this allows pybot to respond to various events that may
149+
occur in your Slack workspace.
150+
* Slash Commands - this allows a user to invoke various commands from any
151+
channel in your workspace to interact with pybot.
152+
* Interactive Components - this allows various options to be exposed when
153+
right clicking on a message, or, when the bot presents various user
154+
elements that can be interacted with, instructs Slack on where to send the
155+
results for such interactions.
156+
157+
High level steps for configuring each of these can be found in the following
158+
sub-sections; note that you don't need to necessarily configure all of these,
159+
it all depends on what areas of pybot you're wanting to play with.
160+
161+
#### Event Subscriptions
162+
163+
You can follow the instructions (and read helpful related information) on the
164+
[Events API](https://api.slack.com/events-api) page on Slack to setup event
165+
subscriptions. When configuring your events URI; make sure you pass in the
166+
Base-URI that pybot is listening on followed by the text _/slack/events_. For
167+
example:
168+
169+
https://supersecret.serveo.net/slack/events
170+
171+
#### Slash Commands
172+
173+
You can follow the instructions (and read helpful relation information) on the
174+
[Enabling interactivity with Slash Commands](https://api.slack.com/interactivity/slash-commands)
175+
page on Slack to setup pybot slash commands. When configuring a Slash command,
176+
make sure you configure the request URL to match the Base-URI that pybot is
177+
listening on followed by the text _/slack/commands_. For example:
178+
179+
https://supersecret.serveo.net/slack/commands
180+
181+
You'll use the same URI for each command. Here's a table listing of currently
182+
supported commands along with some suggested configuration text:
183+
184+
Command | Description | Usage Hint
185+
------- | ----------- | ----------
186+
/lunch | find lunch suggestions nearby | <zip code> <distance in miles>
187+
/mentor | request mentoring |
188+
/mentor-volunteer | offer to mentor others |
189+
/repeat | parrot canned messages | <10000|ask|ldap|merge|firstpr|channels|resources>
190+
/report | report something to the admins | <text of message>
191+
/roll | roll x dice with y sides | <XdY>
192+
/ticket | submit ticket to admins | (text of ticket)
193+
194+
#### Interactive Components
195+
196+
You can follow the instructions (and read helpful related information) on the
197+
[Handling user interaction in your Slack apps](https://api.slack.com/interactivity/handling)
198+
page on Slack to setup Slack interactive component configuration. When
199+
configuring the request URL, you'll want to set it to the Base-URI that pybot
200+
is listening on followed by the text _/slack/actions_. For example:
201+
202+
https://supersecret.serveo.net/slack/actions
203+
204+
You'll also want to make sure to configure the report message action with the
205+
following parameters:
206+
207+
Name | Description | Callback ID
208+
---- | ----------- | -----------
209+
Report Message | Report this message to admins | report_message
210+
211+
## Known Configuration Settings
212+
213+
This application has a number of environment variables that can be set when
214+
launching to alter the behaviour of the application. The list below is an
215+
incomplete description of a number of them. Please feel free to update this
216+
list with more details via a PR:
217+
218+
Name | Description | Example
219+
---- | ----------- | -------
220+
SLACK_BOT_SIGNING_SECRET | The unique signing secret used by Slack for a specific app that will be validated by pybot when inspecting an inbound API request | f3b4d774b79e0fb55af624c3f376d5b4
221+
BOT_OATH_TOKEN | The bot user specific OAuth token used to authenticate the bot when making API requests to Slack | xoxb-800506043194-810119867738-vRvgSc3rslDUgQakFbMy3wAt
222+
MENTOR_CHANNEL | Slack unique identifier (not the same as the channel name) for a workspace channel that mentors should be added to | G1DRT62UC
53223

54224
## License
55225
This package is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

0 commit comments

Comments
 (0)