# OnCallAlert Technical Documentation
Comprehensive, industry-standard, AI-first incident response and on-call alerting platform.
Single Docker container or Go binary backed by PostgreSQL 16+.
---
## Table of Contents
1. [Docker Deployment & Getting Started](#docker-deployment)
2. [Environment Variables](#environment-variables)
3. [Database Setup (PostgreSQL)](#database-setup)
4. [In-App Administration & Configuration](#in-app-administration)
- [System & Alert Configuration](#system--alert-configuration)
- [Authentication & Single Sign-On (SSO)](#authentication--sso)
- [API Keys, Scopes & Delegation](#api-keys--scopes)
- [Twilio Telephony & Emergency Killswitches](#twilio-telephony--killswitches)
- [Priority Label Routing & Escalation](#priority-label-routing)
- [VAPID Web Push Notifications](#vapid-web-push)
- [Mobile Push Relay Gateway](#mobile-push-relay)
- [SaaS Dead-Man Switch Watchdog](#saas-dead-man-switch)
- [Ask AI Triage & Incident Summarization](#ask-ai-triage)
- [1-Click Migration Wizard](#1-click-migration-wizard)
5. [Core Features & Workflows](#core-features--workflows)
- [On-Call Rotations](#on-call-rotations)
- [Schedules & Daily Shift Rules](#schedules--shifts)
- [Escalation Policies](#escalation-policies)
- [User Overrides](#user-overrides)
- [Services & Maintenance Windows](#services--maintenance-windows)
- [Contact Methods & Personal Notification Rules](#contact-methods--rules)
6. [Inbound Alert APIs & Webhooks](#inbound-alert-apis)
- [Generic Alert Ingestion API](#generic-alert-ingestion-api)
- [Grafana Unified Alerting Integration](#grafana-alerting)
- [Prometheus Alertmanager Integration](#prometheus-alertmanager)
- [Datadog Webhook Integration](#datadog-webhook)
- [Inbound Email Alert Ingestion](#inbound-email)
7. [Infrastructure as Code (IaC) Reference](#infrastructure-as-code)
- [Terraform & OpenTofu Provider Configuration](#iac-provider)
- [Resource Schemas & HCL Examples (8 Resources)](#iac-resources)
- [Data Sources (5 Data Sources)](#iac-data-sources)
- [Import Syntax Table](#iac-import)
- [OpenTofu & Pulumi Integration](#opentofu--pulumi)
8. [AI Assistants & MCP Server Tool Contracts](#mcp-server)
- [MCP Architecture & Local Security](#mcp-architecture)
- [Assistant Configurations (Claude, Cursor, VS Code)](#mcp-client-setup)
- [Complete 14 Tool Schema Contracts](#mcp-tools)
- [Role Permissions & Error Handling Matrix](#mcp-security)
9. [Mobile Applications & Delivery](#mobile-applications)
- [iOS & Android Setup & QR Pairing](#mobile-setup)
- [iOS Critical Alerts Entitlement](#ios-critical-alerts)
- [Android DND Overrides & Battery Optimization](#android-permissions)
10. [Access Control & User Roles](#user-roles)
- [Role Definitions & Free Unlimited Viewers](#role-definitions)
- [Governance & Safety Invariants](#governance-invariants)
---
## 1. Docker Deployment
OnCallAlert runs as a single stateless container backed by a PostgreSQL database (version 16 or newer with the `pgcrypto` extension enabled).
### 1. Launch the Server Container
```sh
docker run -d \
--name oncallalert \
--restart unless-stopped \
-p 8080:8080 \
-e ONCALLALERT_DB_URL="postgres://user:password@your-postgres:5432/oncallalert?sslmode=require" \
-e ONCALLALERT_PUBLIC_URL="https://oncall.yourcompany.com" \
-e ONCALLALERT_DATA_ENCRYPTION_KEY="a-long-random-secret" \
oncallalert/oncallalert:latest
```
- Image: `oncallalert/oncallalert:latest` on Docker Hub. Pin version tags (e.g. `v2.1.0`) for production stability.
- Port: Listens on `0.0.0.0:8080` inside the container.
- Encryption Key: Must remain identical across restarts and upgrades; used to encrypt all sensitive credentials stored in PostgreSQL.
### 2. Create the Bootstrap Administrator
To prevent unauthorized public self-registration, OnCallAlert does not have an open sign-up page. Create the initial Owner/Admin account using the container CLI:
```sh
docker exec -it oncallalert oncallalert add-user \
--user admin --email admin@example.com --admin
```
Omit `--pass` to interactively prompt for a password, or pass `--pass`.
### 3. Configure Single Sign-On (SSO / OIDC)
OnCallAlert supports OpenID Connect (OIDC) authentication using Google or GitHub. Configure OIDC client credentials in the admin settings page (`/admin/config`) or environment variables. Users can then authenticate directly using their corporate single sign-on accounts.
### 4. Sign In and Activate License
1. Navigate to your configured public URL (e.g., `https://oncall.yourcompany.com`).
2. Sign in with the administrator account created in step 2.
3. On the **Activate OnCallAlert** prompt, paste your license key.
4. Once activated, alert intake is opened, and all platform features become accessible.
### 5. Health Check Endpoint
Monitor server health using the built-in HTTP health check:
```bash
curl -f http://localhost:8080/healthz
```
---
## 2. Environment Variables
Server bootstrap options are configured via environment variables prefixed with `ONCALLALERT_`. The legacy `GOALERT_` prefix is supported for backward compatibility.
| Variable | Type | Default | Required | Description |
|---|---|---|---|---|
| `ONCALLALERT_DB_URL` | String | *None* | Yes | PostgreSQL connection string (`postgres://...`). Must point to Postgres 16+ with `pgcrypto`. |
| `ONCALLALERT_PUBLIC_URL` | String | *None* | Recommended | Canonical external base URL (`https://oncall.example.com`). Used for deep-links, OAuth callbacks, and license checks. |
| `ONCALLALERT_DATA_ENCRYPTION_KEY` | String (Secret) | *None* | Recommended | Symmetric encryption key protecting database secrets (AI keys, VAPID keys, Slack tokens, push relay keys). |
| `ONCALLALERT_LISTEN` | String | `0.0.0.0:8080` | No | Network interface and port for the HTTP/HTTPS listener. |
---
## 3. Database Setup (PostgreSQL)
- **PostgreSQL Version**: 16 or newer.
- **Extensions**: Requires `pgcrypto`. Run `CREATE EXTENSION IF NOT EXISTS pgcrypto;` as database superuser.
- **Connection Pooling**: Container maintains an internal pool up to 25 connections.
- **TLS Encryption**: Enforce `sslmode=require` in production to protect incident details and credentials in transit.
- **Backups**: Regular `pg_dump` backups or continuous WAL archiving.
---
## 4. In-App Administration & Configuration
Administrators configure operational behavior dynamically via the web console at `/admin/config`. Changes apply in real time across cluster nodes.
### System & Alert Configuration
#### General Settings (`General.*`)
- `General.ApplicationName` (String, Default: `"OnCallAlert"`, Scope: Public): System title in web UI, emails, and TTS voice prompts.
- `General.PublicURL` (String, Default: *None*, Scope: Public): Base URL fallback. (Environment variable takes precedence).
- `General.GoogleAnalyticsID` (String, Default: *None*, Scope: Public): GA4 measurement ID (`G-XXXXXXXXXX`).
- `General.NotificationDisclaimer` (String, Default: *None*, Scope: Public): Telephony disclaimer text shown on user profile pages.
- `General.DisableMessageBundles` (Boolean, Default: `false`, Scope: Public): Disables aggregating status updates into bundles.
- `General.ShortURL` (String, Default: *None*, Scope: Public): Concise domain prefix for SMS notification links.
- `General.DisableSMSLinks` (Boolean, Default: `false`, Scope: Public): Strips all URLs from outbound SMS to prevent telecom spam filtering.
- `General.DisableLabelCreation` (Boolean, Default: `false`, Scope: Public): Freezes service label authoring to existing keys.
- `General.DisableCalendarSubscriptions` (Boolean, Default: `false`, Scope: Public): Deactivates all active iCalendar (ICS) schedule export feeds.
#### Service Governance (`Services.*`)
- `Services.RequiredLabels` ([]String, Default: `[]`, Scope: Public): Mandatory metadata labels required when creating any service.
#### Maintenance & Retention (`Maintenance.*`)
- `Maintenance.AlertCleanupDays` (Integer, Default: `0` / Disabled, Scope: Public): Days before closed alerts are permanently deleted.
- `Maintenance.AlertAutoCloseDays` (Integer, Default: `0` / Disabled, Scope: Public): Inactivity days before unacknowledged alerts auto-close.
- `Maintenance.AutoCloseAckedAlerts` (Boolean, Default: `false`, Scope: Public): Whether auto-close also applies to acknowledged alerts.
- `Maintenance.APIKeyExpireDays` (Integer, Default: `0` / Disabled, Scope: Public): Inactivity days before unused calendar API keys are revoked.
- `Maintenance.ScheduleCleanupDays` (Integer, Default: `0` / Disabled, Scope: Public): Retention days for historical on-call shift records.
#### Slack Gateway (`Slack.*`)
- `Slack.Enable` (Boolean, Default: `false`, Scope: Public): Enables Slack channel alerts and user direct messages (Slack DM).
- `Slack.AccessToken` (String, Secret): Bot user OAuth token (starts with `xoxb-`).
- `Slack.SigningSecret` (String, Secret): Signing secret validating Slack webhook callbacks.
- `Slack.InteractiveMessages` (Boolean, Default: `false`, Scope: Internal): Enables interactive Ack/Close/Escalate buttons in Slack.
- `Slack.DisableBroadcastThreadReplies` (Boolean, Default: `false`, Scope: Public): Keeps alert updates strictly inside incident threads.
#### Email Gateway (`SMTP.*`)
- `SMTP.Enable` (Boolean, Default: `false`, Scope: Public): Enables email as a contact method.
- `SMTP.From` (String, Scope: Public): Outgoing sender address (`alerts@oncall.example.com`).
- `SMTP.Address` (String, Scope: Internal): Host and port (e.g. `smtp.example.com:587`).
- `SMTP.Username` / `SMTP.Password` (String, Secret): SMTP credentials.
- `SMTP.DisableTLS` (Boolean, Default: `false`, Scope: Internal): Disables explicit TLS (uses STARTTLS if available).
- `SMTP.SkipVerify` (Boolean, Default: `false`, Scope: Internal): Disables certificate chain checks (staging only).
#### Webhooks & Feedback (`Webhook.*`, `Feedback.*`)
- `Webhook.Enable` (Boolean, Default: `false`, Scope: Public): Enables custom HTTP webhook contact methods.
- `Webhook.AllowedURLs` ([]String, Default: `[]`, Scope: Public): Security whitelist of allowed destination domains.
- `Feedback.Enable` (Boolean, Default: `false`, Scope: Public): Toggles the Feedback navigation header link.
- `Feedback.OverrideURL` (String, Scope: Public): Custom target URL for feedback.
### Authentication & Single Sign-On (SSO)
#### Password Killswitch
- `Auth.DisableBasic` (Boolean, Default: `false`, Scope: Public): **Killswitch**. When set to `true`, username and password login is disabled across the entire instance, enforcing SSO.
#### GitHub OAuth
- `GitHub.Enable` (Boolean, Default: `false`, Scope: Public): Toggles GitHub OAuth sign-in button.
- `GitHub.ClientID` (String) & `GitHub.ClientSecret` (String, Secret): OAuth App credentials. Callback: `https://oncall.example.com/api/v2/identity/providers/github/callback`.
- `GitHub.NewUsers` (Boolean, Default: `false`): Enables auto-provisioning new accounts for authenticating GitHub users.
- `GitHub.AllowedUsers` ([]String): Whitelist of allowed GitHub usernames (`["*"]` for all).
- `GitHub.AllowedOrgs` ([]String): Whitelist of allowed GitHub organizations or teams (`"org/team"`).
- `GitHub.EnterpriseURL` (String): Custom endpoint for GitHub Enterprise Server instances.
#### OpenID Connect (OIDC) SSO
- `OIDC.Enable` (Boolean, Default: `false`, Scope: Public): Enables enterprise OIDC authentication.
- `OIDC.IssuerURL` (String): Discovery issuer endpoint (Google, Okta, Azure AD, Keycloak). Callback: `https://oncall.example.com/api/v2/identity/providers/oidc/callback`.
- `OIDC.ClientID` (String) & `OIDC.ClientSecret` (String, Secret): OIDC client credentials.
- `OIDC.Scopes` (String, Default: `"openid profile email"`): Requested authentication scopes.
- `OIDC.OverrideName` (String, Default: `"OIDC"`): Button display text (e.g. `"Sign in with Okta"`).
- `OIDC.NewUsers` (Boolean, Default: `false`): Enables auto-provisioning of corporate directory users.
- `OIDC.UserInfoEmailPath`, `OIDC.UserInfoEmailVerifiedPath`, `OIDC.UserInfoNamePath`: JMESPath claim extraction expressions.
### API Keys, Scopes & Delegation
Managed under **Admin → API Keys** (`/admin/api-keys`) and user profiles.
- **Scopes**:
- `Read`: Query alerts, services, schedules, on-call assignments, users. Cannot mutate data.
- `Write`: All Read capabilities plus Acknowledge, Close, Escalate, and Create alerts, and Create user overrides.
- `Admin`: Full access to GraphQL mutations, system configuration, user provisioning, and IaC resources.
- **Delegation Invariant**: A token can never perform actions exceeding its creator's role. If an Admin is downgraded, their tokens immediately lose administrative privileges.
- **Approval Workflow**: Non-admin users request Write tokens in their profile. Tokens remain pending until approved by an administrator in Admin → API Keys.
- **Lifecycle**: Maximum token lifetime is 365 days. Revocations take effect immediately.
### Twilio Telephony & Emergency Killswitches
Configured under `Twilio` in Admin → Config:
- `Twilio.Enable` (Boolean, Default: `false`): Enables Twilio outbound voice phone calls and SMS messages.
- `Twilio.AccountSID` & `Twilio.AuthToken` (Secret): Primary Twilio credentials.
- `Twilio.AlternateAuthToken` (Secret): Secondary Auth Token for zero-downtime key rotation.
- `Twilio.FromNumber` (String): Outgoing caller ID in E.164 format (`+15550100123`).
- `Twilio.MessagingServiceSID` (String): Twilio Messaging Service SID (replaces FromNumber for SMS).
- `Twilio.VoiceName` & `Twilio.VoiceLanguage`: Amazon Polly voice and BCP-47 language tag for TTS voice calls.
- `Twilio.SMSCarrierLookup` (Boolean, Default: `false`): Carrier HLR lookups for carrier-specific routing.
- `Twilio.SMSFromNumberOverride` ([]String): Carrier-specific phone number mappings.
#### Emergency Killswitches
- `Twilio.DisableCallProcessing` (Boolean, Default: `false`): **Voice Telephony Killswitch**. Immediately halts all outbound voice calls and terminates IVR processing during provider outages or runaway billing.
- `Twilio.DisableSMSContactMethod` (Boolean, Default: `false`): **SMS Delivery Killswitch**. Suppresses all outgoing SMS text messages globally.
- `Twilio.DisableTwoWaySMS` (Boolean, Default: `false`): Disables SMS reply codes ('1' to Ack, '2' to Close), saving carrier segment fees while maintaining one-way outbound alerts.
### Priority Label Routing & Escalation
Configured under `Alerts` in Admin → Config:
- `Alerts.HighPriorityLabelKey` (String): Metadata key evaluated on incoming alerts (e.g. `"severity"` or `"urgency"`).
- `Alerts.HighPriorityLabelValue` (String): Matching value triggering high-priority status (e.g. `"critical"` or `"high"`).
- `Alerts.HighPriorityEscalationContactTypes` ([]String): Ordered channels notified if high-priority alert is unacknowledged (`voice`, `sms`, `mobile`, `email`, `slack`, `webpush`).
- `Alerts.HighPriorityEscalationDelayMinutes` (Integer, Default: `5`, Min: 1): Elapsed minutes before high-priority escalation triggers.
- `Alerts.HighPriorityDedupeWindowMinutes` (Integer, Default: `2`): Deduplication window preventing double-paging for the same incident (`-1` disables).
- `Alerts.AllowSameTypeContactMethods` (Boolean, Default: `false`): Permits notifying multiple contact methods of the same type (e.g. two phone numbers).
### VAPID Web Push Notifications
W3C browser push notifications (Chrome, Firefox, Safari, Edge) without third-party services.
Key generation: `npx web-push generate-vapid-keys`
- `WebPush.Enable` (Boolean, Default: `false`): Enables browser push notifications.
- `WebPush.VAPIDPublicKey` (String): Base64 URL-safe unpadded public key.
- `WebPush.VAPIDPrivateKey` (String, Secret): Base64 URL-safe unpadded private key (stored encrypted).
- `WebPush.SubscriberEmail` (String): Contact URI (`mailto:admin@example.com`) for the VAPID `sub` claim.
### Mobile Push Relay Gateway
Enables iOS and Android app push notifications without requiring self-hosters to maintain Apple Developer or Google Play push certificates.
- `Mobile.Enable` (Boolean, Default: `false`): Activates mobile push routing.
- `Mobile.RelayURL` (String, Default: `"https://relay.oncallalert.dev"`): Relay service endpoint.
- `Mobile.RelayAPIKey` (String, Secret): Instance authentication key issued upon license activation.
### SaaS Dead-Man Switch Watchdog
Out-of-band monitoring: if your OnCallAlert server goes offline or loses connectivity, the hosted watchdog detects the silence and pages admin mobile devices.
- `Deadman.Enable` (Boolean, Default: `false`): Activates the heartbeat background worker.
- `Deadman.IntervalSeconds` (Integer, Default: `300` / 5m, Range: 300-3600): Ping recurrence interval.
- `Deadman.MissCount` (Integer, Default: `3`, Range: 1-10): Consecutive missed pings before declaring an outage (~15m at default).
- **Routing**: Alerts responders in the automatically provisioned **SaaS heartbeat** escalation policy who have paired mobile devices.
### Ask AI Triage & Incident Summarization
Bring Your Own Key (BYOK) AI triage analyzing root cause, severity, and remediation steps. Requests go directly from your server to your chosen provider; no data transits OnCallAlert.
- `AI.Enable` (Boolean, Default: `false`): Enables the Ask AI button on alerts.
- `AI.Provider` (String): Provider choice (`openai`, `anthropic`, `ollama`, or `openai-compatible`).
- `AI.Model` (String): Model name (`gpt-4o-mini`, `claude-3-5-haiku-20241022`, `llama3.2`, `gemini-1.5-flash`).
- `AI.BaseURL` (String): Custom endpoint URL (required for `openai-compatible`).
- `AI.AutoTriage` (Boolean, Default: `false`): Summarizes every incoming alert automatically. Off by default.
- `AI.MaxPerHour` (Integer, Default: `30`): Rate limit ceiling protecting against runaway LLM bills during alert storms.
### 1-Click Migration Wizard
Managed in **Admin → Import** (`/admin/import`). Migrates configurations from PagerDuty, Jira Service Management (JSM), or Opsgenie.
- **Process**: Supply read-only vendor API credentials → Preview migration manifest → Confirm transactional import.
- **Safety**: Fully transactional—either all entities import or the entire batch rolls back.
- **Mappings**: Users matched by email, contact methods imported directly, schedules/rotations preserved with timezone and handoff rules, escalation policies mapped with identical steps and repeats.
---
## 5. Core Features & Workflows
### On-Call Rotations
Rotations cycle on-call duty automatically through an ordered list of engineers.
- **Type**: `hourly`, `daily`, `weekly`, or `monthly`.
- **Shift Length**: Cadence multiplier (e.g. `type="weekly"` with `shift_length=2` creates two-week shifts).
- **Start**: Anchor timestamp (RFC 3339) from which all past and future shifts are calculated.
- **Time Zone**: Canonical IANA timezone (`America/New_York`, `Europe/Berlin`, `Etc/UTC`). Handles DST handoffs cleanly.
- **Users**: Ordered roster. Responders take turns in strict cyclic sequence.
### Schedules & Daily Shift Rules
Schedules map days and times to users or rotations.
- **Schedule Rules** (`oncallalert_schedule_rule`):
- `target_type`: `"rotation"` or `"user"`.
- `target_id`: UUID of the rotation or user.
- `start` & `end`: Daily time window in `HH:MM` format (schedule timezone). Overnight shifts (e.g. `17:00` to `09:00`) span midnight cleanly.
- `weekdays`: Array of days (`["mon", "tue", "wed", "thu", "fri"]`).
- **Follow-the-Sun**: Schedules easily combine APAC, EMEA, and Americas rotations across UTC hours.
### Escalation Policies
Defines the multi-tier escalation progression when incidents are triggered.
- **Steps**: Ordered list of tiers. Each step defines `delay_minutes` (wait time before escalating) and concurrent action targets.
- **Action Targets**:
- `builtin-user` (args: `user_id`): Direct user page.
- `builtin-schedule` (args: `schedule_id`): Pages active shift responder.
- `builtin-rotation` (args: `rotation_id`): Pages active rotation engineer.
- `builtin-slack-channel` (args: `slack_channel_id`): Broadcasts to Slack.
- `builtin-webhook` (args: `webhook_url`): Dispatches HTTP POST.
- **Repeats**: Number of times to cycle through all steps if unacknowledged (default: `3`).
- **State Lifecycle**:
- *Unacknowledged*: Escalation timers count down; notifications dispatched.
- *Acknowledged*: Escalation timers frozen; incident assigned to responder.
- *Closed*: Incident resolved; active notifications halted.
### User Overrides
Temporary schedule coverage adjustments without modifying recurring rules.
- **Add User** (`add_user_id`): Adds an extra responder on call for the duration.
- **Remove User** (`remove_user_id`): Relieves a responder from on-call duty.
- **Replace User** (`add_user_id` + `remove_user_id`): Swaps scheduled responder with substitute covering engineer.
- **Time Range**: Bounded by RFC 3339 `start` and `end` timestamps.
### Services & Maintenance Windows
A Service represents a monitored microservice, component, or system.
- **Escalation Policy Binding**: All alerts on the service route through its assigned escalation policy.
- **Integration Keys**: Services own ingress webhook tokens (Generic, Grafana, Prometheus, Datadog, Email).
- **Service Labels**: Key-value tags (`team=backend`, `tier=p1`) for filtering and priority routing.
- **Maintenance Windows** (`maintenanceExpiresAt`): Suppresses outbound paging during planned maintenance while continuing to log alert events. Resumes normal paging automatically once the timestamp expires.
### Contact Methods & Personal Notification Rules
- **Contact Method Channels**: Voice Call (Twilio), SMS (Twilio), Mobile Push (Relay), Email (SMTP), Slack DM, Web Push (VAPID), Custom Webhook.
- **Tiered Notification Rules**:
- 0m: Mobile Push + Slack DM.
- 2m: SMS Text Message if unacknowledged.
- 5m: Voice Phone Call with interactive IVR prompt if still unacknowledged.
- Acknowledging an incident automatically cancels subsequent pending notification steps.
---
## 6. Inbound Alert APIs & Webhooks
### Generic Alert Ingestion API
```sh
curl -X POST https://oncall.example.com/api/v2/generic/incoming \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"summary": "Production Redis Out of Memory",
"details": "Replica node memory saturation exceeded 95% on cluster shard-04.",
"dedup": "redis-shard-04-oom"
}'
```
- `summary` (String, Required): Headline text (max 1000 chars).
- `details` (String, Optional): Markdown diagnostic description.
- `dedup` (String, Optional): Deduplication key. Groups repeated alerts onto the open incident.
### Grafana Unified Alerting
In Grafana → Alerting → Contact points → Add Webhook:
- URL: `https://oncall.example.com/api/v2/grafana/incoming?token=your-grafana-key`
- Method: `POST`
- Automatically manages incident creation and auto-closure on resolution.
### Prometheus Alertmanager
In `alertmanager.yml`:
```yaml
receivers:
- name: 'oncallalert'
webhook_configs:
- url: 'https://oncall.example.com/api/v2/prometheusalertmanager/incoming?token=your-alertmanager-key'
send_resolved: true
```
### Datadog Webhook
Target `https://oncall.example.com/api/v2/generic/incoming` with header `Authorization: Bearer your-key` and payload:
```json
{
"summary": "$EVENT_TITLE",
"details": "$EVENT_MSG\n\nAlert URL: $LINK",
"dedup": "$ALERT_ID"
}
```
### Inbound Email Alert Ingestion
Create an Integration Key of type Email. Send alerts to `service-xyz@alerts.oncall.example.com`. Parsed via Mailgun webhook or local SMTP ingress.
---
## 7. Infrastructure as Code (IaC) Reference
### Terraform & OpenTofu Provider Configuration
Official Provider: `OnCallAlert/oncallalert` (published on Terraform Registry & OpenTofu Registry).
```terraform
terraform {
required_providers {
oncallalert = {
source = "OnCallAlert/oncallalert"
version = "~> 1.0"
}
}
}
provider "oncallalert" {
url = "https://oncall.example.com" # or ONCALLALERT_URL
token = var.oncallalert_token # or ONCALLALERT_TOKEN (Admin scope)
}
```
### Resource Schemas & HCL Examples (8 Resources)
#### 1. `oncallalert_escalation_policy`
```terraform
resource "oncallalert_escalation_policy" "primary" {
name = "Primary Escalation"
description = "Page on-call engineer, escalate after 5m"
repeat = 2
steps = [
{
delay_minutes = 5
actions = [
{ type = "builtin-rotation", args = { rotation_id = oncallalert_rotation.backend.id } },
]
},
{
delay_minutes = 15
actions = [
{ type = "builtin-schedule", args = { schedule_id = oncallalert_schedule.ops.id } },
{ type = "builtin-user", args = { user_id = data.oncallalert_user.lead.id } },
]
}
]
}
```
#### 2. `oncallalert_rotation`
```terraform
resource "oncallalert_rotation" "backend" {
name = "Backend Weekly"
time_zone = "America/New_York"
start = "2026-01-05T09:00:00-05:00"
type = "weekly"
shift_length = 1
user_ids = [data.oncallalert_user.alice.id, data.oncallalert_user.bob.id]
}
```
#### 3. `oncallalert_schedule`
```terraform
resource "oncallalert_schedule" "ops" {
name = "SRE Operations"
description = "24x7 coverage"
time_zone = "Etc/UTC"
}
```
#### 4. `oncallalert_schedule_rule`
```terraform
resource "oncallalert_schedule_rule" "office_hours" {
schedule_id = oncallalert_schedule.ops.id
target_type = "rotation"
target_id = oncallalert_rotation.backend.id
start = "09:00"
end = "17:00"
weekdays = ["mon", "tue", "wed", "thu", "fri"]
}
```
#### 5. `oncallalert_user_override`
```terraform
resource "oncallalert_user_override" "holiday" {
schedule_id = oncallalert_schedule.ops.id
start = "2026-12-24T00:00:00Z"
end = "2026-12-27T00:00:00Z"
add_user_id = data.oncallalert_user.bob.id
remove_user_id = data.oncallalert_user.alice.id
}
```
#### 6. `oncallalert_service`
```terraform
resource "oncallalert_service" "api" {
name = "Public API"
description = "Core HTTP API gateway"
escalation_policy_id = oncallalert_escalation_policy.primary.id
}
```
#### 7. `oncallalert_service_label`
```terraform
resource "oncallalert_service_label" "team" {
service_id = oncallalert_service.api.id
key = "team"
value = "backend-core"
}
```
#### 8. `oncallalert_integration_key`
```terraform
resource "oncallalert_integration_key" "grafana" {
service_id = oncallalert_service.api.id
type = "grafana"
name = "Grafana Ingress"
}
output "grafana_webhook_url" {
value = oncallalert_integration_key.grafana.href
sensitive = true
}
```
### Data Sources (5 Data Sources)
```terraform
data "oncallalert_user" "alice" {
email = "alice@example.com"
}
data "oncallalert_service" "api" {
name = "Public API"
}
data "oncallalert_schedule" "ops" {
name = "SRE Operations"
}
data "oncallalert_escalation_policy" "primary" {
name = "Primary Escalation"
}
data "oncallalert_rotation" "backend" {
name = "Backend Weekly"
}
```
### Import Syntax Table
| Resource | Import Command Syntax | Example |
|---|---|---|
| `oncallalert_escalation_policy` | `terraform import oncallalert_escalation_policy. ` | `terraform import oncallalert_escalation_policy.primary 7b9e12...` |
| `oncallalert_rotation` | `terraform import oncallalert_rotation. ` | `terraform import oncallalert_rotation.backend 4a8c31...` |
| `oncallalert_schedule` | `terraform import oncallalert_schedule. ` | `terraform import oncallalert_schedule.ops 9d2e44...` |
| `oncallalert_schedule_rule` | `terraform import oncallalert_schedule_rule. /` | `terraform import oncallalert_schedule_rule.bh 9d2e44.../1c4f55...` |
| `oncallalert_user_override` | `terraform import oncallalert_user_override. ` | `terraform import oncallalert_user_override.swap 3e2a77...` |
| `oncallalert_service` | `terraform import oncallalert_service. ` | `terraform import oncallalert_service.api 8f1b66...` |
| `oncallalert_service_label` | `terraform import oncallalert_service_label. /` | `terraform import oncallalert_service_label.team 8f1b66.../team` |
| `oncallalert_integration_key` | `terraform import oncallalert_integration_key. ` | `terraform import oncallalert_integration_key.grafana 5d0a99...` |
### OpenTofu & Pulumi Integration
- **OpenTofu**: Fully drop-in compatible using `source = "OnCallAlert/oncallalert"`.
- **Pulumi**:
```sh
pulumi package add terraform-provider OnCallAlert/oncallalert
pulumi config set oncallalert:url https://oncall.example.com
export ONCALLALERT_TOKEN=""
```
Python example:
```python
import pulumi
import pulumi_oncallalert as oncallalert
alice = oncallalert.get_user(email="alice@example.com")
rotation = oncallalert.Rotation("backend",
name="Backend Weekly",
time_zone="America/New_York",
start="2026-01-05T09:00:00-05:00",
type="weekly",
shift_length=1,
user_ids=[alice.id]
)
```
---
## 8. AI Assistants & MCP Server Tool Contracts
### MCP Architecture & Local Security
The `oncallalert-mcp` binary implements the Model Context Protocol (MCP). It executes locally on your workstation and connects over HTTPS directly to your private OnCallAlert server using your user API token. Zero external telemetry or intermediaries.
### Client Configurations
#### Claude Code CLI
```sh
claude mcp add oncallalert \
--env ONCALLALERT_URL=https://oncall.example.com \
--env ONCALLALERT_TOKEN=your-api-token \
-- oncallalert-mcp
```
#### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"oncallalert": {
"command": "oncallalert-mcp",
"env": {
"ONCALLALERT_URL": "https://oncall.example.com",
"ONCALLALERT_TOKEN": "your-api-token"
}
}
}
}
```
#### Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
```json
{
"mcpServers": {
"oncallalert": {
"command": "oncallalert-mcp",
"args": ["--read-only"],
"env": {
"ONCALLALERT_URL": "https://oncall.example.com",
"ONCALLALERT_TOKEN": "your-api-token"
}
}
}
}
```
#### VS Code (`.vscode/mcp.json`)
```json
{
"servers": {
"oncallalert": {
"command": "oncallalert-mcp",
"env": {
"ONCALLALERT_URL": "https://oncall.example.com",
"ONCALLALERT_TOKEN": "your-api-token"
}
}
}
}
```
### Complete 14 Tool Schema Contracts
All list endpoints accept `first` (default 15, max 100) and `after`, returning `page_info` with `end_cursor` and `has_next_page`.
#### 1. `list_alerts`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs:
- `service_id` (String, optional): Filter by service UUID.
- `status` (String, optional): `"open"`, `"acknowledged"`, or `"closed"`.
- `since` (String, optional): ISO timestamp or date.
- `until` (String, optional): ISO timestamp or date.
- `search` (String, optional): Full-text match against summary, ID, service.
- `first` (Integer, optional, default: 15, max: 100).
- `after` (String, optional): Cursor.
- Output: `{"alerts": [{"id": 1042, "summary": "...", "status": "open", "service_id": "...", "created_at": "..."}], "page_info": {"end_cursor": "...", "has_next_page": false}}`
#### 2. `get_alert`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: `id` (Integer, required)
- Output: `{"alert": {...}, "details": "...", "service_name": "...", "events": [{"message": "...", "time": "..."}]}`
#### 3. `ack_alert`
- Mutating: Yes | Roles: User, Admin, Owner (Viewer: 403 Forbidden)
- Inputs: `ids` (List of Integers, 1 to 50, required)
- Output: `{"updated_ids": [1042], "skipped_ids": []}`
#### 4. `resolve_alert`
- Mutating: Yes | Roles: User, Admin, Owner
- Inputs: `ids` (List of Integers, 1 to 50, required)
- Output: `{"updated_ids": [1042], "skipped_ids": []}`
#### 5. `escalate_alert`
- Mutating: Yes | Roles: User, Admin, Owner
- Inputs: `id` (Integer, required)
- Output: `{"escalated_id": 1042}`
#### 6. `create_alert`
- Mutating: Yes | Roles: User, Admin, Owner
- Inputs:
- `service_id` (String, required)
- `summary` (String, required)
- `details` (String, optional)
- `dedup` (String, optional)
- Output: `{"alert": {"id": 1043, "summary": "...", "status": "open", "service_id": "...", "created_at": "..."}}`
#### 7. `get_oncall`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: Exactly one of `service_id`, `escalation_policy_id`, `schedule_id`; optional `at` (schedules only).
- Output:
- For service/policy: `{"service_id": "...", "steps": [{"step": 1, "users": [{"id": "...", "name": "..."}]}]}`
- For schedule: `{"schedule_id": "...", "users": [{"id": "...", "name": "..."}]}`
#### 8. `list_schedules`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: `search` (String, optional), `first` (Integer), `after` (String)
- Output: `{"schedules": [{"id": "...", "name": "...", "description": "...", "time_zone": "..."}], "page_info": {...}}`
#### 9. `get_schedule`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: `id` (String, required), `start` (String, optional), `end` (String, optional)
- Output: `{"schedule": {...}, "shifts": [...], "rules": [...], "overrides": [...]}`
#### 10. `create_user_override`
- Mutating: Yes | Roles: User, Admin, Owner
- Inputs:
- `schedule_id` (String, required)
- `start` (String, required)
- `end` (String, required)
- `add_user_id` (String, optional)
- `remove_user_id` (String, optional)
*(At least one of add_user_id or remove_user_id required)*
- Output: `{"id": "...", "schedule_id": "...", "start_time": "...", "end_time": "...", "add_user_id": "...", "remove_user_id": "..."}`
#### 11. `list_services`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: `search` (String, optional), `first` (Integer), `after` (String)
- Output: `{"services": [{"id": "...", "name": "...", "description": "...", "escalation_policy_id": "...", "is_maintenance": false}], "page_info": {...}}`
#### 12. `search_users`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: `search` (String, optional, name match only), `first` (Integer), `after` (String)
- Output: `{"users": [{"id": "...", "name": "...", "email": "...", "role": "user"}], "page_info": {...}}`
#### 13. `get_user`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: `id` (String, required)
- Output: `{"user": {"id": "...", "name": "...", "email": "...", "role": "..."}, "contact_methods": [...], "on_call": [{"service_id": "...", "service_name": "...", "step": 1}]}`
#### 14. `whoami`
- Mutating: No | Roles: Viewer, User, Admin, Owner
- Inputs: None (`{}`)
- Output: `{"id": "...", "name": "...", "email": "...", "role": "..."}`
### Role Permissions & Error Handling Matrix
- **Viewer Role**: Read tools only (`list_*`, `get_*`, `search_*`, `whoami`). All mutating tools return 403 Forbidden.
- **User Role**: Read tools + Mutating tools (with Write-scoped token).
- **Admin & Owner Roles**: Full tool execution.
- **Read-Only Mode (`--read-only`)**: Mutating tools are hidden completely from the MCP tool registry advertised to the AI.
- **Error Codes**:
- `401 Unauthorized`: `"token invalid or lacks permission"`.
- `403 Forbidden`: Mutating action attempted by Viewer or Read token.
---
## 9. Mobile Applications & Delivery
### Setup & QR Pairing
1. Install **OnCallAlert** from the [Google Play Store](https://play.google.com/store/apps/details?id=com.bexiko.oncallalertdev) and the [Apple App Store](https://apps.apple.com/in/app/oncallalert/id6834493259) (both live).
2. In the web UI, open **Profile → Mobile Devices → Pair New Device**.
3. Scan the generated QR code with the mobile app to securely register device push credentials.
### Apple iOS: Critical Alerts Entitlement
OnCallAlert has requested Apple's **Critical Alerts** entitlement, which Apple approves by hand. Until it is approved, iOS alerts are standard notifications that follow the silent switch and Focus modes. After approval, an app update will let alerts bypass the mute switch and Focus modes (Do Not Disturb, Sleep, Work).
### Google Android: DND Overrides & Battery Optimization
Android requires three explicit permissions:
1. **Do Not Disturb Access (DND Override)**: Break through system DND quiet hours.
2. **Full-Screen Intent**: Wake display and render full-screen interactive response UI when locked.
3. **Battery Optimization Exclusion**: Prevent Android Doze Mode from delaying background push sockets.
---
## 10. Access Control & User Roles
### Role Definitions
| Role | Permissions | Consumes Paid Seat |
|---|---|---|
| **Owner** | Full system rights + manage Owner and Admin roles. | Yes (1 seat) |
| **Admin** | Full system, service, schedule, and user management. | Yes (1 seat) |
| **User (On-call)** | Active responder. Participates in shifts, receives pages, manages alerts. | Yes (1 seat) |
| **Viewer** | Read-only observer. Inspects alerts, services, and schedules. Cannot be paged. | **No (Free & Unlimited)** |
Unlike traditional incident management vendors that bill for every user in the directory, OnCallAlert includes **unlimited free viewer seats** on all plans. Stakeholders, customer success managers, and engineering executives can observe real-time incident status without consuming paid responder licenses.
### Governance Invariants
- **Minimum One Owner**: The server strictly prevents deleting or demoting the last Owner. If lost, promote via `docker exec ... oncallalert set-role --user admin --role owner`.
- **Seat Quota Enforcement**: Promoting a Viewer to User, Admin, or Owner checks against license quota.
- **Safe Demotion**: Users must be removed from rotations and escalation steps before demoting to Viewer.
## Pricing
- [Pricing](https://oncallalert.dev/pricing): Flat plans by team size, not per seat. Core $699/year (15 on-call and admin users), Team $149/month or $1,499/year (50 users), Business $499/month or $4,999/year (200 users), Unlimited $999/month or $9,999/year. Viewers are free and unlimited on every plan. Every plan includes schedules, escalations, Slack, analytics, high-priority escalation, one public status page (free yourname.oncallalert.dev address), Ask AI (BYOK, local LLMs supported through Ollama), the MCP server and the Terraform provider. Team and up add the mobile app and dead-man's switch, and a custom status page domain as a $5/month add-on. Support: standard on Core and Team, priority on Business, 24/7 priority with onboarding on Unlimited. Feature requests: https://github.com/OnCallAlert/oncallalert/discussions