Iris - Alert Notification System

Iris is a comprehensive alert management and notification system designed to receive alerts from monitoring systems like Grafana and AlertManager, and dispatch notifications through multiple channels including SMS and email.

Features

Alert Management: Receive, store, and manage alerts from AlertManager
Multi-Channel Notifications: Support for SMS (Kavenegar, Smsir)
User & Role Management: Complete RBAC (Role-Based Access Control) system
Group Management: Organize users into groups for efficient alert routing
Web Dashboard: React-based web interface for monitoring and managing alerts
Notification Providers: Configurable priority-based notification provider system
Schedulers: Background workers for processing alerts and messages
RESTful API: Comprehensive REST API for integration
JWT Authentication: Secure token-based authentication
CAPTCHA Support: Built-in CAPTCHA for user registration

Architecture

├── cmd/server/          # Application entry point
├── internal/            # Internal application code
│   ├── bootstrap/       # Application initialization
│   ├── config/          # Configuration management
│   ├── logging/         # Logging setup
│   ├── schedulers/      # Background schedulers
│   ├── server/          # HTTP server setup
│   └── storage/         # Database connections
├── pkg/                 # Reusable packages
│   ├── alerts/          # Alert management
│   ├── auth/            # Authentication
│   ├── groups/          # Group management
│   ├── http/            # HTTP handlers and middleware
│   ├── message/         # Message handling
│   ├── notifications/   # Notification providers
│   ├── roles/           # Role management
│   ├── storage/         # Data repositories
│   └── user/            # User management
├── migrations/          # Database migrations
└── web/                 # React frontend application

Prerequisites

Go: 1.23.0 or higher
PostgreSQL: 13 or higher
Node.js: 16 or higher (for web frontend)
Git: For version control

Installation

1. Clone the Repository

git clone https://github.com/lyralab/iris.git
cd iris

2. Install Dependencies

Backend (Go)

go mod download

Frontend (React)

cd web
npm install
cd ..

3. Database Setup

Create a PostgreSQL database:

CREATE DATABASE iris;
CREATE USER iris_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE iris TO iris_user;

4. Run Database Migrations

The application automatically runs migrations on startup, or you can run them manually:

# Migrations are located in the migrations/ directory
# They will be executed automatically when the application starts

Configuration

Iris uses environment variables for configuration. Create a .env file in the root directory with the following variables:

Required Configuration

# Database Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DATABASE_NAME=iris
POSTGRES_USER=iris_user
POSTGRES_PASS=your_password
POSTGRES_SSL=false

# HTTP Server Configuration
HTTP_PORT=9090

# Security
JWT_SECRET=your-secret-jwt-key-change-this-in-production
ADMIN_PASS=your-admin-password

# Application Mode
GO_ENV=debug  # Use "release" for production
SIGNUP_ENABLED=true  # Set to false to disable user registration

Notification Providers (Optional)

Kavenegar (SMS Provider)

KAVENEGAR_API_TOKEN=your-kavenegar-api-token
KAVENEGAR_SENDER=your-sender-number
KAVENEGAR_ENABLED=true
KAVENEGAR_PRIORITY=1  # Lower number = higher priority

Smsir (SMS Provider)

SMSIR_API_TOKEN=your-smsir-api-token
SMSIR_LINE_NUMBER=your-smsir-line-number
SMSIR_ENABLED=false
SMSIR_PRIORITY=2

Email Configuration

EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
[email protected]
EMAIL_PASSWORD=your-email-password
[email protected]
EMAIL_ENABLED=false

Scheduler Configuration (Optional)

# Mobile/SMS Scheduler
MOBILE_SCHEDULER_START_AT=1s
MOBILE_SCHEDULER_INTERVAL=600s
MOBILE_SCHEDULER_WORKERS=1
MOBILE_SCHEDULER_QUEUE_SIZE=1
MOBILE_SCHEDULER_CACHE_CAPACITY=1

# Alert Scheduler
ALERT_SCHEDULER_START_AT=2s
ALERT_SCHEDULER_INTERVAL=10s
ALERT_SCHEDULER_WORKERS=1
ALERT_SCHEDULER_QUEUE_SIZE=10

# Message Status Scheduler
MESSAGE_STATUS_START_AT=10s
MESSAGE_STATUS_INTERVAL=10s
MESSAGE_STATUS_WORKERS=10
MESSAGE_STATUS_QUEUE_SIZE=100

See .env.example for a complete configuration template.

Running the Application

Development Mode

Start the Backend

# From the project root
go run cmd/server/main.go

The API server will start on http://localhost:9090 (or your configured HTTP_PORT).

Start the Frontend

# In a separate terminal
cd web
npm start

The web interface will be available at http://localhost:3000.

Production Mode

Build the Backend

go build -o iris cmd/server/main.go

Run the Backend

./iris

Build the Frontend

cd web
npm run build

The production build will be created in the web/build directory. Serve it using a web server like Nginx or Apache.

API Documentation

Authentication

Most endpoints require JWT authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

User Management

Sign Up

POST /v1/users/create
Content-Type: application/json

{
  "username": "john.doe",
  "firstname": "John",
  "lastname": "Doe",
  "password": "SecurePass123!",
  "confirm-password": "SecurePass123!",
  "email": "[email protected]"
}

Sign In

POST /v1/users/signin
Content-Type: application/json

{
  "username": "john.doe",
  "password": "SecurePass123!"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "username": "john.doe",
    "role": "viewer"
  }
}

Verify User (Admin only)

POST /v1/users/verify
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "username": "john.doe"
}

Alert Management

Get All Alerts

GET /v0/alerts
Authorization: Bearer <token>

Get Alert by ID

GET /v0/alerts/{alert_id}
Authorization: Bearer <token>

Get Alerts with Pagination

GET /v0/alerts/?page=1&pagination=10&status=firing
Authorization: Bearer <token>

Status values: firing, resolved

Get Firing Alert Count

GET /v0/alerts/firingCount
Authorization: Bearer <token>

Webhook Endpoints

Grafana Webhook

not implemented yet

AlertManager Webhook

POST /v1/messages/alertmanager
Authorization: Basic admin:<ADMIN_PASS>
Content-Type: application/json

{
  "version": "4",
  "groupKey": "alert-group-1",
  "status": "firing",
  "receiver": "iris-webhook",
  "alerts": [
    {
      "status": "firing",
      "labels": {
        "alertName": "HighCPU",
        "method": "sms",
        "receptor": "admin",
        "severity": "critical"
      },
      "annotations": {
        "summary": "CPU usage is above 90%"
      },
      "startsAt": "2024-01-12T12:34:32.908Z",
      "fingerprint": "unique-fingerprint-123"
    }
  ]
}

Health Check

GET /health

Response:

{
  "status": "healthy"
}

Alert Label Configuration

For proper routing of notifications, include these labels in your alerts:

receptor: The recipient's phone number or username (required)
method: Notification method - sms, call, or email (required)
alertname: Name of the alert
severity: Alert severity level (e.g., critical, warning, info)

Example Grafana alert configuration:

{
  "labels": {
    "alertname": "HighMemoryUsage",
    "receptor": "group_name_1,group_name_2",
    "method": "sms",
    "severity": "critical"
  },
  "annotations": {
    "summary": "Memory usage is above 80%",
    "description": "Server XYZ has memory usage of 85%"
  }
}

Web Interface

The web dashboard provides:

Dashboard: Overview of firing and resolved alerts
Alert List: Paginated list of all alerts
Alert Details: Detailed view of individual alerts
User Authentication: Sign in to access the dashboard

Configuration

Update web/src/config.js to point to your API server:

const base_url = 'http://127.0.0.1:9090';

const config = {
    api: {
        alertSummary: base_url + '/v0/alerts/firingCount',
        firingIssues: base_url + '/v0/alerts/?page=1&pagination=10&status=firing',
        resolvedIssues: base_url + '/v0/alerts/?page=1&pagination=10&status=resolved',
        signin: base_url + '/v1/users/signin',
    },
};

export default config;

Database Schema

The system uses the following main tables:

alerts: Stores all alert information
users: User accounts
roles: User roles and permissions
groups: User groups for organization
user_groups: Many-to-many relationship between users and groups
providers: Notification provider configuration
message: Outgoing notification messages

Security Considerations

Change Default Passwords: Always change the default admin password
JWT Secret: Use a strong, unique JWT secret in production
HTTPS: Use HTTPS in production environments
Database Security: Use strong database passwords and restrict access
API Keys: Keep notification provider API keys secure
Disable Signup: Set SIGNUP_ENABLED=false in production if you don't want open registration

Troubleshooting

Application Won't Start

Error: "JWT_SECRET not set"
- Solution: Set the JWT_SECRET environment variable
Error: Database connection failed
- Solution: Check database credentials and ensure PostgreSQL is running

Notifications Not Being Sent

Check that the appropriate notification provider is enabled
Verify API tokens are correct
Check scheduler configuration
Review application logs for errors

Web Interface Can't Connect to API

Verify the backend is running
Check the base_url in web/src/config.js
Ensure CORS is properly configured

Development

Running Tests

# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific package tests
go test ./pkg/alerts/...

Code Structure

Follow Go best practices and conventions
Use meaningful variable and function names
Add comments for exported functions
Write tests for new features

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

Support

For issues and questions:

Create an issue on GitHub
Contact the development team

Changelog

Version 0.0.1

Initial release
Alert management system
Multi-channel notifications
User and role management
Web dashboard
AlertManager integration

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.vscode		.vscode
assets		assets
cmd/server		cmd/server
internal		internal
migrations		migrations
pkg		pkg
web		web
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
alerts.http		alerts.http
config.yml		config.yml
go.mod		go.mod
go.sum		go.sum
health.http		health.http
http-client.env.json		http-client.env.json
iris.env		iris.env
messages.http		messages.http
package.json		package.json
user.http		user.http

lyralab/iris

Folders and files

Latest commit

History

Repository files navigation

Iris - Alert Notification System

Features

Architecture

Prerequisites

Installation

1. Clone the Repository

2. Install Dependencies

Backend (Go)

Frontend (React)

3. Database Setup

4. Run Database Migrations

Configuration

Required Configuration

Notification Providers (Optional)

Kavenegar (SMS Provider)

Smsir (SMS Provider)

Email Configuration

Scheduler Configuration (Optional)

Running the Application

Development Mode

Start the Backend

Start the Frontend

Production Mode

Build the Backend

Run the Backend

Build the Frontend

API Documentation

Authentication

User Management

Sign Up

Sign In

Verify User (Admin only)

Alert Management

Get All Alerts

Get Alert by ID

Get Alerts with Pagination

Get Firing Alert Count

Webhook Endpoints

Grafana Webhook

AlertManager Webhook

Health Check

Alert Label Configuration

Web Interface

Configuration

Database Schema

Security Considerations

Troubleshooting

Application Won't Start

Notifications Not Being Sent

Web Interface Can't Connect to API

Development

Running Tests

Code Structure

Contributing

License

Support

Changelog

Version 0.0.1

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages