Peak Demand Alerts

Alerting municipalities when they can save on energy costs and help the environment.

Overview

This is a Rails app that runs scheduled daily emails (via Mailgun). There is a basic admin interface that allows us to configure the min/max values for energy consumption thresholds and view the status of today's emails. There is also a simple embeddable page that surfaces the same information as the daily emails.

Weather data are pulled from the weather.gov API, and energy usage data are pulled from the ISO New England Web Services API.

The Environment team runs a model that predicts the min/max energy consumption for the season (managed by adding/updating Configurations through the admin UI. These configuration values are used to make the unlikely/possible/likely determinations in the daily email alerts.

Scheduling

The app uses the Heroku Scheduler add-on to run the rake task that generates today's weather report and sends emails via Mailgun.

Note: The ACTIVE environment variable must be set to true for the emails to go out. This acts as a simple on/off switch for the service if needed.

Emails

Content

Originally, email content was generated using an erb template. Now, the app uses Mailgun's Email Templates feature. Ideally, non-technical users should be able to manage and update the email template without requiring a code deployment or other technical assistance.

Mailing List

Originally, the mailing list was maintained as CSV in an environment variable (EMAIL_RECIPIENTS). Now, the app uses Mailgun's Mailing List feature. Ideally, non-technical users should be able to manage and update the mailing list without requiring a code deployment or other technical assistance. See these Mailgun docs on the mailing list API, managing mailing lists, and mailing list best practices.

Note: Unsubscribed emails should be removed regularly from the mailing list. If this is not done, the proportion of successful/unsuccessful emails may drop below the alert threshold (see the MAILGUN_BAD_DELIVERY_THRESHOLD environment variable) and trigger the status monitor.

Monitoring

We use UptimeRobot to monitor the service itself (Peak Alerts) and the daily email delivery (Peak Demand Alert Emails). The MAILGUN_BAD_DELIVERY_THRESHOLD environment variable (usually set to 80, representing 80% successfully delivered) determines whether the "Peak Demand Alert Emails" monitor will be triggered. It reads from the https://peak-alerts.herokuapp.com/status/email endpoint, which queries the Mailgun API and determines the deliverability of the most recent batch of emails sent to the mailing list.

Deployment

This application lives on Heroku as peak-alerts. The app is automatically built/deployed when you push to the remote heroku git repository.

Environment Variables

In addition to the environment variables defined in .env.template, on production you will need to set configuration for the MailGun API.

heroku config:set\
 MAILGUN_API_KEY='value'\
 MAILGUN_DOMAIN='value'\
 MAILGUN_PUBLIC_KEY='value'\

Production values for these environment variables can be found in Dashlane under the "Peak Demand" secure notes.

These variables can also be managed through the Settings tab for the app in Heroku.

Seasonal shut-down/start-up

Shutting down

At the end of the summer, we can suspend emails and save money by deactivating the service in Heroku.

1. First, log into UptimeRobot and pause the monitors (there are two: Peak Alerts and Peak Demand Alert Emails) by selecting the checkboxes next to them, going to the "Bulk actions" dropdown at the top, and selecting "Pause monitors".
2. Then, go to the Settings tab for the app, and set the ACTIVE environment variable to false. This prevents emails from going out when the service is running.
3. Lastly, go to the Resources tab for the app, click the "edit" icon for the Dyno, and click the slider to deactivate the service. When this is done, you should see the "Estimated Monthly Cost" at the bottom read $0.00

Starting up

At the beginning of the summer, we can resume emails by turning the service back on and making it active again.

1. First, go to the Resources tab for the app, click the "edit" icon for the Dyno, and click the slider to activate the service. When this is done, you should see the "Estimated Monthly Cost" bump up to ~$7.00 (as of 09/2024).
2. Then, go to the Settings tab for the app, and set the ACTIVE environment variable to true. This allows the daily alert emails to be sent now that the service is running again.
3. Lastly, log into UptimeRobot and start the monitors (there are two: Peak Alerts and Peak Demand Alert Emails) by selecting the checkboxes next to them, going to the "Bulk actions" dropdown at the top, and selecting "Start monitors".