centralcloud/oncall-engine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Slack polishing & docs

Browse source
This commit is contained in:
Matvey Kukuy 2022-06-13 15:33:56 +03:00
parent c6ba0d1073
commit 34e94ce823
7 changed files with 42 additions and 210 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
DEVELOPER.md
View file

@ -124,161 +124,7 @@ extra_hosts:
### Slack application setup
This instruction is also applicable if you set up self-hosted OnCall.
1. Start a [localtunnel](https://github.com/localtunnel/localtunnel) reverse proxy to make oncall engine api accessible to slack (if you don't have OnCall backend accessible from https),
```bash
# Choose the unique prefix instead of pretty-turkey-83
# Localtunnel will generate an url, e.g. https://pretty-turkey-83.loca.lt
# it is referred as <ONCALL_ENGINE_PUBLIC_URL> below
lt --port 8000 -s pretty-turkey-83 --print-requests
```
2. [Create a Slack Workspace](https://slack.com/create) for development.
3. Go to https://api.slack.com/apps and click Create New App button
4. Select `From an app manifest` option and choose the right workspace
5. Copy and paste the following block with the correct <YOUR_BOT_NAME> and <ONCALL_ENGINE_PUBLIC_URL> fields
<details>
<summary>Click to expand!</summary>
```yaml
_metadata:
major_version: 1
minor_version: 1
display_information:
name: <YOUR_BOT_NAME>
features:
app_home:
home_tab_enabled: true
messages_tab_enabled: true
messages_tab_read_only_enabled: false
bot_user:
display_name: <YOUR_BOT_NAME>
always_online: true
shortcuts:
- name: Create a new incident
type: message
callback_id: incident_create
description: Creates a new OnCall incident
- name: Add to postmortem
type: message
callback_id: add_postmortem
description: Add this message to postmortem
slash_commands:
- command: /oncall
url: <ONCALL_ENGINE_PUBLIC_URL>/slack/interactive_api_endpoint/
description: oncall
should_escape: false
oauth_config:
redirect_urls:
- <ONCALL_ENGINE_PUBLIC_URL>/api/internal/v1/complete/slack-install-free/
- <ONCALL_ENGINE_PUBLIC_URL>/api/internal/v1/complete/slack-login/
scopes:
user:
- channels:read
- chat:write
- identify
- users.profile:read
bot:
- app_mentions:read
- channels:history
- channels:read
- chat:write
- chat:write.customize
- chat:write.public
- commands
- files:write
- groups:history
- groups:read
- im:history
- im:read
- im:write
- mpim:history
- mpim:read
- mpim:write
- reactions:write
- team:read
- usergroups:read
- usergroups:write
- users.profile:read
- users:read
- users:read.email
- users:write
settings:
event_subscriptions:
request_url: <ONCALL_ENGINE_PUBLIC_URL>/slack/event_api_endpoint/
bot_events:
- app_home_opened
- app_mention
- channel_archive
- channel_created
- channel_deleted
- channel_rename
- channel_unarchive
- member_joined_channel
- message.channels
- message.im
- subteam_created
- subteam_members_changed
- subteam_updated
- user_change
interactivity:
is_enabled: true
request_url: <ONCALL_ENGINE_PUBLIC_URL>/slack/interactive_api_endpoint/
org_deploy_enabled: false
socket_mode_enabled: false
```
</details>
6. Click `Install to workspace` button to generate the credentials
6. Populate the environment with variables related to Slack
In your `.env` file, fill out the following variables:
```
SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID
SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret
SLACK_API_TOKEN = OAuth & Permissions -> Bot User OAuth Token
SLACK_INSTALL_RETURN_REDIRECT_HOST = https://pretty-turkey-83.loca.lt
```
Don't forget to export variables from the `.env` file and restart the server!
7. Edit `grafana-plugin/grafana-plugin.yml` to set `onCallApiUrl` fields with localtunnel url
```
onCallApiUrl: https://pretty-turkey-83.loca.lt
```
or set BASE_URL Env variable through web interface.
8. Edit grafana-plugin/src/plugin.json to add `Bypass-Tunnel-Reminder` header section for all existing routes
> this headers required for the local development only, otherwise localtunnel blocks requests from grafana plugin, An alternative to this is you can modify your user-agent in your browser to bypass the tunnel warning, it only filters the common browsers.
```
{
"path": ...,
...
"headers": [
...
{
"name": "Bypass-Tunnel-Reminder",
"content": "True"
}
]
},
```
9. Rebuild the plugin
```
yarn watch
```
10. Restart grafana instance
11. All set! Go to Slack and check if your application is functional.
For Slack app configuration check our docs: https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup
## Troubleshooting

2
README.md
View file

@ -11,7 +11,7 @@ Developer-friendly, incident response with brilliant Slack integration.
## Getting Started
We prepared multiple environments: [production](PRODUCTION.md), [developer](DEVELOPER.md) and hobby:
We prepared multiple environments: [production](https://grafana.com/docs/grafana-cloud/oncall/open-source/#production-environment), [developer](DEVELOPER.md) and hobby:
1. Download docker-compose.yaml:
```bash

2
docs/sources/getting-started.md
View file

@ -17,7 +17,7 @@ These procedures introduce you to the configuration of user settings, how to set
## Before you begin
You must have a Grafana Cloud account.
You must have a [Grafana Cloud](https://grafana.com/products/cloud/) account or [Open Source Grafana OnCall]({{< relref " open-source.md" >}})
Each supported integration and the associated monitoring system has a slightly different configuration method. These methods will not be explained in this guide, however, you can follow the online instructions provided when adding an integration.

59
docs/sources/open-source.md
View file

@ -13,11 +13,15 @@ weight: 100
We prepared three environments for OSS users:
- **Hobby** environment for local usage & playing around: [README.md](https://github.com/grafana/oncall#getting-started).
- **Development** environment for contributors: [DEVELOPER.md](https://github.com/grafana/oncall/blob/dev/DEVELOPER.md)
- **Production** environment for reliable cloud installation using Helm: #production
- **Production** environment for reliable cloud installation using Helm: [Production Environment](#production-environment)
## Production Environment
TBD
## Slack Setup
Grafana OnCall Slack integration use most of the features Slack API provides.
Grafana OnCall Slack integration use a lot of Slack API features:
- Subscription on Slack events requires OnCall to be externally available and provide https endpoint.
- You will need to register new Slack App.
@ -31,16 +35,15 @@ Grafana OnCall Slack integration use most of the features Slack API provides.
lt --port 8000 -s pretty-turkey-83 --print-requests
```
2. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace.
3. If you use localtunnel, open your external URL and click "Continue" to allow requests to bypass the warning page.
3. Go to https://api.slack.com/apps and click Create New App button
4. [Create a Slack Workspace](https://slack.com/create) for development, or use your company workspace.
4. Select `From an app manifest` option and choose the right workspace
5. Go to https://api.slack.com/apps and click Create New App button
5. Copy and paste the following block with the correct <YOUR_BOT_NAME> and <ONCALL_ENGINE_PUBLIC_URL> fields
6. Select `From an app manifest` option and choose the right workspace
<details>
<summary>Click to expand!</summary>
7. Copy and paste the following block with the correct <YOUR_BOT_NAME> and <ONCALL_ENGINE_PUBLIC_URL> fields
```yaml
_metadata:
@ -129,46 +132,16 @@ lt --port 8000 -s pretty-turkey-83 --print-requests
org_deploy_enabled: false
socket_mode_enabled: false
```
</details>
6. Click `Install to workspace` button to generate the credentials
7. Populate the environment with variables related to Slack.
Go to your OnCall plugin -> Env Variables and set:
6. Go to your "OnCall" -> "Env Variables" and set:
```
SLACK_CLIENT_OAUTH_ID = Basic Information -> App Credentials -> Client ID
SLACK_CLIENT_OAUTH_SECRET = Basic Information -> App Credentials -> Client Secret
SLACK_API_TOKEN = OAuth & Permissions -> Bot User OAuth Token
SLACK_INSTALL_RETURN_REDIRECT_HOST = https://pretty-turkey-83.loca.lt
SLACK_SIGNING_SECRET = Basic Information -> App Credentials -> Signing Secret
SLACK_INSTALL_RETURN_REDIRECT_HOST = << OnCall external URL >>
```
8. Set BASE_URL Env variable through web interface or edit `grafana-plugin/grafana-plugin.yml` to set `onCallApiUrl` fields with publicly available url:
```
onCallApiUrl: https://pretty-turkey-83.loca.lt
```
7. Go to "OnCall" -> "ChatOps" -> "Slack" and install Slack Integration
9. For dev environment only: Edit grafana-plugin/src/plugin.json to add `Bypass-Tunnel-Reminder` header section for all existing routes
> this headers required for the local development only, otherwise localtunnel blocks requests from grafana plugin
```
{
"path": ...,
...
"headers": [
...
{
"name": "Bypass-Tunnel-Reminder",
"content": "True"
}
]
},
```
10. Rebuild the plugin
```
yarn watch
```
11. Restart grafana instance
12. All set! Go to Slack and check if your application is functional.
8. All set!

26
engine/apps/base/models/live_setting.py
View file

@ -41,6 +41,7 @@ class LiveSetting(models.Model):
"SLACK_CLIENT_OAUTH_ID",
"SLACK_CLIENT_OAUTH_SECRET",
"SLACK_SIGNING_SECRET",
"SLACK_INSTALL_RETURN_REDIRECT_HOST",
"SEND_ANONYMOUS_USAGE_STATS",
"GRAFANA_CLOUD_ONCALL_TOKEN",
"GRAFANA_CLOUD_ONCALL_HEARTBEAT_ENABLED",
@ -50,24 +51,31 @@ class LiveSetting(models.Model):
DESCRIPTIONS = {
"SLACK_SIGNING_SECRET": (
"Check <a href='"
"https://github.com/grafana/amixr/blob/main/DEVELOPER.md#slack-application-setup"
"'>this instruction</a> for details how to set up Slack. "
"https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup"
"'>instruction</a> for details how to set up Slack. "
"Slack secrets can't be verified on the backend, please try installing the Slack Bot "
"after you update Slack credentials."
"after you update them."
),
"SLACK_CLIENT_OAUTH_SECRET": (
"Check <a href='"
"https://github.com/grafana/amixr/blob/main/DEVELOPER.md#slack-application-setup"
"'>this instruction</a> for details how to set up Slack. "
"https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup"
"'>instruction</a> for details how to set up Slack. "
"Slack secrets can't be verified on the backend, please try installing the Slack Bot "
"after you update Slack credentials."
"after you update them."
),
"SLACK_CLIENT_OAUTH_ID": (
"Check <a href='"
"https://github.com/grafana/amixr/blob/main/DEVELOPER.md#slack-application-setup"
"'>this instruction</a> for details how to set up Slack. "
"https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup"
"'>instruction</a> for details how to set up Slack. "
"Slack secrets can't be verified on the backend, please try installing the Slack Bot "
"after you update Slack credentials."
"after you update them."
),
"SLACK_INSTALL_RETURN_REDIRECT_HOST": (
"Check <a href='"
"https://grafana.com/docs/grafana-cloud/oncall/open-source/#slack-setup"
"'>instruction</a> for details how to set up Slack. "
"Slack secrets can't be verified on the backend, please try installing the Slack Bot "
"after you update them."
),
"TWILIO_ACCOUNT_SID": (
"Twilio username to allow amixr send sms and make phone calls, "

3
engine/apps/slack/views.py
View file

@ -119,6 +119,9 @@ class SlackEventApiEndpointView(APIView):
return Response(status=403)
if not settings.DEBUG:
if live_settings.SLACK_SIGNING_SECRET is None and settings.SLACK_SIGNING_SECRET_LIVE:
raise Exception("Please specify SLACK_SIGNING_SECRET or use DEBUG.")
if not (
SlackEventApiEndpointView.verify_signature(
slack_request_timestamp, slack_signature, body, live_settings.SLACK_SIGNING_SECRET

4
engine/apps/social_auth/live_setting_django_strategy.py
View file

@ -34,8 +34,10 @@ class LiveSettingDjangoStrategy(DjangoStrategy):
def build_absolute_uri(self, path=None):
"""
Overriden DjangoStrategy's method to substitute and force the host value from ENV
Overridden DjangoStrategy's method to substitute and force the host value from ENV
"""
if live_settings.SLACK_INSTALL_RETURN_REDIRECT_HOST is not None and path is not None:
return live_settings.SLACK_INSTALL_RETURN_REDIRECT_HOST + path
if settings.SLACK_INSTALL_RETURN_REDIRECT_HOST is not None and path is not None:
return settings.SLACK_INSTALL_RETURN_REDIRECT_HOST + path
if self.request: