This guide will walk through configuring GoAlert for general production use cases.
Most options in GoAlert are configured through the UI in the Admin page. In this guide, when configuring external services,
those options will be referenced in the format:
<Section.Option Name> where
Section is the section/header within the admin page and
Option Name refers to the label of the individual option being referenced.
The only hard requirement for GoAlert is a running Postgres instance/database.
Running Behind a Proxy
When running GoAlert behind a reverse proxy:
- Specify the
GOALERT_HTTP_PREFIXenv var for any instances behind the proxy with a path prefix without the trailing slash
- Ensure the proxy passes the complete path, including prefix, if applicable
- Ensure the proxy passes the original host header (used for validating Twilio requests)
- Ensure the
General.PublicPathcontains the prefix in the URL, if applicable
We recommend using Postgres 11 for new installations as newer features will be used in the future.
GoAlert requires the
pgcrypto extension enabled (you can enable it with
CREATE EXTENSION pgcrypto;).
Upon first startup, it will attempt to enable the extension if it’s not already enabled, but this requires elevated privileges that may not be available
in your setup.
Encryption of Sensitive Data
It is also recommended to set the
--data-encryption-key which is used to encrypt sensitive information (like API keys) before transmitting to the database.
It can be set to any value as it is internally passed through a key derivation function. All instances of GoAlert must be configured to use the same key for things to work properly.
To run GoAlert you can start the binary or the docker container. You will need to specify the
--data-encryption-key you plan to use.
The following examples use
More information on Postgres connection strings can be found here.
goalert --db-url postgres://goalert@localhost/goalert --data-encryption-key super-awesome-secret-key
docker run -p 8081:8081 -e GOALERT_DB_URL=postgres://goalert@localhost/goalert -e GOALERT_DATA_ENCRYPTION_KEY=super-awesome-secret-key goalert/goalert
You should see migrations applied followed by a
Listening. message and an engine cycle start and end.
API Only Mode
When running multiple instances of GoAlert (e.g. in a kubernetes cluster) it is recommended to run a single instance in the default mode, and the rest with the
--api-only flag set.
While it is safe to run multiple “engine” instances simultaneously, it is generally unecessary and can cause unwanted contention. It is useful, however, to run an “engine” instance in separate geographic regions or availability zones. If messages fail to send from one (e.g. network outage), they may be retried in the other this way.
First Time Login
In order to login to GoAlert initially you will need an admin user to start with. Afterwords you may enable other authentication methods through the UI, as well as disable basic (user/pass) login.
This can be done after GoAlert has started for the first time, and is safe to execute while GoAlert is running.
To do this, you may use the
$ 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 switch-over mode). --json Log in JSON format. --stack-traces Enables stack traces with all error logs. -v, --verbose Enable verbose logging.
Be sure to specify the
--admin flag, as well as
--db-url you plan to use.
goalert add-user --db-url $GOALERT_DB_URL --admin --user admin --email firstname.lastname@example.org # Prompt will be given for password
Upon logging in to GoAlert as an admin, you should see a link to the Admin page on the left nav-bar.
|General||Public URL||Set this to the full publicly-routable URL to GoAlert. This is used for callbacks and messages from various features (like voice calls).|
|Auth||Referer URLs||By default GoAlert will only allow authentication from referers on the same host as the current request. You may manually set/restrict which hosts are allowed in environments where the UI is served by a different domain than the API or you wish to further restrict allowed referer hosts.|
|Auth||Disable Basic||This will disable basic authentication. Do not set this until you’ve validated you can login as an admin by other means (e.g. GitHub or OIDC auth)|
GoAlert supports GitHub’s OAuth as an authentication method with the optional ability to limit logins to specified users, organizations or teams.
Using following as examples for required fields:
|Authorization callback URL||
Document Client ID and Client Secret after creation and input into appropriate fields in GoAlert’s Admin page.
Be sure to Enable GitHub authentication and New Users using the toggles and fill out Allowed Users or Allowed Orgs appropriately to restrict access.
Note: If you are limiting logins to an org or team, users will need to manually click on “Grant” access for the required org on first login (before authorizing).
OpenID Connect Authentication (OIDC)
GoAlert supports OpenID Connect as an authentication method.
You should be able to use any OIDC-compliant system as an authentication provider, but we’ll use Google Identity Platform using OAuth 2.0 as an example following the Setting up OAuth 2.0 instructions.
When creating the user consent screen, use the following as examples for required fields:
|Application Homepage link||
When creating the OAuth client ID, use the following as examples for required fields:
|Authorized redirect URIs||
Document Client ID and Client Secret after creation and input into appropriate fields in GoAlert’s Admin page under the OIDC section.
Be sure to Enable OIDC authentication and New Users using the toggles.
GoAlert supports creating alerts by email via Mailgun integration.
From the Admin page in GoAlert, under the
Mailgun section, set your Email Domain and API Key.
The API Key may be found under the Security section in the Mailgun website (click your name in the top bar and select it from the drop down) it is labeled as Private API Key.
To configure Mailgun to forward to GoAlert:
- Go to Receiving
- Click Create Route
- Set Expression Type to
- Set Recipient to
- Check Forward
- In the forward box, enter
- Click Create Route
GoAlert supports generating a notification to a Slack channel as part of the Escalation Policy.
For the time being you will need to create your own Slack app in your workspace for GoAlert to interface with.
To configure Slack, first create a workspace or login to an existing one.
- From https://api.slack.com/apps click Create New App
- Enter a name for your app (e.g.
- Select your workspace
- Click Create App
- In the list under Features, click OAuth & Permissions
- Click on Add New Redirect URL and enter your
<General.Public URL>and click Add
- Under Scopes find Bot Token Scopes, click on Add an OAuth Scope
- Add the following scopes:
- At the top of the page, click Install App to Workspace and Allow
You may now configure the Slack section of the GoAlert Admin page.
- You may find your Access Token under OAuth & Permissions – it is the Bot User OAuth Access Token
- Client ID and Client Secret are found under Basic Information in the App Credentials section.
Be sure to Enable Slack using the toggle.
You must invite the new app (e.g. GoAlert) by typing
/invite @GoAlert in the desired Slack channel(s).
GoAlert relies on bidirectional communication (outbound & inbound) with certain third-party services in order to provide convenient alerting capabilities.
For voice and SMS notifications to function, you will need a notification provider configured. Currently the only supported provider is Twilio.
Get started with a free trial account in order to configure GoAlert. Twilio’s Free Trial Guide details the account setup instructions and limitations. After your trial account is created, click on Get a Trial Number from the Twilio Dashboard. Configure GoAlert to use your trial account by copying & pasting the following fields into the respective GoAlert fields (on the Admin page):
In the Twilio section of the Admin page:
|Twilio Dashboard||GoAlert Admin Page|
|TRIAL NUMBER||From Number|
|ACCOUNT SID||Account SID|
|AUTH TOKEN||Auth Token|
Be sure to Enable Twilio using the toggle.
In order for incoming SMS messages to be processed, the message callback URL must be set within Twilio.
From Twilio Dashboard, navigate to Phone Numbers and click on your trial phone number.
- Under Messaging section, update the webhook URL for A MESSAGE COMES IN to
Twilio trial account limitations (if you decide to upgrade your Twilio account these go away):
- SMS: The message “Sent from your Twilio trail account” is prepended to all SMS messages
- Voice: “You have a trial account…” verbal message before GoAlert message.