### Start PostgreSQL Instance Source: https://github.com/target/goalert/blob/master/docs/development-setup.md Starts a PostgreSQL instance using Docker. This command is part of the GoAlert development setup and ensures the database is available for the application. ```bash make postgres ``` -------------------------------- ### Start GoAlert Local Development Server Source: https://github.com/target/goalert/blob/master/README.md This command initiates the GoAlert development server using `make start`. It launches the application on http://localhost:3030, allowing for live UI and backend code changes without manual restarts. Default admin credentials are provided. ```bash make start ``` -------------------------------- ### Start GoAlert Development Server Source: https://github.com/target/goalert/blob/master/docs/development-setup.md Starts the GoAlert development server using Docker. This command assumes Docker is running and makes the GoAlert UI accessible at http://localhost:3030. It also provides an option to set a public URL for testing external callbacks. ```bash make start make start PUBLIC_URL=https://localdev.example.com ``` -------------------------------- ### Configure VSCode for Yarn PnP Source: https://github.com/target/goalert/blob/master/docs/development-setup.md Installs the Yarn SDK for VSCode, which is necessary for compatibility with the Yarn Plug'n'Play (PnP) setup used by GoAlert. This resolves dependency resolution issues in VSCode. ```bash make vscode ``` -------------------------------- ### GoAlert 'add-user' Subcommand Help Source: https://github.com/target/goalert/blob/master/docs/getting-started.md Displays help information for the 'add-user' subcommand in GoAlert. This command is used to create new users for basic authentication, with options to set roles, emails, and passwords. ```bash $ goalert add-user -h Adds a user for basic authentication. Usage: goalert add-user [flags] Flags: --admin If specified, the user will be created with the admin role (ignored if user-id is provided). --email string Specifies the email address of the new user (ignored if user-id is provided). -h, --help help for add-user --pass string Specify new users password (if blank, prompt will be given). --user string Specifies the login username. --user-id string If specified, the auth entry will be created for an existing user ID. Default is to create a new user. Global Flags: --data-encryption-key string Encryption key for sensitive data like signing keys. Used for encrypting new and decrypting existing data. --data-encryption-key-old string Fallback key. Used for decrypting existing data only. --db-url string Connection string for Postgres. --db-url-next string Connection string for the *next* Postgres server (enables DB switchover mode). --json Log in JSON format. --stack-traces Enables stack traces with all error logs. -v, --verbose Enable verbose logging. ``` -------------------------------- ### Manual PostgreSQL Role Creation Source: https://github.com/target/goalert/blob/master/docs/development-setup.md SQL commands for manually configuring PostgreSQL for GoAlert development if not using Docker. This includes creating the `goalert` role with superuser privileges and enabling the `pgcrypto` extension. ```sql CREATE ROLE goalert WITH LOGIN SUPERUSER; CREATE EXTENSION IF NOT EXISTS pgcrypto WITH SCHEMA public; ``` -------------------------------- ### Expose Local Server with ngrok Source: https://github.com/target/goalert/blob/master/docs/development-setup.md Configures `ngrok` to tunnel external traffic to the local GoAlert development server running on port 3030. This is achieved by adding a line to the `Procfile.local`. ```bash ngrok: ngrok http 3030 ``` -------------------------------- ### Reconfigure GoAlert to Use New Database URL (CLI) Source: https://github.com/target/goalert/blob/master/docs/switchover.md After a successful switchover, this command reconfigures GoAlert to exclusively use the new database URL. The `--db-url-next` flag is removed. ```bash goalert --db-url= ``` -------------------------------- ### Generic API - Curl Examples Source: https://github.com/target/goalert/blob/master/web/src/app/documentation/sections/IntegrationKeys.md These `curl` commands illustrate different ways to trigger alerts using the generic API. They show basic alerts with summary and details, alerts with deduplication, and closing existing alerts. ```bash curl -XPOST https:///api/v2/generic/incoming?token=key-here&summary=test&details=test ``` ```bash curl -XPOST https:///api/v2/generic/incoming?token=key-here&summary=test&dedup=disk-check ``` ```bash curl -XPOST https:///api/v2/generic/incoming?token=key-here&summary=test&action=close ``` -------------------------------- ### Query User Notification Setup Source: https://context7.com/target/goalert/llms.txt Retrieves a user's notification configuration, including contact methods and notification rules. ```APIDOC ## POST /target/goalert (GraphQL) ### Description Queries the user's notification setup, including their ID, name, email, contact methods, and notification rules. ### Method POST ### Endpoint /target/goalert ### Parameters #### Path Parameters None #### Query Parameters None #### Request Body - **query** (String) - Required - The GraphQL query string. ```graphql query UserNotificationSetup($userId: ID!) { user(id: $userId) { id name email contactMethods { id name type formattedValue disabled } notificationRules { id delayMinutes contactMethod { id name type } } } } ``` ### Request Example ```json { "query": "query UserNotificationSetup($userId: ID!) { user(id: $userId) { id name email contactMethods { id name type formattedValue disabled } notificationRules { id delayMinutes contactMethod { id name type } } } }", "variables": { "userId": "user-123" } } ``` ### Response #### Success Response (200) - **data** (Object) - Contains the user's notification setup information. - **user** (Object) - User details. - **id** (ID) - **name** (String) - **email** (String) - **contactMethods** (Array) - List of user's contact methods. - **id** (ID) - **name** (String) - **type** (String) - **formattedValue** (String) - **disabled** (Boolean) - **notificationRules** (Array) - List of user's notification rules. - **id** (ID) - **delayMinutes** (Int) - **contactMethod** (Object) - Associated contact method. - **id** (ID) - **name** (String) - **type** (String) #### Response Example ```json { "data": { "user": { "id": "user-123", "name": "Jane Doe", "email": "jane.doe@example.com", "contactMethods": [ { "id": "contact-method-1", "name": "Work Phone", "type": "phone", "formattedValue": "+11234567890", "disabled": false } ], "notificationRules": [ { "id": "rule-1", "delayMinutes": 5, "contactMethod": { "id": "contact-method-1", "name": "Work Phone", "type": "phone" } } ] } } } ``` ``` -------------------------------- ### Generic API Alert - URL Parameters Source: https://github.com/target/goalert/blob/master/web/src/app/documentation/sections/IntegrationKeys.md This example shows how to send alert metadata using URL query parameters for the generic API. The `meta` parameter can be specified multiple times for different key-value pairs. ```url /api/v2/generic/incomming?token=&meta=example_key=example_value&meta=example_key2=example_value2 ``` -------------------------------- ### Run GoAlert Binary Source: https://github.com/target/goalert/blob/master/docs/getting-started.md This command demonstrates how to run the GoAlert binary directly. It requires specifying the database URL, a data encryption key for sensitive data, and the public URL for the application. Ensure the `--db-url` is a valid PostgreSQL connection string. ```bash goalert --db-url postgres://goalert@localhost/goalert --data-encryption-key super-awesome-secret-key --public-url https://goalert.example.com ``` -------------------------------- ### Run GoAlert Demo Container Source: https://github.com/target/goalert/blob/master/README.md This command starts a GoAlert demo container, making the application accessible at localhost:8081. It's useful for quick testing and integration. The demo container includes default credentials and can be configured to skip initial seed data. ```bash docker run -it --rm -p 8081:8081 goalert/demo ``` -------------------------------- ### Configure GoAlert with Old and New Database URLs (Environment Variables) Source: https://github.com/target/goalert/blob/master/docs/switchover.md This method uses environment variables to configure GoAlert instances with both the old and new database URLs for a switchover. It's an alternative to using command-line flags. ```bash export GOALERT_DB_URL= export GOALERT_DB_URL_NEXT= ``` -------------------------------- ### Enable PostgreSQL pgcrypto Extension Source: https://github.com/target/goalert/blob/master/docs/getting-started.md This SQL command enables the 'pgcrypto' extension in PostgreSQL, which is required by GoAlert for certain cryptographic functions. Ensure you have the necessary privileges to execute this command. ```sql CREATE EXTENSION pgcrypto; ``` -------------------------------- ### Rollback GoAlert to Old Database URL (CLI) Source: https://github.com/target/goalert/blob/master/docs/switchover.md This command is used during rollback to revert GoAlert to using the original database URL. The `--db-url-next` flag is omitted. ```bash goalert --db-url= ``` -------------------------------- ### Generic API Response Example Source: https://github.com/target/goalert/blob/master/web/src/app/documentation/sections/IntegrationKeys.md This JSON object represents a successful response from the generic API when the `Accept` header is set to `application/json`. It includes the Alert ID, Service ID, and a flag indicating if the alert is new. ```json { "AlertID": 10, "ServiceID": "00000000-0000-0000-0000-000000000001", "IsNew": true } ``` -------------------------------- ### Generic API Alert - JSON Body Source: https://github.com/target/goalert/blob/master/web/src/app/documentation/sections/IntegrationKeys.md This example demonstrates sending alert details and metadata using a JSON request body for the generic API. The `meta` field accepts an object for key-value metadata. ```json { "summary": "test", "details": "test", "meta": { "example_key": "example_value", "example_key2": "example_value2" } } ``` -------------------------------- ### Configure GoAlert with Old and New Database URLs (CLI) Source: https://github.com/target/goalert/blob/master/docs/switchover.md This command configures GoAlert instances to use both the current and the next database URLs during a switchover process. It requires the old database URL and the new database URL as arguments. ```bash goalert --db-url= --db-url-next= ``` -------------------------------- ### Rollback GoAlert to Old Database URL (Environment Variables) Source: https://github.com/target/goalert/blob/master/docs/switchover.md This method uses environment variables to roll back GoAlert to the old database configuration. The `GOALERT_DB_URL_NEXT` environment variable is unset. ```bash export GOALERT_DB_URL= unset GOALERT_DB_URL_NEXT ``` -------------------------------- ### Reconfigure GoAlert to Use New Database URL (Environment Variables) Source: https://github.com/target/goalert/blob/master/docs/switchover.md This approach uses environment variables to set the GoAlert instance to use only the new database URL after a switchover. The `GOALERT_DB_URL_NEXT` environment variable is unset. ```bash export GOALERT_DB_URL= unset GOALERT_DB_URL_NEXT ``` -------------------------------- ### Node.js Express Webhook Receiver Example Source: https://context7.com/target/goalert/llms.txt This Node.js script demonstrates how to set up an Express server to receive and process webhook notifications from GoAlert. It logs basic alert information and provides a placeholder for forwarding to other systems. ```javascript // Webhook receiver example (Node.js/Express) const express = require('express'); const app = express(); app.post('/goalert-webhook', express.json(), (req, res) => { const { type, alertID, summary, serviceName, meta } = req.body; console.log(`[${type}] Alert #${alertID}: ${summary}`); console.log(`Service: ${serviceName}`); if (meta) { console.log('Metadata:', meta); } // Forward to your ticketing system, chat platform, etc. // Example: Create JIRA ticket, post to Discord, update status page res.status(200).json({ received: true }); }); app.listen(8080); ``` -------------------------------- ### Add Initial Admin User in GoAlert Source: https://github.com/target/goalert/blob/master/docs/getting-started.md This command is used to add an initial administrator user to GoAlert for basic authentication. It requires specifying the database URL and the admin user's details. The password will be prompted if not provided. ```bash goalert add-user --db-url $GOALERT_DB_URL --admin --user admin --email admin@example.com ``` -------------------------------- ### Query User Notification Configuration (GraphQL) Source: https://context7.com/target/goalert/llms.txt Retrieves a user's notification setup, including their contact methods and notification rules. This GraphQL query requires a user ID as input. ```graphql query UserNotificationSetup($userId: ID!) { user(id: $userId) { id name email contactMethods { id name type formattedValue disabled } notificationRules { id delayMinutes contactMethod { id name type } } } } ``` -------------------------------- ### Reset and Regenerate GoAlert Database Source: https://github.com/target/goalert/blob/master/docs/development-setup.md Resets the GoAlert database, erasing existing data and generating a fresh schema with sample data. It also creates an admin user with default credentials. The `SIZE` parameter can be used to control the amount of sample data generated. ```bash make regendb make regendb SIZE=10 ``` -------------------------------- ### Run GoAlert via Docker Container Source: https://github.com/target/goalert/blob/master/docs/getting-started.md This command shows how to run GoAlert using its Docker image. Environment variables are used to pass the database URL, data encryption key, and public URL. The container is exposed on port 8081. ```bash docker run -p 8081:8081 -e GOALERT_DB_URL=postgres://goalert@localhost/goalert -e GOALERT_DATA_ENCRYPTION_KEY=super-awesome-secret-key -e GOALERT_PUBLIC_URL=https://goalert.example.com goalert/goalert ``` -------------------------------- ### API Session Authentication (Bash) Source: https://context7.com/target/goalert/llms.txt Demonstrates how to authenticate users and manage API sessions using cURL commands. This includes logging in with basic authentication, obtaining a session cookie, querying user information using the cookie, and logging out. It targets the GoAlert API endpoints. ```bash # Login with username/password curl -X POST https://goalert.example.com/api/v2/identity/providers/basic \ -H 'Referer: https://goalert.example.com' \ -d 'username=admin' \ -d 'password=admin123' \ -d 'noRedirect=1' # Response includes session cookie (goalert_session.2) # Use cookie in subsequent requests # Query current user curl -X POST https://goalert.example.com/api/graphql \ -H 'Cookie: goalert_session.2=...' \ -H 'Content-Type: application/json' \ -d '{ "query": "query { user { id name email role isFavorite } }" }' # Logout curl -X POST https://goalert.example.com/api/v2/identity/logout \ -H 'Cookie: goalert_session.2=...' ``` -------------------------------- ### Get GoAlert Session Token Source: https://github.com/target/goalert/blob/master/README.md This command retrieves a session token for the GoAlert demo API. It's useful for automated testing or programmatic access to the API when using the demo container. Ensure you set the correct Referer header. ```bash curl -XPOST -H 'Referer: http://localhost:8081' -d 'username=admin&password=admin123' 'http://localhost:8081/api/v2/identity/providers/basic?noRedirect=1' ``` -------------------------------- ### Set up Heartbeat Monitor for Job Monitoring Source: https://context7.com/target/goalert/llms.txt This mutation creates a heartbeat monitor to track critical jobs. It requires a name, service ID, and a timeout in minutes. The response provides the monitor's ID and a check-in URL. ```graphql # Create heartbeat monitor via GraphQL mutation { createHeartbeatMonitor(input: { name: "Database Backup Job" serviceID: "service-uuid" timeoutMinutes: 65 }) { id href } } ``` ```bash # Add to cron job (every hour at :05) # /etc/cron.d/db-backup 5 * * * * root /usr/local/bin/backup-db.sh && curl -fsS https://goalert.example.com/api/v2/heartbeat/hb-a1b2c3d4-e5f6-7890 || true ``` ```python # From Python script import requests import subprocess try: subprocess.run(['/usr/local/bin/backup-db.sh'], check=True) requests.get('https://goalert.example.com/api/v2/heartbeat/hb-a1b2c3d4-e5f6-7890', timeout=10) except Exception as e: # Alert will be created automatically if heartbeat not received within 65 minutes print(f"Backup failed: {e}") ``` ```graphql # Query heartbeat status query { heartbeatMonitor(id: "hb-uuid") { id name timeoutMinutes lastState lastHeartbeat href } } ``` -------------------------------- ### Create Schedule with Weekly Rotation and Business Hours Source: https://context7.com/target/goalert/llms.txt Defines a GraphQL mutation to create a new on-call schedule. This includes setting up a weekly rotation for users, specifying business hours with weekday filters, and defining the schedule's name, description, and timezone. It returns the created schedule's ID, name, timezone, and associated target rules. ```graphql mutation CreateSchedule { createSchedule(input: { name: "Engineering On-Call - Primary" description: "Primary escalation for engineering incidents" timeZone: "America/New_York" targets: [{ newRotation: { name: "Weekly Engineer Rotation" description: "Rotates weekly starting Monday" type: weekly shiftLength: 1 start: "2024-01-01T00:00:00Z" timeZone: "America/New_York" userIDs: [ "user-alice-uuid", "user-bob-uuid", "user-charlie-uuid" ] } rules: [{ start: "09:00" end: "17:00" weekdayFilter: [false, true, true, true, true, true, false] }] }] }) { id name timeZone targets { target { id name } rules { start end weekdayFilter } } } } ``` -------------------------------- ### Create Escalation Policy with Multi-Step Notifications Source: https://context7.com/target/goalert/llms.txt This GraphQL mutation demonstrates the creation of an escalation policy. It supports multiple notification steps, each with configurable delays and actions like notifying users, Slack channels, schedules, or webhooks. The mutation returns the policy's ID, name, repeat count, and details of its steps and targets. ```graphql mutation CreateEscalationPolicy { createEscalationPolicy(input: { name: "Critical Production Alerts" description: "Escalation for P0 production issues" repeat: 3 steps: [ { delayMinutes: 0 actions: [ { type: user values: [{fieldID: "user-id", value: "oncall-engineer-uuid"}] }, { type: slackChannel values: [{fieldID: "slack-channel-id", value: "C01PROD123"}] } ] }, { delayMinutes: 5 actions: [ { type: schedule values: [{fieldID: "schedule-id", value: "manager-schedule-uuid"}] } ] }, { delayMinutes: 15 actions: [ { type: user values: [{fieldID: "user-id", value: "director-uuid"}] }, { type: webhook values: [ {fieldID: "webhook-url", value: "https://example.com/incident-webhook"}, {fieldID: "webhook-name", value: "PagerDuty Bridge"} ] } ] } ] }) { id name repeat steps { id delayMinutes targets { id name type } } } } ``` -------------------------------- ### Query On-Call Users for a Schedule Source: https://context7.com/target/goalert/llms.txt A GraphQL query to retrieve information about who is currently on-call and for upcoming shifts within a specified schedule. It fetches the user's ID, name, and email, along with shift start and end times for a given date range. This query requires the schedule ID as a variable. ```graphql query OnCallSchedule($scheduleId: ID!) { schedule(id: $scheduleId) { id name assignedTo { id name email } shifts(start: "2024-06-01T00:00:00Z", end: "2024-06-30T23:59:59Z") { userID user { name } start end truncated } } } ``` -------------------------------- ### Add Temporary Override to On-Call Schedule Source: https://context7.com/target/goalert/llms.txt This GraphQL mutation allows for the creation of a temporary override on an existing schedule. It's used to swap out the currently on-call user for a specified duration by adding a replacement user and removing the original user. The mutation returns the override's ID, start, and end times. ```graphql mutation CreateOverride { createUserOverride(input: { scheduleID: "schedule-uuid" start: "2024-06-15T09:00:00Z" end: "2024-06-16T09:00:00Z" addUserID: "user-replacement-uuid" removeUserID: "user-oncall-uuid" }) { id start end } } ``` -------------------------------- ### Configure Prometheus Alertmanager for GoAlert Integration Source: https://context7.com/target/goalert/llms.txt This YAML configuration sets up Prometheus Alertmanager to send alerts to GoAlert via a webhook. It defines routing rules, grouping intervals, and specifies the webhook receiver URL, including an integration token. The example payload shows the structure of alerts sent by Alertmanager, which GoAlert uses to create incidents. ```yaml # Alertmanager configuration (alertmanager.yml) route: receiver: goalert-webhook group_by: ['alertname', 'cluster'] group_wait: 10s group_interval: 10s repeat_interval: 1h receivers: - name: goalert-webhook webhook_configs: - url: 'https://goalert.example.com/api/v2/prometheusalertmanager/incoming?token=integration-key-here' send_resolved: true # Example alert payload sent by Alertmanager { "version": "4", "status": "firing", "alerts": [ { "status": "firing", "labels": { "alertname": "InstanceDown", "instance": "web-01:9090", "job": "node-exporter", "severity": "critical" }, "annotations": { "summary": "Instance web-01:9090 down", "description": "web-01:9090 of job node-exporter has been down for more than 5 minutes." }, "startsAt": "2024-06-15T10:30:00Z", "endsAt": "0001-01-01T00:00:00Z", "generatorURL": "http://prometheus:9090/graph?g0.expr=up+%3D%3D+0", "fingerprint": "1234567890abcdef" } ], "groupLabels": {"alertname": "InstanceDown"}, "commonLabels": {"severity": "critical"}, "commonAnnotations": {}, "externalURL": "http://alertmanager:9093" } # GoAlert creates alert with: # - Summary from annotation.summary or generated from labels # - Details include all labels, annotations, and generatorURL # - Dedup key from fingerprint (auto-closes when resolved: true) ```