From e96035e3de96cb886bbdb8e6fa046654ee2567bc Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Tue, 4 Jun 2019 10:53:55 -0500 Subject: [PATCH 01/25] Changes from old repo Co-authored-by: Mitch Cimenski --- CONTRIBUTING.md | 2 +- README.md | 59 ++++++++--------- docs/development-setup.md | 61 ++++++++++++++++++ docs/getting-started.md | 130 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 217 insertions(+), 35 deletions(-) create mode 100644 docs/development-setup.md create mode 100644 docs/getting-started.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11e5521008..a3baa9d46f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,4 +36,4 @@ Be sure to run `make check` before opening a PR to catch common errors. - Use unit tests as a tool to validate complex logic - New functionality should have a behavioral smoketest at a minimum. For [example](./smoketest/simplenotification_test.go). Documentation on our smoketest framework can be found [here](./smoketest/README.md). -- New Go code should pass `golint`, exported functions/methods should be commented, etc.. +- Go code should follow best practices, exported functions/methods should be commented, etc.. diff --git a/README.md b/README.md index 579f12d025..c77af54542 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,43 @@ # GoAlert -GoAlert is an on-call alerting platform written in Go. +GoAlert provides on-call scheduling, automated escalation, and notifications via SMS and voice to automatically engage the right person, the right way, and at the right time. +These features allow people to promptly respond to any critical issue so that customer impact is prevented or minimized. -## All-In-One (demo) Container +**SCREENSHOT** -The quickest way to explore GoAlert is by using the GoAlert [all-in-one container](https://hub.docker.com/r/goalert/all-in-one). +- Alerts page, alert text indicating triggered by sensu and/or grafana +- admin user so that admin link is visible +- desktop & mobile +- desktop, calendar -- Ensure you have Docker Desktop installed ([Mac](https://docs.docker.com/docker-for-mac/release-notes/) / [Windows](https://docs.docker.com/docker-for-windows/release-notes/)) -- `docker run -it --rm --name goalert-demo -p 8081:8081 goalert/all-in-one` +## Installation -Using a web browser, navigate to `http://localhost:8081` and log in with user `admin` and password `admin123`. +GoAlert is distributed as a single binary with release notes available from the [GitHub Releases](https://github.com/target/goalert/releases) page. -## Development +See our [Getting Started Guide](./docs/getting-started.md) for running GoAlert in a production environment. -Ensure you have docker, Go, node (and yarn), and make installed. +### Quick Start -- If you do not have Postgres installed/configured, first run `make postgres`, GoAlert is built and tested against Postgres 11. -- For the first start, run `make regendb` to migrate and add test data into the DB. This includes an admin user `admin/admin123`. -- To start GoAlert in development mode run `make start`. -- To build the GoAlert binary run `make bin/goalert BUNDLE=1`. +```bash +docker run -it --rm -p 8081:8081 goalert/all-in-one +``` -### Automated Browser Tests +GoAlert will be running at [127.0.0.1:8081](http://127.0.0.1:8081). You can login with `admin/admin123`. -To run automated browser tests, you can start Cypress in one of the following modes: +## Contributing -- `make cy-wide` Widescreen format, in dev mode. -- `make cy-mobile` Mobile format, in dev mode. -- `make cy-wide-prod` Widescreen format, production build. -- `make cy-mobile-prod` Mobile format, production build. +If you'd like to contribute to GoAlert, please see our [Contributing Guidelines](./CONTRIBUTING.md) and the [Development Setup Guide](./docs/development-setup.md). -### Running Smoketests +Please also see our [Code of Conduct](./CODE_OF_CONDUCT.md). -A suite of functional/behavioral tests are maintained for the backend code. These test various APIs and behaviors -of the GoAlert server component. +## Contact Us -Run the full suite with `make smoketest`. +If you need help or have a question, visit the [#GoAlert](https://gophers.slack.com/messages/CJQGZPYLV/) channel on [Gophers Slack](https://gophers.slack.com/) (use the [invite app](https://invite.slack.golangbridge.org/) for access). -### Running Unit Tests +- Vote on existing [Feature Requests](https://github.com/target/goalert/issues?q=is%3Aopen+label%3Afeature-request+sort%3Areactions-%2B1-desc) or submit [a new one](https://github.com/target/goalert/issues/new) +- File a [bug report](https://github.com/target/goalert/issues) +- Report security issues to security@goalert.me -All unit tests can be run with `make test`. +## License -UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`. - -### Setup Postgres - -By default, the development code expects a postgres server configured on port `5432`, with the user and DB `goalert`. - -Alternatively, you can run `make postgres` to configure one in a docker container. - -- You can reset the dev database with `make resetdb` -- You can reset and generate random data with `make regendb`, this includes generating an admin user `admin/admin123` +GoAlert is licensed under the [Apache License, Version 2.0](./LICENSE.md). diff --git a/docs/development-setup.md b/docs/development-setup.md new file mode 100644 index 0000000000..d094844d15 --- /dev/null +++ b/docs/development-setup.md @@ -0,0 +1,61 @@ +## Development Setup + +#### [PostgreSQL](https://www.postgresql.org/) Requirements (Version 11 recommended) + +- A dedicated database (i.e. goalert) +- A user (role) with appropriate (owner) permissions on the database (i.e. goalertuser) +- Enable required extension [pgcrypto](https://www.postgresql.org/docs/11/pgcrypto.html) + +The following is an example of how you may perform the above using native psql statements: + +``` +CREATE DATABASE goalert; +CREATE ROLE goalertuser WITH LOGIN PASSWORD ''; +GRANT ALL PRIVILEGES ON DATABASE goalert TO goalertuser; +``` + +Change database to the newly created database `goalert` and enable `pgcrypto` extension: + +``` +CREATE EXTENSION pgcrypto; +``` + +#### Toolchain Requirements + +Ensure you have Docker, Go, node (and yarn), and make installed. + +- If you do not have Postgres installed/configured, first run `make postgres`, GoAlert is built and tested against Postgres 11. +- For the first start, run `make regendb` to migrate and add test data into the DB. This includes an admin user `admin/admin123`. +- To start GoAlert in development mode run `make start`. +- To build the GoAlert binary run `make bin/goalert BUNDLE=1`. + +### Automated Browser Tests + +To run automated browser tests, you can start Cypress in one of the following modes: + +- `make cy-wide` Widescreen format, in dev mode. +- `make cy-mobile` Mobile format, in dev mode. +- `make cy-wide-prod` Widescreen format, production build. +- `make cy-mobile-prod` Mobile format, production build. + +### Running Smoketests + +A suite of functional/behavioral tests are maintained for the backend code. These test various APIs and behaviors +of the GoAlert server component. + +Run the full suite with `make smoketest`. + +### Running Unit Tests + +All unit tests can be run with `make test`. + +UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`. + +### Setup Postgres + +By default, the development code expects a Postgres server configured on port `5432`, with the user and DB `goalert`. + +Alternatively, you can run `make postgres` to configure one in a docker container. + +- You can reset the dev database with `make resetdb` +- You can reset and generate random data with `make regendb`, this includes generating an admin user `admin/admin123` diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000000..1bbafd6b24 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,130 @@ +## Getting Started + +## Basic Configuration + +After GoAlert is started, additional configuration may be performed from within the application by navigating to the **Admin** page. + +### Exposing GoAlert (TODO) - SMS outbound doesn't require exposing -- is it worth calling this out (test SMS minus status callbacks, SMS responses, etc)? + +GoAlert relies on bidirectional communication (outbound & inbound) with certain third-party services in order to provide convenient alerting capabilities. + +TODO: small blurb about exposing using ngrok / serveo / reverse tunnel of your choice. + +Requirements: + +- Your application must be exposed externally via HTTPS (publicly routable URL) +- The steps to do this depend on multiple factors and are outside the scope of this doc -- recommend serveo / easy mode for evaluation purposes. + +**PUBLIC-URL**: document and use below + +### Twilio + +GoAlert uses [Twilio](https://www.twilio.com/) to generate SMS and voice notifications. +Get started with a [free trial account](https://www.twilio.com/try-twilio) in order to configure GoAlert. +[Twilio's Free Trial Guide](https://support.twilio.com/hc/en-us/articles/223136107-How-does-Twilio-s-Free-Trial-work-) 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): + +| From 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. + +From Twilio Dashboard, navigate to **Phone Numbers** and click on your trial phone number. + +- Under **Voice & Fax** section, update the webhook URL for _A CALL COMES IN_ to **PUBLIC-URL**/api/v2/twilio/call +- Under **Voice & Fax** section, update the webhook URL for _CALL STATUS CHANGES_ to **PUBLIC-URL**/api/v2/twilio/call/status +- Under **Messaging** section, update the webhook URL for _A MESSAGE COMES IN_ to **PUBLIC-URL**/api/v2/twilio/message + +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. + +### Authentication + +#### Basic (should we include this section or omit entirely?) + +GoAlert supports basic authentication. To create an admin user, you can use the GoAlert binary: +`goalert add-user --admin --email admin@example.com --user admin --pass admin123 --db-url='postgres://goalert@/goalert?sslmode=disable'` + +#### GitHub (OAuth) + +GoAlert supports GitHub's OAuth as an authentication method with the optional ability to limit logins to specified users, organizations or teams. + +Follow [GitHub's documentation on creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). + +Using following as examples for required fields: +Application name = **GoAlert** +Homepage URL = **PUBLIC-URL** (from above) +Authorization callback URL = **PUBLIC-URL/api/v2/identity/providers/github/callback** + +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. + +- 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 (OIDC) + +GoAlert supports [OpenID Connect](https://openid.net/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](https://developers.google.com/identity/protocols/OpenIDConnect) following the **Setting up OAuth 2.0** instructions: + +When creating the **user consent screen**, use the following as examples for required fields: +Application name = **GoAlert** +Authorized domains = **PUBLIC-URL** (from above) +Application Homepage link = **PUBLIC-URL** (from above) +Application Privacy Policy link = **PUBLIC-URL** (from above) + +When creating the **OAuth client ID**, use the following as examples for required fields: +Application type = **Web application** +Name = **GoAlert** +Authorized JavaScript origins = **PUBLIC-URL** (from above) +Authorized redirect URIs = **PUBLIC-URL/api/v2/identity/providers/oidc/callback** + +Document **Client ID** and **Client Secret** after creation and input into appropriate fields in GoAlert's Admin page. + +Be sure to **Enable** OIDC authentication and **New Users** using the toggles. +Override Name = **Google** +Issuer URL = **https://accounts.google.com** + +### Mailgun + +Mailgun + +### Slack + +GoAlert supports generating a notification to a Slack channel or user as part of the [Escalation Policy](link to EP doc here). + +To configure Slack, first [create a workspace](https://slack.com/create#email) and a new test channel. + +https://api.slack.com/apps +Create New app + +App Name: GoaLert +select workspace +create app + +permissions -> "Send messages as GoAlert + +chat:write:bot" save changes + +Redirect URL -> new redirect url: **PUBLIC-URL** + +install app to workspace + +auth + +copy access token in admin page + +navigate to basic information +client id / secret +copy to admin page + +TO DO: +cleanup github auth token stuff +cleanup google auth token stuff +cleanup slack app +cleanup mailgun stuff (DNS) From 98d20644e2a84a31d3a8c2d4925ef9159d3d23e3 Mon Sep 17 00:00:00 2001 From: Mitch Cimenski Date: Tue, 4 Jun 2019 11:29:20 -0500 Subject: [PATCH 02/25] adding screenshot --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index c77af54542..9574b92545 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,7 @@ GoAlert provides on-call scheduling, automated escalation, and notifications via SMS and voice to automatically engage the right person, the right way, and at the right time. These features allow people to promptly respond to any critical issue so that customer impact is prevented or minimized. -**SCREENSHOT** - -- Alerts page, alert text indicating triggered by sensu and/or grafana -- admin user so that admin link is visible -- desktop & mobile -- desktop, calendar +![image](https://user-images.githubusercontent.com/23565500/58896528-c1cdb100-86bb-11e9-96f1-a57198ece062.png) ## Installation From e025445cc1732d656477cdcc3c88b0c4f6f26028 Mon Sep 17 00:00:00 2001 From: Mitch Cimenski Date: Tue, 4 Jun 2019 11:35:35 -0500 Subject: [PATCH 03/25] tweak to project description --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 9574b92545..e28ec20d14 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # GoAlert GoAlert provides on-call scheduling, automated escalation, and notifications via SMS and voice to automatically engage the right person, the right way, and at the right time. -These features allow people to promptly respond to any critical issue so that customer impact is prevented or minimized. - ![image](https://user-images.githubusercontent.com/23565500/58896528-c1cdb100-86bb-11e9-96f1-a57198ece062.png) ## Installation From 7e2fb5218f4c11740308b3f4013e33fc801d489b Mon Sep 17 00:00:00 2001 From: Mitch Cimenski Date: Tue, 4 Jun 2019 11:36:20 -0500 Subject: [PATCH 04/25] spacing --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index e28ec20d14..42aa6f544b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # GoAlert -GoAlert provides on-call scheduling, automated escalation, and notifications via SMS and voice to automatically engage the right person, the right way, and at the right time. +GoAlert provides on-call scheduling, automated escalation, and notifications via SMS and voice to automatically engage the right person, the right way, and at the right time. + ![image](https://user-images.githubusercontent.com/23565500/58896528-c1cdb100-86bb-11e9-96f1-a57198ece062.png) ## Installation From 258f34dd078cd8bcd576e3cd5d5413298c57d715 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Tue, 4 Jun 2019 14:36:29 -0500 Subject: [PATCH 05/25] Simplify dev setup documentation --- docs/development-setup.md | 37 ++++++++++++------------------------- 1 file changed, 12 insertions(+), 25 deletions(-) diff --git a/docs/development-setup.md b/docs/development-setup.md index d094844d15..eee8c01d02 100644 --- a/docs/development-setup.md +++ b/docs/development-setup.md @@ -1,30 +1,26 @@ ## Development Setup -#### [PostgreSQL](https://www.postgresql.org/) Requirements (Version 11 recommended) +This guide assumes you have the commands `docker`, `go`, `node`, `yarn`, and `make` installed/available. -- A dedicated database (i.e. goalert) -- A user (role) with appropriate (owner) permissions on the database (i.e. goalertuser) -- Enable required extension [pgcrypto](https://www.postgresql.org/docs/11/pgcrypto.html) +## Postgres -The following is an example of how you may perform the above using native psql statements: +GoAlert is built and tested against Postgres 11. 9.6 should still work as of this writing, but is not recomended as future versions may begin using newer features. -``` -CREATE DATABASE goalert; -CREATE ROLE goalertuser WITH LOGIN PASSWORD ''; -GRANT ALL PRIVILEGES ON DATABASE goalert TO goalertuser; -``` +The easiest way to setup Postgres for development is to run `make postgres`. +This will start a docker container with the correct configuration for the dev environment. -Change database to the newly created database `goalert` and enable `pgcrypto` extension: +### Manual Configuration -``` -CREATE EXTENSION pgcrypto; +If you already have Postgres running locally you can create the `goalert` role. + +```sql +CREATE ROLE goalert WITH LOGIN SUPERUSER; ``` -#### Toolchain Requirements +Currently the dev user must be a superuser to enable `pgcrypto` with `CREATE EXTENSION`. -Ensure you have Docker, Go, node (and yarn), and make installed. +#### Toolchain Requirements -- If you do not have Postgres installed/configured, first run `make postgres`, GoAlert is built and tested against Postgres 11. - For the first start, run `make regendb` to migrate and add test data into the DB. This includes an admin user `admin/admin123`. - To start GoAlert in development mode run `make start`. - To build the GoAlert binary run `make bin/goalert BUNDLE=1`. @@ -50,12 +46,3 @@ Run the full suite with `make smoketest`. All unit tests can be run with `make test`. UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`. - -### Setup Postgres - -By default, the development code expects a Postgres server configured on port `5432`, with the user and DB `goalert`. - -Alternatively, you can run `make postgres` to configure one in a docker container. - -- You can reset the dev database with `make resetdb` -- You can reset and generate random data with `make regendb`, this includes generating an admin user `admin/admin123` From ddac6cc6d9510c68527275f8a19e83644f2306bf Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Tue, 4 Jun 2019 14:36:54 -0500 Subject: [PATCH 06/25] resetdb: don't err if db doesn't exist --- devtools/resetdb/main.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/devtools/resetdb/main.go b/devtools/resetdb/main.go index 222491bcd1..c0bc8f40a8 100644 --- a/devtools/resetdb/main.go +++ b/devtools/resetdb/main.go @@ -491,7 +491,7 @@ func recreateDB() error { } defer db.Close() - _, err = db.Exec("drop database goalert") + _, err = db.Exec("drop database if exists goalert") if err != nil { return err } From 4793656712aab60af1eb57276ceb7d4ea4c3fd35 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 08:36:34 -0500 Subject: [PATCH 07/25] Tweaks for clairity --- docs/development-setup.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/development-setup.md b/docs/development-setup.md index eee8c01d02..6642a650d8 100644 --- a/docs/development-setup.md +++ b/docs/development-setup.md @@ -21,7 +21,7 @@ Currently the dev user must be a superuser to enable `pgcrypto` with `CREATE EXT #### Toolchain Requirements -- For the first start, run `make regendb` to migrate and add test data into the DB. This includes an admin user `admin/admin123`. +- For the first start, run `make regendb` to migrate and add test data into the DB. This includes adding an admin user `admin/admin123`. - To start GoAlert in development mode run `make start`. - To build the GoAlert binary run `make bin/goalert BUNDLE=1`. @@ -34,6 +34,8 @@ To run automated browser tests, you can start Cypress in one of the following mo - `make cy-wide-prod` Widescreen format, production build. - `make cy-mobile-prod` Mobile format, production build. +The Cypress UI should start automatically. + ### Running Smoketests A suite of functional/behavioral tests are maintained for the backend code. These test various APIs and behaviors @@ -45,4 +47,4 @@ Run the full suite with `make smoketest`. All unit tests can be run with `make test`. -UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`. +UI Unit tests are found under the directory of the file being tested, with the same file name, appended with `.test.js`. They can be run independently of the Go unit tests with `make jest`. Watch mode can be enabled with `make jest JEST_ARGS=--watch`. From ae0ca2998765576037da0873b82b721fe543425a Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 08:47:08 -0500 Subject: [PATCH 08/25] Cleanup contributing guidelines a bit --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3baa9d46f..cdb5b1e546 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,13 +4,13 @@ We welcome feature requests, bug reports and contributions for code and document ## Reporting Issues -Reporting bugs can be done in the GitHub [issue tracker](https://github.com/target/goalert/issues). Please search for a possible pre-existing issue first to help prevent duplicates. +Reporting bugs can be done in the GitHub [issue tracker](https://github.com/target/goalert/issues). Please search for existing issues first to help prevent duplicates. Please include the version (`goalert version`) with new bug reports. ## Code Contribution -GoAlert is already used in production environments, so any new changes/features/functionality must (where possible): +GoAlert is already used in production environments, so any new changes/features/functionality must, where possible: - Not alter existing behavior without an explicit config change - Co-exist with older versions without disruption @@ -24,7 +24,7 @@ As an example, things like DB changes/migrations should preserve behavior across Patches are welcome, but we ask that any significant change start as an [issue](https://github.com/target/goalert/issues/new) in the tracker, prefereably before work is started. -Be sure to run `make check` before opening a PR to catch common errors. +Be sure to run `make check` and tests before opening a PR to catch common errors. ### UI Change Guidelines From 25afc3bcf9673dcd9dff0d91b102d6e4808a8812 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 08:47:16 -0500 Subject: [PATCH 09/25] Update smoketest readme --- smoketest/README.md | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/smoketest/README.md b/smoketest/README.md index e2daf56816..1253c888a4 100644 --- a/smoketest/README.md +++ b/smoketest/README.md @@ -1,12 +1,11 @@ -# Notification Smoketest Suite +# Behavioral Smoketest Suite A suite of tests to check that notifications get sent properly. ## Setup 1. Ensure you have postgres running locally, the test suite will create timestamped databases while running. -1. Make sure you have the `goalert` binary installed. (run `make install` from the root of the repo) -1. If you want codesigning (Mac OS, prevents the firewall popup) create a trusted cert named `localdev` (detailed steps are below). +1. Make sure you have the `goalert` binary installed and up-to-date. (run `make install` from the root of the repo) ## Running Tests @@ -17,18 +16,6 @@ To run a single test you can use `go test` from the smoketest directory. ## Creating Tests -- Try to keep the test under 5 minutes, if possible. -- Specify the current migration level when the test is created. This way your initial SQL won't break as migrations are applied in the future, and your test will ensure behavior against newer migrations at the same time. +- Try to keep the test under 1 minute, where possible. +- Use the latest migration when the test is created. - Make sure to call `t.Parallel()` and `defer h.Close()` in your test. - -### Creating a Code Signing Cert (Mac OS Only) - -1. Open `Keychain Access` (press Command+Space and start typing the name) -1. Click the menu `Keychain Access` -> `Certificate Assistant` -> `Create a Certificate ...` -1. Enter `localdev` as the name. -1. Set "Certificate Type" to `Code Signing` -1. Click continue, hit yes on the confirmation window. -1. Go to the `login` keychain and find the new cert. -1. Right-click (or control-click) and select `Get Info`. -1. Click the arrow next to `Trust`. -1. Next to "When using this certificate" select `Always Trust`. From e7d68ca9ec5570959737818d8069bc9c64c85a71 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 13:25:51 -0500 Subject: [PATCH 10/25] add Dockerfile --- devtools/ci/dockerfiles/goalert/Dockerfile | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 devtools/ci/dockerfiles/goalert/Dockerfile diff --git a/devtools/ci/dockerfiles/goalert/Dockerfile b/devtools/ci/dockerfiles/goalert/Dockerfile new file mode 100644 index 0000000000..80b0c3114d --- /dev/null +++ b/devtools/ci/dockerfiles/goalert/Dockerfile @@ -0,0 +1,4 @@ +FROM alpine +RUN apk --no-cache add tzdata ca-certificates +COPY goalert /usr/bin/ +CMD ["/usr/bin/goalert"] From 00f1940afd89ede8caa6b5a70d8851550188ff47 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 13:37:55 -0500 Subject: [PATCH 11/25] fix for regendb getting stuck with empty config --- Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 55c12faa0e..83b4a7ef2d 100644 --- a/Makefile +++ b/Makefile @@ -18,6 +18,8 @@ GIT_COMMIT=$(shell git rev-parse HEAD || echo '?') GIT_TREE=$(shell git diff-index --quiet HEAD -- && echo clean || echo dirty) BUILD_DATE=$(shell date -u +"%Y-%m-%dT%H:%M:%SZ") +DEFAULT_CONFIG='{"Auth":{"RefererURLs":["http://localhost:3030", "http://[::]:3030", "http://127.0.0.1:3030"]}}' + LD_FLAGS+=-X github.com/target/goalert/app.gitCommit=$(GIT_COMMIT) LD_FLAGS+=-X github.com/target/goalert/app.gitVersion=$(GIT_VERSION) LD_FLAGS+=-X github.com/target/goalert/app.gitTreeState=$(GIT_TREE) @@ -137,7 +139,9 @@ web/src/build/vendorPackages.dll.js: web/src/node_modules web/src/webpack.dll.co (cd web/src && node_modules/.bin/webpack --config ./webpack.dll.config.js --progress) config.json.bak: bin/goalert - (bin/goalert get-config "--db-url=$(DB_URL)" 2>/dev/null >config.json.new || echo '{"Auth":{"RefererURLs":["http://localhost:3030", "http://[::]:3030", "http://127.0.0.1:3030"]}}' >config.json.new) && mv config.json.new config.json.bak + @echo Backing up config to config.json.bak + @(bin/goalert get-config "--db-url=$(DB_URL)" 2>/dev/null >config.json.new || echo $(DEFAULT_CONFIG) >config.json.new) && mv config.json.new config.json.bak + @(if [ "`cat config.json.bak`" = "{}" ]; then echo $(DEFAULT_CONFIG) >config.json.bak; fi) postgres: docker run -d \ From 90e53418f1e7e4b85de3dc44c4dd0819b3e982c1 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 15:47:18 -0500 Subject: [PATCH 12/25] first pass at getting started cleanup --- docs/getting-started.md | 203 +++++++++++++++++++++++++--------------- 1 file changed, 130 insertions(+), 73 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 1bbafd6b24..3e3870a553 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,130 +1,187 @@ -## Getting Started +# Getting Started -## Basic Configuration +GoAlert requires a Postgres database with 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. -After GoAlert is started, additional configuration may be performed from within the application by navigating to the **Admin** page. +It is also recomended to set the `--data-encryption-key` which is used to encrypt sensitive information before transmitting to the database. It can be set to any value, keep it secret. -### Exposing GoAlert (TODO) - SMS outbound doesn't require exposing -- is it worth calling this out (test SMS minus status callbacks, SMS responses, etc)? +## Running GoAlert -GoAlert relies on bidirectional communication (outbound & inbound) with certain third-party services in order to provide convenient alerting capabilities. +To run GoAlert you can start the binary or the docker container. You will need to specify the `--db-url` and `--data-encryption-key` you plan to use. -TODO: small blurb about exposing using ngrok / serveo / reverse tunnel of your choice. +The following examples use `postgres://goalert@localhost/goalert` and `super-awesome-secret-key` respectively. -Requirements: +Binary: -- Your application must be exposed externally via HTTPS (publicly routable URL) -- The steps to do this depend on multiple factors and are outside the scope of this doc -- recommend serveo / easy mode for evaluation purposes. +```bash +goalert --db-url postgres://goalert@localhost/goalert --data-encryption-key super-awesome-secret-key +``` -**PUBLIC-URL**: document and use below +Docker: -### Twilio +```bash +docker run -p 8081:8081 -e GOALERT_DB_URL=postgres://goalert@localhost/goalert -e GOALERT_DATA_ENCRYPTION_KEY=super-awesome-secret-key goalert/goalert +``` -GoAlert uses [Twilio](https://www.twilio.com/) to generate SMS and voice notifications. -Get started with a [free trial account](https://www.twilio.com/try-twilio) in order to configure GoAlert. -[Twilio's Free Trial Guide](https://support.twilio.com/hc/en-us/articles/223136107-How-does-Twilio-s-Free-Trial-work-) 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): +You should see migrations applied followed by a `Listening.` message and an engine cycle start and end. -| From Twilio Dashboard | GoAlert Admin Page | -| --------------------- | ------------------ | -| TRIAL NUMBER | From Number | -| ACCOUNT SID | Account SID | -| AUTH TOKEN | Auth Token | +## First Time Login -Be sure to **Enable** Twilio using the toggle. +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. -From Twilio Dashboard, navigate to **Phone Numbers** and click on your trial phone number. +This can be done after GoAlert has started for the first time, and is safe to execute while GoAlert is running. -- Under **Voice & Fax** section, update the webhook URL for _A CALL COMES IN_ to **PUBLIC-URL**/api/v2/twilio/call -- Under **Voice & Fax** section, update the webhook URL for _CALL STATUS CHANGES_ to **PUBLIC-URL**/api/v2/twilio/call/status -- Under **Messaging** section, update the webhook URL for _A MESSAGE COMES IN_ to **PUBLIC-URL**/api/v2/twilio/message +To do this, you may use the `add-user` subcommand: -Twilio trial account limitations (if you decide to upgrade your Twilio account these go away): +```bash +$ goalert add-user -h +Adds a user for basic authentication. -- 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. +Usage: + goalert add-user [flags] -### Authentication +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. -#### Basic (should we include this section or omit entirely?) +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. +``` -GoAlert supports basic authentication. To create an admin user, you can use the GoAlert binary: -`goalert add-user --admin --email admin@example.com --user admin --pass admin123 --db-url='postgres://goalert@/goalert?sslmode=disable'` +Be sure to specify the `--admin` flag, as well as `--db-url` you plan to use. -#### GitHub (OAuth) +Example usage: + +```bash +goalert add-user --db-url $GOALERT_DB_URL --admin --user admin --email admin@example.com +# Prompt will be given for password +``` + +## Configuration + +Upon logging in to GoAlert as an admin, you should see a link to the **Admin** page on the left nav-bar. + +| Section | Value | Description | +| ------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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) | + +### GitHub Authentication GoAlert supports GitHub's OAuth as an authentication method with the optional ability to limit logins to specified users, organizations or teams. Follow [GitHub's documentation on creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). Using following as examples for required fields: -Application name = **GoAlert** -Homepage URL = **PUBLIC-URL** (from above) -Authorization callback URL = **PUBLIC-URL/api/v2/identity/providers/github/callback** +| Field | Example Value | +| --- | --- | +| Application name | `GoAlert` | +| Homepage URL | `` | +| Authorization callback URL | `/api/v2/identity/providers/github/callback` | 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. +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). -- 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) -#### OpenID Connect (OIDC) +GoAlert supports [OpenID Connect](https://openid.net/connect/) as an authentication method. -GoAlert supports [OpenID Connect](https://openid.net/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](https://developers.google.com/identity/protocols/OpenIDConnect) following the **Setting up OAuth 2.0** instructions: +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](https://developers.google.com/identity/protocols/OpenIDConnect) 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 name = **GoAlert** -Authorized domains = **PUBLIC-URL** (from above) -Application Homepage link = **PUBLIC-URL** (from above) -Application Privacy Policy link = **PUBLIC-URL** (from above) +| Field | Example Value | +| --- | --- | +| Application name | `GoAlert` | +| Authorized domains | `` | +| Application Homepage link | `` | +| Application Privacy Policy link | `` | When creating the **OAuth client ID**, use the following as examples for required fields: -Application type = **Web application** -Name = **GoAlert** -Authorized JavaScript origins = **PUBLIC-URL** (from above) -Authorized redirect URIs = **PUBLIC-URL/api/v2/identity/providers/oidc/callback** -Document **Client ID** and **Client Secret** after creation and input into appropriate fields in GoAlert's Admin page. +| Field | Example Value | +| ----------------------------- | -------------------------------------------------------------- | +| Application type | `Web application` | +| Name | `GoAlert` | +| Authorized JavaScript origins | `` | +| Authorized redirect URIs | `/api/v2/identity/providers/oidc/callback` | + +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. -Override Name = **Google** -Issuer URL = **https://accounts.google.com** + +- Set `Override Name` to `Google` (not required). +- Set `Issuer URL` to `https://accounts.google.com` ### Mailgun -Mailgun +TODO ### Slack GoAlert supports generating a notification to a Slack channel or user as part of the [Escalation Policy](link to EP doc here). -To configure Slack, first [create a workspace](https://slack.com/create#email) and a new test channel. +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](https://slack.com/create#email) or login to an existing one. + +1. From https://api.slack.com/apps click **Create New App** +1. Enter a name for your app (e.g. `GoAlert`) +1. Select your workspace +1. Click **Create App** +1. Under **Bot Users** click **Add a Bot User** configure as desired and click **Add Bot User** +1. Under **OAuth & Permissions** add your `` with **Add New Redirect URL** +1. Under **OAuth & Permissions** click **Install App to Workspace** and complete the flow + +You may now configure the **Slack** section of the 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. + +### Twilio + +GoAlert relies on bidirectional communication (outbound & inbound) with certain third-party services in order to provide convenient alerting capabilities. -https://api.slack.com/apps -Create New app +For voice and SMS notifications to function, you will need a notification provider configured. Currently the only supported provider is Twilio. -App Name: GoaLert -select workspace -create app +Get started with a [free trial account](https://www.twilio.com/try-twilio) in order to configure GoAlert. +[Twilio's Free Trial Guide](https://support.twilio.com/hc/en-us/articles/223136107-How-does-Twilio-s-Free-Trial-work-) 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): -permissions -> "Send messages as GoAlert +In the **Twilio** section of the Admin page: -chat:write:bot" save changes +| Twilio Dashboard | GoAlert Admin Page | +| ---------------- | ------------------ | +| TRIAL NUMBER | From Number | +| ACCOUNT SID | Account SID | +| AUTH TOKEN | Auth Token | -Redirect URL -> new redirect url: **PUBLIC-URL** +Be sure to **Enable** Twilio using the toggle. -install app to workspace +In order for incoming SMS messages to be processed, the message callback URL must be set within Twilio. -auth +From Twilio Dashboard, navigate to **Phone Numbers** and click on your trial phone number. -copy access token in admin page +- Under **Messaging** section, update the webhook URL for _A MESSAGE COMES IN_ to `/api/v2/twilio/message` -navigate to basic information -client id / secret -copy to admin page +Twilio trial account limitations (if you decide to upgrade your Twilio account these go away): -TO DO: -cleanup github auth token stuff -cleanup google auth token stuff -cleanup slack app -cleanup mailgun stuff (DNS) +- 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. From 8c553923100183503122b7cba837c43885c5c72b Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 15:50:21 -0500 Subject: [PATCH 13/25] fix formatting --- docs/getting-started.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 3e3870a553..49f8f14a63 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -85,10 +85,11 @@ GoAlert supports GitHub's OAuth as an authentication method with the optional ab Follow [GitHub's documentation on creating an OAuth App](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/). Using following as examples for required fields: -| Field | Example Value | -| --- | --- | -| Application name | `GoAlert` | -| Homepage URL | `` | + +| Field | Example Value | +| -------------------------- | ---------------------------------------------------------------- | +| Application name | `GoAlert` | +| Homepage URL | `` | | Authorization callback URL | `/api/v2/identity/providers/github/callback` | Document **Client ID** and **Client Secret** after creation and input into appropriate fields in GoAlert's Admin page. @@ -104,11 +105,12 @@ GoAlert supports [OpenID Connect](https://openid.net/connect/) as an authenticat 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](https://developers.google.com/identity/protocols/OpenIDConnect) 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: -| Field | Example Value | -| --- | --- | -| Application name | `GoAlert` | -| Authorized domains | `` | -| Application Homepage link | `` | + +| Field | Example Value | +| ------------------------------- | ---------------------- | +| Application name | `GoAlert` | +| Authorized domains | `` | +| Application Homepage link | `` | | Application Privacy Policy link | `` | When creating the **OAuth client ID**, use the following as examples for required fields: From 70eaadffbeabfe5345a5a117a630616d7ffbaf39 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Wed, 5 Jun 2019 15:52:50 -0500 Subject: [PATCH 14/25] mailgun description --- docs/getting-started.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/getting-started.md b/docs/getting-started.md index 49f8f14a63..e70ea52547 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -131,6 +131,8 @@ Be sure to **Enable** OIDC authentication and **New Users** using the toggles. ### Mailgun +GoAlert supports creating alerts by email via Mailgun integration. + TODO ### Slack From 6fe55753ebcf260f2ea735a51545599778a9110e Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Thu, 6 Jun 2019 11:54:52 -0500 Subject: [PATCH 15/25] add mailgun section --- docs/getting-started.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index e70ea52547..74a46aee3c 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -133,7 +133,18 @@ Be sure to **Enable** OIDC authentication and **New Users** using the toggles. GoAlert supports creating alerts by email via Mailgun integration. -TODO +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: + +1. Go to **Routes** +1. Click **Create Route** +1. Set **Expression Type** to `Match Recipient` +1. Set **Recipient** to `*@` +1. Check **Forward** +1. In the forward box, enter `/api/v2/mailgun/incoming` +1. Click **Create Route** ### Slack From 70a2086408a46431cea0f99aca72a39063293871 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Thu, 6 Jun 2019 12:09:18 -0500 Subject: [PATCH 16/25] add note about API-only mode --- docs/getting-started.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 74a46aee3c..32dd7dbbf7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,6 +1,19 @@ # Getting Started -GoAlert requires a Postgres database with the `pgcrypto` extension enabled (you can enable it with `CREATE EXTENSION 'pgcrypto'`). +This guide will walk through configuring GoAlert for use and integration with services for things like sending SMS messages, +making voice calls, triggering alerts by email, and authentication. + +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: `` 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 and it's associated connection URL. + +## Database + +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. @@ -26,6 +39,13 @@ docker run -p 8081:8081 -e GOALERT_DB_URL=postgres://goalert@localhost/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. From f9a46ff0eb27bce05f28af0c2148cf467fb3b325 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 08:41:40 -0500 Subject: [PATCH 17/25] attempt to start postgres container on failure --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 4725c61b66..8ca30d19a5 100644 --- a/Makefile +++ b/Makefile @@ -146,7 +146,7 @@ postgres: -e POSTGRES_USER=goalert \ --name goalert-postgres \ -p 5432:5432 \ - postgres:11-alpine + postgres:11-alpine || docker start goalert-postgres regendb: bin/goalert migrate/inline_data_gen.go config.json.bak go run ./devtools/resetdb --with-rand-data From 1bbea8ea46d1d26810d907683ccf1f5b5825d818 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 08:48:10 -0500 Subject: [PATCH 18/25] update README with feedback --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 42aa6f544b..80f9755c35 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # GoAlert -GoAlert provides on-call scheduling, automated escalation, and notifications via SMS and voice to automatically engage the right person, the right way, and at the right time. +GoAlert provides on-call scheduling, automated escalations and notifications (like SMS or voice calls) to automatically engage the right person, the right way, and at the right time. ![image](https://user-images.githubusercontent.com/23565500/58896528-c1cdb100-86bb-11e9-96f1-a57198ece062.png) @@ -16,7 +16,7 @@ See our [Getting Started Guide](./docs/getting-started.md) for running GoAlert i docker run -it --rm -p 8081:8081 goalert/all-in-one ``` -GoAlert will be running at [127.0.0.1:8081](http://127.0.0.1:8081). You can login with `admin/admin123`. +GoAlert will be running at [localhost:8081](http://localhost:8081). You can login with `admin/admin123`. ## Contributing @@ -26,7 +26,9 @@ Please also see our [Code of Conduct](./CODE_OF_CONDUCT.md). ## Contact Us -If you need help or have a question, visit the [#GoAlert](https://gophers.slack.com/messages/CJQGZPYLV/) channel on [Gophers Slack](https://gophers.slack.com/) (use the [invite app](https://invite.slack.golangbridge.org/) for access). +If you need help or have a question, the `#goalert` Slack channel is available on [gophers.slack.com](https://gophers.slack.com/messages/goalert/). + +To access Gophers Slack and the `#goalert` channel, you will need an invitation. You request one through the automated process here: https://invite.slack.golangbridge.org/ - Vote on existing [Feature Requests](https://github.com/target/goalert/issues?q=is%3Aopen+label%3Afeature-request+sort%3Areactions-%2B1-desc) or submit [a new one](https://github.com/target/goalert/issues/new) - File a [bug report](https://github.com/target/goalert/issues) From 4e27c52ace7b0907b73645dbcd1af652089852a7 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 08:49:36 -0500 Subject: [PATCH 19/25] use full name in header --- docs/development-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development-setup.md b/docs/development-setup.md index 6642a650d8..25c4609076 100644 --- a/docs/development-setup.md +++ b/docs/development-setup.md @@ -2,9 +2,9 @@ This guide assumes you have the commands `docker`, `go`, `node`, `yarn`, and `make` installed/available. -## Postgres +## Database (PostgreSQL) -GoAlert is built and tested against Postgres 11. 9.6 should still work as of this writing, but is not recomended as future versions may begin using newer features. +GoAlert is built and tested against Postgres 11. Version 9.6 should still work as of this writing, but is not recomended as future versions may begin using newer features. The easiest way to setup Postgres for development is to run `make postgres`. This will start a docker container with the correct configuration for the dev environment. From 831553f216fd586538f4a1414dbf3a7e2592d755 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 08:51:00 -0500 Subject: [PATCH 20/25] shorten getting started intro --- docs/getting-started.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 32dd7dbbf7..370fa7d31e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,6 @@ # Getting Started -This guide will walk through configuring GoAlert for use and integration with services for things like sending SMS messages, -making voice calls, triggering alerts by email, and authentication. +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: `` where `Section` is the section/header within the admin page and From b3873a451259e863bc6faa49ff6849a553a0d0dd Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 08:54:38 -0500 Subject: [PATCH 21/25] tweaks to postgres getting started info --- docs/getting-started.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 370fa7d31e..3c3ebb3d6b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,13 +6,13 @@ Most options in GoAlert are configured through the UI in the Admin page. In this those options will be referenced in the format: `` 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 and it's associated connection URL. +The only hard requirement for GoAlert is a running Postgres instance/database. ## Database 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'`). +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. @@ -24,6 +24,8 @@ To run GoAlert you can start the binary or the docker container. You will need t The following examples use `postgres://goalert@localhost/goalert` and `super-awesome-secret-key` respectively. +More information on Postgres connection strings can be found [here](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING). + Binary: ```bash From 09c8f2c17ada9705c72146c08aa1707fbfd0908d Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 09:02:19 -0500 Subject: [PATCH 22/25] add link to effective Go in CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cdb5b1e546..67a0e2159f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,4 +36,4 @@ Be sure to run `make check` and tests before opening a PR to catch common errors - Use unit tests as a tool to validate complex logic - New functionality should have a behavioral smoketest at a minimum. For [example](./smoketest/simplenotification_test.go). Documentation on our smoketest framework can be found [here](./smoketest/README.md). -- Go code should follow best practices, exported functions/methods should be commented, etc.. +- Go code should [follow best practices](https://golang.org/doc/effective_go.html), exported functions/methods should be commented, etc.. From 7eec623ae70dea9f2589d2ed46db7c56153070f9 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 10:26:14 -0500 Subject: [PATCH 23/25] add links to more info for tests --- docs/development-setup.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/development-setup.md b/docs/development-setup.md index 25c4609076..37eed42e20 100644 --- a/docs/development-setup.md +++ b/docs/development-setup.md @@ -36,6 +36,8 @@ To run automated browser tests, you can start Cypress in one of the following mo The Cypress UI should start automatically. +More information about browser tests can be found [here](../web/src/cypress/README.md). + ### Running Smoketests A suite of functional/behavioral tests are maintained for the backend code. These test various APIs and behaviors @@ -43,6 +45,8 @@ of the GoAlert server component. Run the full suite with `make smoketest`. +More information about smoketests can be found [here](../smoketest/README.md). + ### Running Unit Tests All unit tests can be run with `make test`. From c4e0f89b1fb9c612bffb9b3ca8f17a05d1ef0b57 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 10:30:54 -0500 Subject: [PATCH 24/25] add go unit test example --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67a0e2159f..8e8c5d6cf9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,6 +34,6 @@ Be sure to run `make check` and tests before opening a PR to catch common errors ### Backend Change Guidelines -- Use unit tests as a tool to validate complex logic +- Use unit tests as a tool to validate complex logic. For [example](./schedule/rule/weekdayfilter_test.go). - New functionality should have a behavioral smoketest at a minimum. For [example](./smoketest/simplenotification_test.go). Documentation on our smoketest framework can be found [here](./smoketest/README.md). - Go code should [follow best practices](https://golang.org/doc/effective_go.html), exported functions/methods should be commented, etc.. From 816b0af4ff63ef58a57487945f212b8b27c34e41 Mon Sep 17 00:00:00 2001 From: Nathaniel Caza Date: Fri, 7 Jun 2019 10:34:14 -0500 Subject: [PATCH 25/25] update label query in README Co-Authored-By: Arundhati Rao --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 80f9755c35..4776750264 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ If you need help or have a question, the `#goalert` Slack channel is available o To access Gophers Slack and the `#goalert` channel, you will need an invitation. You request one through the automated process here: https://invite.slack.golangbridge.org/ -- Vote on existing [Feature Requests](https://github.com/target/goalert/issues?q=is%3Aopen+label%3Afeature-request+sort%3Areactions-%2B1-desc) or submit [a new one](https://github.com/target/goalert/issues/new) +- Vote on existing [Feature Requests](https://github.com/target/goalert/issues?q=is%3Aopen+label%3Aenhancement+sort%3Areactions-%2B1-desc) or submit [a new one](https://github.com/target/goalert/issues/new) - File a [bug report](https://github.com/target/goalert/issues) - Report security issues to security@goalert.me