Merge pull request #26 from VersusControl/docs/update

(docs): add advanced template tips

Author: hoalongnatsu

README.md

@@ -14,11 +14,9 @@ An open-source incident management system with multi-channel alerting capabiliti
   - [Installation](#installation)
 - [Configuration](#configuration)
 - [Environment Variables](#environment-variables)
-- [Custom Alert Templates](#custom-alert-templates)
 - [Development](#development)
   - [Docker](#docker)
   - [Kubernetes](#kubernetes)
-- [API Usage](#api-usage)
 - [Advanced API Usage](#advanced-api-usage)
 - [SNS Usage](#sns-usage)
 - [Example](#example)
@@ -46,7 +44,7 @@ An open-source incident management system with multi-channel alerting capabiliti
 - Docker 20.10+ (optional)
 - Slack workspace (for Slack notifications)
 
-### Installation
+### Easy Installation with Docker
 
 ```bash
 docker run -p 3000:3000 \
@@ -56,7 +54,7 @@ docker run -p 3000:3000 \
   ghcr.io/versuscontrol/versus-incident
 ```
 
-### Build from source
+### Or Build from source
 
 ```bash
 # Clone the repository
@@ -78,17 +76,6 @@ export SLACK_CHANNEL_ID=your_channel
 ./versus-incident
 ```
 
-Or run with Docker:
-```
-docker build -t versus-incident .
-
-docker run -p 3000:3000 \
-  -e SLACK_ENABLE=true \
-  -e SLACK_TOKEN=your_token \
-  -e SLACK_CHANNEL_ID=your_channel \
-  versus-incident
-```
-
 ## Configuration
 
 A sample configuration file is located at `config/config.yaml`:
@@ -125,6 +112,7 @@ alert:
 
 queue:
   enable: true
+  debug_body: true
 
   # AWS SNS
   sns:
@@ -178,98 +166,147 @@ The application relies on several environment variables to configure alerting se
 
 Ensure these environment variables are properly set before running the application. You can configure them in your `.env` file, Docker environment variables, or Kubernetes secrets.
 
-## Custom Alert Templates
+## Development
 
-### Slack Template
-Create your Slack message template, for example `config/slack_message.tmpl`:
+### Docker
 
+#### Basic Deployment
+
+```bash
+docker run -d \
+  -p 3000:3000 \
+  -e SLACK_ENABLE=true \
+  -e SLACK_TOKEN=your_slack_token \
+  -e SLACK_CHANNEL_ID=your_channel_id \
+  --name versus \
+  ghcr.io/versuscontrol/versus-incident
 ```
-*Critical Error in {{.ServiceName}}*
-----------
-Error Details:
-{{.Logs}}
-----------
-Owner <@{{.UserID}}> please investigate
-```
-### Telegram Template
 
-For Telegram, you can use HTML formatting. Create your Telegram message template, for example `config/telegram_message.tmpl`:
+#### With Custom Templates
+
+Create a configuration file:
+
 ```
-🚨 <b>Critical Error Detected!</b> 🚨
-📌 <b>Service:</b> {{.ServiceName}}
-⚠️ <b>Error Details:</b>
-{{.Logs}}
+mkdir -p ./config && touch config.yaml
 ```
-This template will be parsed with HTML tags when sending the alert to Telegram.
 
-### Email Template
-Create your email message template, for example `config/email_message.tmpl`:
+`config.yaml`:
+```yaml
+name: versus
+host: 0.0.0.0
+port: 3000
+
+alert:
+  slack:
+    enable: true
+    token: ${SLACK_TOKEN}
+    channel_id: ${SLACK_CHANNEL_ID}
+    template_path: "/app/config/slack_message.tmpl"
 
+  telegram:
+    enable: false
 ```
-Subject: Critical Error Alert - {{.ServiceName}}
 
-Critical Error Detected in {{.ServiceName}}
-----------------------------------------
+**Configuration Notes**
 
-Error Details:
-{{.Logs}}
+Ensure `template_path` in `config.yaml` matches container path:
+```yaml
+alert:
+  slack:
+    template_path: "/app/config/slack_message.tmpl" # For containerized env
+```
 
-Please investigate this issue immediately.
+**Slack Template**
+
+Create your Slack message template, for example `config/slack_message.tmpl`:
 
-Best regards,
-Versus Incident Management System
 ```
-This template supports both plain text and HTML formatting for email notifications.
+🔥 *Critical Error in {{.ServiceName}}*
 
-## Development
+❌ Error Details:
+```{{.Logs}}```
 
-### Docker
+Owner <@{{.UserID}}> please investigate
+```
+
+**Run with volume mount:**
 
-#### Basic Deployment
 ```bash
 docker run -d \
   -p 3000:3000 \
+  -v $(pwd)/config:/app/config \
   -e SLACK_ENABLE=true \
   -e SLACK_TOKEN=your_slack_token \
   -e SLACK_CHANNEL_ID=your_channel_id \
   --name versus \
   ghcr.io/versuscontrol/versus-incident
 ```
 
-#### With Custom Templates
+Verify template mounting:
 
-**Configuration Notes**
-- Ensure `template_path` in config.yaml matches container path:
-  ```yaml
-  alert:
-    slack:
-      template_path: "/app/config/slack_message.tmpl" # For containerized env
-  ```
-- File permissions: Templates must be readable by the app user (UID 1000 in Dockerfile)
-
-1. Create local config directory with your templates:
 ```bash
-mkdir -p ./config
-cp your-custom-template.tmpl ./config/slack_message.tmpl
+docker exec versus ls -l /app/config
 ```
 
-2. Run with volume mount:
+To test, simply send an incident to Versus:
+
 ```bash
-docker run -d \
-  -p 3000:3000 \
-  -v $(pwd)/config:/app/config \
-  -e SLACK_ENABLE=true \
-  -e SLACK_TOKEN=your_slack_token \
-  -e SLACK_CHANNEL_ID=your_channel_id \
-  --name versus \
-  ghcr.io/versuscontrol/versus-incident
+curl -X POST http://localhost:3000/api/incidents \
+  -H "Content-Type: application/json" \
+  -d '{
+    "Logs": "[ERROR] This is an error log from User Service that we can obtain using Fluent Bit.",
+    "ServiceName": "order-service",
+    "UserID": "SLACK_USER_ID"
+  }'
 ```
 
-3. Verify template mounting:
-```bash
-docker exec versus ls -l /app/config
+Response:
+
+```json
+{
+    "status":"Incident created"
+}
+```
+
+**Result:**
+
+![Slack Alert](src/docs/images/versus-result.png)
+
+#### Other Templates
+
+**Telegram Template**
+
+For Telegram, you can use HTML formatting. Create your Telegram message template, for example `config/telegram_message.tmpl`:
+```
+🚨 <b>Critical Error Detected!</b> 🚨
+📌 <b>Service:</b> {{.ServiceName}}
+⚠️ <b>Error Details:</b>
+{{.Logs}}
 ```
 
+This template will be parsed with HTML tags when sending the alert to Telegram.
+
+**Email Template**
+
+Create your email message template, for example `config/email_message.tmpl`:
+
+```
+Subject: Critical Error Alert - {{.ServiceName}}
+
+Critical Error Detected in {{.ServiceName}}
+----------------------------------------
+
+Error Details:
+{{.Logs}}
+
+Please investigate this issue immediately.
+
+Best regards,
+Versus Incident Management System
+```
+
+This template supports both plain text and HTML formatting for email notifications.
+
 ### Kubernetes
 
 1. Create a secret for Slack:
@@ -380,7 +417,7 @@ spec:
       targetPort: 3000
 ```
 
-4. Apply changes:
+4. Apply:
 ```bash
 kubectl apply -f versus-deployment.yaml
 ```
@@ -390,27 +427,6 @@ kubectl apply -f versus-deployment.yaml
 kubectl exec -it <pod-name> -- ls -l /app/config
 ```
 
-## API Usage
-
-Create an incident:
-
-```bash
-curl -X POST http://localhost:3000/api/incidents \
-  -H "Content-Type: application/json" \
-  -d '{
-    "Logs": "[ERROR] This is an error log from User Service that we can obtain using Fluent Bit.",
-    "ServiceName": "order-service",
-    "UserID": "SLACK_USER_ID"
-  }'
-```
-
-**Response:**
-```json
-{
-    "status":"Incident created"
-}
-```
-
 ## Advanced API Usage
 We provide a way to overwrite configuration values using query parameters, allowing you to send alerts to different channel IDs based on the service.
 

src/advanced-template-tips.md

@@ -17,6 +17,24 @@ Handle multiple alerts in one template:
 🔗 *Details*: {{.detail | toJson}}
 ```
 
+If the field does not exist when passed to the template, let's use the template's `printf` function to handle it.
+
+```
+{{ if contains (printf "%v" .source) "aws.glue" }}
+🔥 *Glue Job Failed*: {{.detail.jobName}}
+
+❌ Error: 
+```{{.detail.errorMessage}}```
+{{ else }}
+🔥 *Critical Error in {{.ServiceName}}*
+
+❌ Error Details:
+```{{.Logs}}```
+
+Owner <@{{.UserID}}> please investigate
+{{ end }}
+```
+
 ### Conditional Formatting
 
 Highlight critical issues: