From ec0c0facc4029c020ffd1d2383c9e0f1e6e3c116 Mon Sep 17 00:00:00 2001 From: Chung-Yi Chi Date: Thu, 31 Dec 2020 15:40:46 -0500 Subject: [PATCH 1/3] doc: convert links to references --- README.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 4ef22c3..20b1dda 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# APRd (Artsy Real-time Dashboard) [![CircleCI](https://circleci.com/gh/artsy/aprd.svg?style=svg)](https://circleci.com/gh/artsy/aprd) +# APRd (Artsy Real-time Dashboard) [![CircleCI][ci_badge]][circleci] -APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir](https://elixir-lang.org/) on [Phoenix Framework](https://phoenixframework.org/). For it's real-time dashboard it's using [Phoenix Live View](https://github.com/phoenixframework/phoenix_live_view) to be able to provide websocket based pages that can update in real-time based on updates on the server side. +APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir][elixir] on [Phoenix Framework][phoenixframework]. For it's real-time dashboard it's using [Phoenix Live View][phoenix_live_view] to be able to provide websocket based pages that can update in real-time based on updates on the server side. ## Meta @@ -10,8 +10,8 @@ APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir](https://el - Production: https://aprd.artsy.net - Staging: https://aprd-staging.artsy.net - GitHub: https://github.com/artsy/aprd/ -- CI: [CircleCI](https://circleci.com/gh/artsy/apr-dashboard); merged PRs to artsy/apr-dashboard#master are automatically deployed to staging. PRs from `staging` to `release` are automatically deployed to production. [Start a deploy...](https://github.com/artsy/apr-dashboard/compare/release...staging?expand=1) -- Point People: [@jpotts244](https://github.com/jpotts244), [@zephraph][zephraph] +- CI: [CircleCI][circleci]; merged PRs to artsy/aprd#master are automatically deployed to staging. PRs from `staging` to `release` are automatically deployed to production. [Start a deploy...][deploy] +- Point People: [@jpotts244][jpotts244], [@zephraph][zephraph] ## Setup @@ -21,7 +21,7 @@ APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir](https://el ``` $ git clone git@github.com:your-github-username/apr-dashboard.git ``` -- Install [Elixir](https://elixir-lang.org/install.html) +- Install [Elixir][elixir_install] Using Homebrew ``` @@ -33,22 +33,22 @@ APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir](https://el $ command not found: mix ``` -- Ensure you have [postgres](https://www.postgresql.org/download/) and [rabbitmq](https://www.rabbitmq.com/download.html) installed +- Ensure you have [postgres][postgresql] and [rabbitmq][rabbitmq] installed - Once installed make sure both are running on your local machine (using Homebrew) ``` $ brew services start postgresql $ brew services start rabbitmq - ``` + ``` - Install dependencies with `mix deps.get` - Create and migrate your database with `mix ecto.setup` - Install Node.js dependencies with `cd assets && npm install` - Copy `.env.example` to `.env` -- We use [Phoenix Live View](https://github.com/phoenixframework/phoenix_live_view) for our real-time data presentation. Make sure to set `SECRET_SALT` in your `.env`. Generate a secret salt with: +- We use [Phoenix Live View][phoenix_live_view] for our real-time data presentation. Make sure to set `SECRET_SALT` in your `.env`. Generate a secret salt with: - `mix phx.gen.secret 32` - Make set your RabbitMQ setting in `.env` - Start Phoenix endpoint with `mix phx.server` -Now you can visit [`localhost:4000/dashboard`](http://localhost:4000/dashboard) from your browser. +Now you can visit [`localhost:4000/dashboard`][localhost] from your browser. ## Running the test suite @@ -68,7 +68,6 @@ APRd listens on RabbitMQ for different topics. Once it receives a new event, it Whenever we receive a new event, after storing the event locally, we use Phoenix's local PUB/SUB to broadcast we received an event. And then our websocket live views are listening on this internal PUB/SUB and they update the data on listening Webosckets reflecting the latest event updated. -[zephraph]: https://github.com/zephraph ## Artsy Slack Setup @@ -81,3 +80,16 @@ APRd is used to power critical alerting workflows in Artsy's Slack organization. 1. Re-generate the bot API token (via https://artsy.slack.com/services/70260076245) 1. Run `hokusai [staging|production] env set SLACK_API_TOKEN=token-from-step-4` 1. Run `hokusai [staging|production] refresh` + +[ci_badge]: https://circleci.com/gh/artsy/aprd.svg?style=svg +[circleci]: https://circleci.com/gh/artsy/aprd +[elixir]: https://elixir-lang.org/ +[elixir_install]: https://elixir-lang.org/install.html +[phoenix_live_view]: https://github.com/phoenixframework/phoenix_live_view +[deploy]: https://github.com/artsy/apr-dashboard/compare/release...staging?expand=1 +[jpotts244]: https://github.com/jpotts244 +[zephraph]: https://github.com/zephraph +[localhost]: http://localhost:4000/dashboard +[phoenixframework]: https://phoenixframework.org/ +[postgresql]: https://www.postgresql.org/download/ +[rabbitmq]: https://www.rabbitmq.com/download.html From afe222ded5ea4d71249cfd6d976795730129453c Mon Sep 17 00:00:00 2001 From: Chung-Yi Chi Date: Thu, 31 Dec 2020 15:51:08 -0500 Subject: [PATCH 2/3] doc: wrap lines at 120 characters --- README.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 20b1dda..c4928fe 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ # APRd (Artsy Real-time Dashboard) [![CircleCI][ci_badge]][circleci] -APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir][elixir] on [Phoenix Framework][phoenixframework]. For it's real-time dashboard it's using [Phoenix Live View][phoenix_live_view] to be able to provide websocket based pages that can update in real-time based on updates on the server side. +APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir][elixir] on [Phoenix Framework][phoenixframework]. +For it's real-time dashboard it's using [Phoenix Live View][phoenix_live_view] to be able to provide websocket based +pages that can update in real-time based on updates on the server side. ## Meta @@ -10,7 +12,8 @@ APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir][elixir] on - Production: https://aprd.artsy.net - Staging: https://aprd-staging.artsy.net - GitHub: https://github.com/artsy/aprd/ -- CI: [CircleCI][circleci]; merged PRs to artsy/aprd#master are automatically deployed to staging. PRs from `staging` to `release` are automatically deployed to production. [Start a deploy...][deploy] +- CI: [CircleCI][circleci]; merged PRs to artsy/aprd#master are automatically deployed to staging. PRs from `staging` to + `release` are automatically deployed to production. [Start a deploy...][deploy] - Point People: [@jpotts244][jpotts244], [@zephraph][zephraph] ## Setup @@ -43,7 +46,8 @@ APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir][elixir] on - Create and migrate your database with `mix ecto.setup` - Install Node.js dependencies with `cd assets && npm install` - Copy `.env.example` to `.env` -- We use [Phoenix Live View][phoenix_live_view] for our real-time data presentation. Make sure to set `SECRET_SALT` in your `.env`. Generate a secret salt with: +- We use [Phoenix Live View][phoenix_live_view] for our real-time data presentation. Make sure to set `SECRET_SALT` in + your `.env`. Generate a secret salt with: - `mix phx.gen.secret 32` - Make set your RabbitMQ setting in `.env` - Start Phoenix endpoint with `mix phx.server` @@ -64,19 +68,24 @@ $ mix test test/apr/views/commerce/commerce_transaction_slack_view_test.exs ## Architecture -APRd listens on RabbitMQ for different topics. Once it receives a new event, it will store a copy of that event locally in it's database so we can later process the data and provide detailed and aggregated data. - -Whenever we receive a new event, after storing the event locally, we use Phoenix's local PUB/SUB to broadcast we received an event. And then our websocket live views are listening on this internal PUB/SUB and they update the data on listening Webosckets reflecting the latest event updated. +APRd listens on RabbitMQ for different topics. Once it receives a new event, it will store a copy of that event locally +in it's database so we can later process the data and provide detailed and aggregated data. +Whenever we receive a new event, after storing the event locally, we use Phoenix's local PUB/SUB to broadcast we +received an event. And then our websocket live views are listening on this internal PUB/SUB and they update the data on +listening Webosckets reflecting the latest event updated. ## Artsy Slack Setup -APRd is used to power critical alerting workflows in Artsy's Slack organization. After a recent incident where APRd lost its connection to Artsy's Slack, we surfaced the following steps to re-connect the digital assets needed to get it all working: +APRd is used to power critical alerting workflows in Artsy's Slack organization. After a recent incident where APRd lost +its connection to Artsy's Slack, we surfaced the following steps to re-connect the digital assets needed to get it all +working: 1. Re-enable the `/apr` slash command: https://artsy.slack.com/services/B227A48KX 1. Re-enable the `@apr / APR Announcer` Slack bot: https://artsy.slack.com/services/70260076245 1. Re-invite the Bot in (2) to the appropriate Slack channels - - You can check your work by reading the Channels attribute on the Bot show page: https://artsy.slack.com/services/70260076245 + - You can check your work by reading the Channels attribute on the Bot show page: + https://artsy.slack.com/services/70260076245 1. Re-generate the bot API token (via https://artsy.slack.com/services/70260076245) 1. Run `hokusai [staging|production] env set SLACK_API_TOKEN=token-from-step-4` 1. Run `hokusai [staging|production] refresh` From 953968f26dc035bf69f331a6b72935fc4cc37d45 Mon Sep 17 00:00:00 2001 From: Chung-Yi Chi Date: Fri, 1 Jan 2021 11:19:01 -0500 Subject: [PATCH 3/3] doc: update README and .env.example for functional local setup --- .env.example | 18 +++++++++++------- README.md | 37 +++++++++++++++---------------------- 2 files changed, 26 insertions(+), 29 deletions(-) diff --git a/.env.example b/.env.example index c2f257a..8c608c0 100644 --- a/.env.example +++ b/.env.example @@ -1,13 +1,17 @@ -SECRET_SALT= +ARTSY_CLIENT_ID=REPLACE +ARTSY_CLIENT_SECRET=REPLACE +ARTSY_INTERNAL_SECRET=REPLACE +ARTSY_TOKEN_AUD=REPLACE +ARTSY_URL=https://stagingapi.artsy.net +EXCHANGE_URL=https://exchange-staging.artsy.net +GRAVITY_API_TOKEN=REPLACE +GRAVITY_API_URL=https://stagingapi.artsy.net/api +METAPHYSICS_URL=https://metaphysics-staging.artsy.net RABBITMQ_HOST= RABBITMQ_PASSWORD= RABBITMQ_PORT= RABBITMQ_USER= -SECRET_KEY_BASE= -AUTH_USER= -AUTH_PASS= -AUTH_REALM=Admin Area -METAPHYSICS_URL=https://metaphysics-staging.artsy.net -EXCHANGE_URL=https://exchange-staging.artsy.net +SECRET_KEY_BASE=REPLACE +SECRET_SALT=REPLACE SLACK_API_TOKEN=REPLACE SLACK_SLASH_COMMAND_TOKEN=REPLACE diff --git a/README.md b/README.md index c4928fe..835f3e9 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,10 @@ APRd (aka. APR dashboard), is a real-time dashboard built in [Elixir][elixir] on For it's real-time dashboard it's using [Phoenix Live View][phoenix_live_view] to be able to provide websocket based pages that can update in real-time based on updates on the server side. +APRd also powers the Slack notification workflows at Artsy. It consumes RabbitMQ events, composes Slack messages, and +notifies subscribing Slack channels. Users can subscribe to topics from a Slack channel with the `/apr` Slack slash +command that APRd provides. + ## Meta - State: production @@ -18,52 +22,41 @@ pages that can update in real-time based on updates on the server side. ## Setup -- Fork the project to your GitHub account - -- Clone your fork: - ``` - $ git clone git@github.com:your-github-username/apr-dashboard.git - ``` +- Clone the project - Install [Elixir][elixir_install] Using Homebrew ``` - $ brew update - $ brew install elixir + brew update + brew install elixir ``` - - Ensure that everything installed correctly by running `mix`, you should not see the following error - ``` - $ command not found: mix - ``` - - Ensure you have [postgres][postgresql] and [rabbitmq][rabbitmq] installed - Once installed make sure both are running on your local machine (using Homebrew) ``` - $ brew services start postgresql - $ brew services start rabbitmq + brew services start postgresql + brew services start rabbitmq ``` - Install dependencies with `mix deps.get` - Create and migrate your database with `mix ecto.setup` - Install Node.js dependencies with `cd assets && npm install` -- Copy `.env.example` to `.env` +- Copy `.env.example` to `.env` and populate environment variables - We use [Phoenix Live View][phoenix_live_view] for our real-time data presentation. Make sure to set `SECRET_SALT` in your `.env`. Generate a secret salt with: - `mix phx.gen.secret 32` -- Make set your RabbitMQ setting in `.env` -- Start Phoenix endpoint with `mix phx.server` +- Start Phoenix endpoint with `foreman run mix phx.server` -Now you can visit [`localhost:4000/dashboard`][localhost] from your browser. +Now you can visit [`localhost:4000`][localhost] from your browser. ## Running the test suite Run the entire test suite using the following command ``` -$ mix test +mix test ``` To run a specific test file, add the path to the test file ``` -$ mix test test/apr/views/commerce/commerce_transaction_slack_view_test.exs +mix test test/apr/views/commerce/commerce_transaction_slack_view_test.exs ``` ## Architecture @@ -98,7 +91,7 @@ working: [deploy]: https://github.com/artsy/apr-dashboard/compare/release...staging?expand=1 [jpotts244]: https://github.com/jpotts244 [zephraph]: https://github.com/zephraph -[localhost]: http://localhost:4000/dashboard +[localhost]: http://localhost:4000 [phoenixframework]: https://phoenixframework.org/ [postgresql]: https://www.postgresql.org/download/ [rabbitmq]: https://www.rabbitmq.com/download.html