Skip to content

Commit 58b738e

Browse files
handotdevhandotdev
authored
Add initial setup (#1)
1 parent df9f963 commit 58b738e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

68 files changed

+2545
-1
lines changed

‎README.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,17 @@
1-
# keep-docs
1+
# Keep Documentation
2+
3+
The content and configuration powering the documentation available at []()
4+
5+
### 👩‍💻 Development
6+
7+
Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command
8+
9+
```
10+
npm i mintlify -g
11+
```
12+
13+
Run the following command at the root of your documentation (where mint.json is)
14+
15+
```
16+
mintlify dev
17+
```

‎applications/github.mdx

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
title: "GitHub Application"
3+
sidebarTitle: "GitHub"
4+
description: "The Keep GitHub Application is a powerful tool that enhances your workflow by monitoring file changes under the parent `.keep/` directory in your repositories' pull requests. It automates the process of generating AI-generated alerts from plain English and allows you to seamlessly deploy these alerts to your provider using comments."
5+
---
6+
7+
## Getting Started
8+
9+
To start using the Keep GitHub Application, follow these simple steps:
10+
11+
1. Sign up and log in to the **[Keep's platform](https://platform.keephq.dev)**.
12+
2. Install the **Keep GitHub Application** either through the onboarding screen or by visiting **[this link](https://github.com/apps/keephq)**. The installation process is straightforward and user-friendly.
13+
14+
<Frame>
15+
<img src="/images/github-app-install.png" />
16+
</Frame>
17+
18+
3. Connect your preferred provider, such as Datadog, by linking it to Keep's platform. This step allows Keep to seamlessly generate and deploy alerts to your chosen provider.
19+
20+
<Frame>
21+
<img src="/images/connect-provider.png" />
22+
</Frame>
23+
24+
4. You are now ready to go! The Keep GitHub Application is successfully integrated into your GitHub workflow.
25+
26+
## How does it work?
27+
28+
The Keep GitHub Application operates seamlessly in the background, ensuring that you stay informed about relevant changes in your repositories. Whenever a pull request is opened or updated, the application monitors the files under the .keep/ directory.
29+
30+
Once a change is detected, the GitHub application sends an HTTP request to Keep's API smart AI layer. The AI layer analyzes the content of the changed files and together with context from the provider (existing alerts, sample logs, etc.) generates an alert based on the user provided plain English description. The AI-powered alert generation ensures accuracy and relevance.
31+
32+
After the alert is generated, the Keep GitHub Application automatically comments the alert on the respective file within the pull request. This allows you, as the user, to conveniently review and verify the generated alert.
33+
34+
If the generated alert meets your requirements and is ready to be deployed, you can simply leave a comment on the file. The comment should include one of the predefined emojis, such as 🚀 or 🆗 (refer to the ["Deploying Alerts with Emojis"](#deploying-alerts-with-emojis) section). The Keep GitHub Application recognizes these emojis as commands to proceed with the deployment process.
35+
36+
This intuitive workflow streamlines the alert generation and deployment process, providing you with a seamless experience and allowing you to focus on the core aspects of your project.
37+
38+
## Monitoring Files Under .keep/ Directory
39+
40+
The Keep GitHub Application actively monitors the files residing within the `.keep/` directory located at the parent level of your repository. Any changes or updates made to these files will trigger the alert generation process. This allows you to focus on the essential aspects of your project while ensuring that relevant changes are promptly identified and acted upon.
41+
42+
## Alert File Structure
43+
44+
Each file under the `.keep/` directory represents a single alert. The structure of an alert file follows the YAML format. Below is an example of an alert file:
45+
46+
```yaml title=alert-example.yaml
47+
# The alert text in plain English
48+
alert: |
49+
Count the error rate (4xx-5xx) this service has in the last 10 minutes.
50+
Alert when the threshold is above 5% out of total requests.
51+
Send a Slack message to the #alerts-playground channel and include all the context you have"
52+
53+
# The provider you've previously connected and want this alert to be generated for
54+
provider: datadog
55+
# You can use this to override Keep's managed API and have the GitHub application
56+
# use the API that you run locally (using the NGROK URL)
57+
# api_url: https://OVERRIDE-KEEP-MANAGED-API
58+
```
59+
60+
The alert file consists of the following components:
61+
62+
1. **Alert Text**: This section contains the plain English description of the alert. Write a clear and concise explanation of the conditions or criteria that should trigger the alert. You can include any relevant context to facilitate understanding and resolution.
63+
64+
2. **Provider**: Specify the provider to which you want the alert to be generated. This ensures that the alert seamlessly integrates with your existing monitoring and notification infrastructure. In the example above, the alert is configured to be generated for Datadog.
65+
66+
3. **API Override**: Optionally, you can include the api_url field to override Keep's managed API. This allows you to use your locally hosted API for advanced customization and integration purposes.
67+
68+
<Accordion title="ngrok">
69+
**ngrok?**
70+
71+
Imagine you have a secret hideout in your backyard, but you don't want anyone to know where it is. So, you build a tunnel from your hideout to a tree in your friend's backyard. This way, you can go into the tunnel in your yard and magically come out at the tree in your friend's yard.
72+
73+
Now, let's say you have a cool website or a game that you want to show your friend, but it's running on your computer at home. Your friend is far away and can't come to your house. So, you need a way to show them your website or game over the internet.
74+
75+
This is where ngrok comes in! Ngrok is like a magical tunnel, just like the one you built in your backyard. It creates a secure connection between your computer and the internet. It gives your computer a special address that people can use to reach your website or game, even though it's on your computer at home.
76+
77+
When you start ngrok, it opens up a tunnel between your computer and the internet. It assigns a special address to your computer, like a secret door to your website or game. When your friend enters that address in their web browser, it's as if they're walking through the tunnel and reaching your website or game on your computer.
78+
79+
So, ngrok is like a magical tunnel that helps you share your website or game with others over the internet, just like the secret tunnel you built to reach your friend's backyard!
80+
81+
**How to start Keep with ngrok**
82+
83+
ngrok is Controlled with the `USE_NGROK` environment variable.<br />
84+
Simply run Keep's API using the following command to start with ngrok: `USE_NGROK=true keep api`
85+
86+
{" "}
87+
<Note>
88+
`USE_NGROK` is enabled by default when running with `docker-compose`
89+
</Note>
90+
91+
**How to obtain ngrok URL?**
92+
93+
When `USE_NGROK` is set, Keep will start with ngrok in the background. <br />
94+
You can find your private ngrok URL looking for this log line "`ngrok tunnel`":
95+
96+
```json
97+
{
98+
"asctime": "0000-00-00 00:00:00,000",
99+
"message": "ngrok tunnel: https://fab5-213-57-123-130.ngrok.io",
100+
...
101+
}
102+
```
103+
104+
The URL (https://fab5-213-57-123-130.ngrok.io in the example above) is a publicly accessible URL to your Keep API service running locally. <br />
105+
106+
{" "}
107+
<Note>
108+
You can check that the ngrok tunnel is working properly by sending a simple
109+
HTTP GET request to `/healthcheck` Try: `curl -v
110+
https://fab5-213-57-123-130.ngrok.io/healthcheck` in our example.
111+
</Note>
112+
113+
</Accordion>
114+
115+
## Deploying Alerts with Emojis
116+
117+
To deploy an alert to the specified provider, you can simply leave a comment on the respective file using the 🚀 or 🆗 emojis. The Keep GitHub Application recognizes these emojis as commands and will initiate the deployment process accordingly. This streamlined approach ensures a smooth and intuitive experience when deploying alerts.
118+
119+
For example, by leaving a comment with the 🚀 emoji, you can signal the Keep GitHub Application to deploy the alert to the specified provider (Datadog in our example above).
120+
121+
<Frame>
122+
<img src="/images/first-alert.yaml.png" />
123+
</Frame>
124+
125+
The Keep GitHub Application will either mark the comment with 👍 meaning the alert was successfully deployed or 👎 and another comment with the failure reason in case the alert was not deployed.
126+
127+
<Info>
128+
Keep GitHub Application has a retry mechanism that automatically tries to fix
129+
the alert in case it was not successfully deployed to the provider. If the
130+
alert that is deployed is different from the originally generated one, Keep
131+
Github Application will comment the updated one once again.
132+
</Info>

‎deployment.mdx

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: "Deployment"
3+
sidebarTitle: "Overview"
4+
description: "After writing some alerts with Keep, you may now want to use Keep in production! For that, you can easily deploy Keep on an environment other than your local station."
5+
---
6+
7+
Keep currently supports [Docker](#docker) and [Render](#render).
8+
9+
<Warning>
10+
Want to deploy Keep on a specific platform that is not yet supported? [Just
11+
open an
12+
issue](https://github.com/keephq/keep/issues/new?assignees=&labels=&template=feature_request.md&title=feature:%20new%20deployment%20option)
13+
and we will get to it ASAP!
14+
</Warning>
15+
16+
## E2E
17+
18+
### Docker
19+
20+
## CLI
21+
22+
Run _Keep_ alerting engine (The CLI)
23+
24+
### Docker
25+
26+
Configure the Slack provider (See "[Run locally](https://github.com/keephq/keep#get-a-slack-incoming-webhook-using-this-tutorial-and-use-keep-to-configure-it)" on how to obtain the webhook URL)
27+
28+
```bash
29+
docker run -v ${PWD}:/app -it keephq/cli config provider --provider-type slack --provider-id slack-demo
30+
```
31+
32+
You should now have a providers.yaml file created locally
33+
34+
Run Keep and execute our example "Paper DB has insufficient disk space" alert
35+
36+
```bash
37+
docker run -v ${PWD}:/app -it keephq/cli -j run --alert-url https://raw.githubusercontent.com/keephq/keep/main/examples/alerts/db_disk_space.yml
38+
```
39+
40+
### Render
41+
42+
Click the Deploy to Render button to deploy Keep as a background worker running in [Render](https://www.render.com)
43+
44+
[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/keephq/keep)
45+
46+
To run Keep and execute our example "Paper DB has insufficient disk space" alert, you will need to configure you Slack provider.
47+
When clicking the Deploy to Render button, you will be asked to provide the `KEEP_PROVIDER_SLACK_DEMO` environment variable, this is the expected format:
48+
49+
```json
50+
{ "authentication": { "webhook_url": "https://hooks.slack.com/services/..." } }
51+
```
52+
53+
\*\* `KEEP_PROVIDER_PROVIDER_ID` is the way you can configure providers using environment variables <br/>
54+
\*\* Refer to [Run locally](https://github.com/keephq/keep#get-a-slack-incoming-webhook-using-this-tutorial-and-use-keep-to-configure-it) on how to obtain a Slack webhook URL or on how to obtain Keep's webhook.

0 commit comments

Comments
 (0)