Sara Alert is an open source tool built to allow public health officials to monitor potentially exposed individuals (“monitorees”, e.g., contacts of cases or travelers from affected areas) over time for symptoms by enrolling them in the system. During enrollment, the potentially exposed individual indicates their preferred method for daily contact. The enrolled monitoree receives a daily reminder from Sara Alert to enter temperature and any symptoms. If any symptoms are reported, the public health official receives an alert in order to coordinate care. If the monitoree fails to report, the public health official can follow up after a pre-defined period. Public health officials have access to reports and aggregated data based on their level of access.
Sara Alert was built in response to the COVID-19 outbreak, but was designed to be customizable such that it can be deployed to support future outbreaks.
Sara Alert is a Ruby on Rails application that uses the MySQL database for data storage and Redis for message processing.
To work with the application, you will need to install some prerequisites:
Run the following commands from the root directory to pull in both frontend and backend dependencies:
bundle installyarn install
Run the following command from the root directory to intialize the database (note: make sure you have a MySQL database running):
bundle exec rake db:drop db:create db:migrate db:setupbundle exec rake admin:import_or_update_jurisdictionsbundle exec rake admin:create_roles- (optional)
bundle exec rake demo:setup demo:populate
ActiveJob will work with Sidekiq, Redis, and Whenever to manage the queueing and running of jobs (used to send emails, SMS, and other methods of notification).
Redis will need to be installed and running. To install Redis:
wget http://download.redis.io/redis-stable.tar.gz
tar xvzf redis-stable.tar.gz
cd redis-stable
makeTo start Redis:
redis-server
Sidekiq is the queueing system that ActiveJob interfaces with. Sidekiq should be installed when you ran bundle install in the application installation instructions. To start Sidekiq, and make it aware that it is responsible for the mailers queue, execute the following:
bundle exec sidekiq -q default -q mailers
The Whenever gem is used to schedule jobs. This gem uses the contents of config/schedule.rb to generate a crontab file. These jobs include:
- Automatically closing out monitorees after the monitoring period
- Purging old monitoree records
- Updating system analytics
You must update your chrontab for these jobs to run periodically (defined in config/schedule.rb). To do so run:
bundle exec whenever --update-crontab
These tasks are configured to run periodically. Their run timing parameters are specified in config/schedule.rb
CloseSubjectsJob- Active job that closes cases that meet duration/symptomatic conditions
PurgeJob- Active job that redacts PII of cases that have been closed for N many days
rake mailers:send_purge_warning- Send warning to users of upcoming PurgeJob containing N many records
rake analytics:cache_current_analytics- Caches analytics information for faster retrieval
rake mailers:send_assessments- Send assessment reminders to non-reporting individuals
To run Sara Alert, execute: bundle exec rails s.
Ensure Docker and Docker Compose are installed.
This application includes several Dockerfiles and Docker Compose configurations. Let's go over each of them:
Dockerfile: This Dockerfile is essentially the same as theDevelopmentTest.Dockerfilebut provides support for developers that want to get a development and test environment up and running with a simpledocker build .DevelopmentTest.Dockerfile: This Dockerfile is used in the project's Continuous Integration (CI) and allows developers to get started with the full split stack architecture as its the default used in the compose files. It contains the dependencies for running tests.Production.Dockerfile: This Dockerfile is built for production or staging deployments.docker-compose.yml: This docker compose file sets up the numerous containers, networks, and volumes required for the split architecture.docker-compose.prod.yml: The only difference between this file and the normal one is the overwriting of theDevelopmentTestimage tag with thelatesttag.
If you are building the image behined a corporate proxy:
- Create a
certs/directory in the root of the project - Place your company
.crtfile in it export CERT_PATH=/path/to/crt_from_above.crt
Building for staging requires the use of the Production.Dockerfile.
docker build -f Production.Dockerfile --tag sara-alert:latest --build-arg cert="$(cat $CERT_PATH)" .
Deploying a staging server is done with docker-compose.yml, docker-compose.prod.yml, and the image created in the previous section. Make sure the image is on the staging server or it can be pulled from a Docker registry to the staging server.
Docker Networking
The docker-compose.yml file sets up three networks which route traffic between the containers. The networks are:
dt-net-enrollment: Hosts the applications/services used for enrolling and monitoring.dt-net-assessment: Hosts the application/services used by monitorees filling out assessments.dt-net-bridge: Facilitiates communication between the two other networks.
This results in a 'split architecture' where multiple instances of the SaraAlert application are running. This approach attempts to reduces the amount of services that have access to the monitoree database.
A key portion of this is the use of the Nginx reverse proxy container. The configuration (located at ./nginx.conf) will route traffic from 'untrusted' users submitting assessments to the dt-net-assessment application while, at the same time, enrollers and epidemiologists are routed to the enrollment database.
Below is a graphic depicting the services and applications present on each network:
Environment Variable Setup
To set up Sara Alert in a staging configuration, generate two environment variable files which correspond with the networks described above:
.env-prod-assessment.env-prod-enrollment
The content for these files can be based off of the .env-prod-assessment-example and .env-prod-enrollment-example files.
The SECRET_KEY_BASE and MYSQL_PASSWORD variables should be changed at the very least. These variables should also not be the same between both assessment and enrollment instances of the files. It is important to note that SARA_ALERT_REPORT_MODE should be set to false for the enrollment file and true for the assessment file.
Twilio/Authy Environment Variables
The following environment variables need to be set on the enrollment instances, which are the instances that will be dispatching the SMS/Voice assessments via Twilio and performing Two-Factor Authentication using Authy. These environment variables can be set in a config/local_env.yml file, or via a method provided by the deployment environment.
TWILLIO_API_ACCOUNT: <Account number for Twilio Account>TWILLIO_API_KEY: <API key for Twilio Account>TWILLIO_SENDING_NUMBER: <Phone number registered to Twilio Account for SMS/Voice>TWILLIO_STUDIO_FLOW: <Twilio Studio Flow ID for handling SMS/Voice Assessments>AUTHY_API_KEY: <API key for Authy project>
Container Dependencies
Create a directory for the deployment. Move both docker compose files and both environment variable files from the previous section into this folder. Within this deployment directory, create a subdirectory called tls and place your .key and .crt files for the webserver inside. Name the files puma.key and puma.crt. Ensure the .crt and .key files within the tls directory are at least 0x004 permissions so they can be read inside the container.
The Nginx configuration is also statged within the same directory. You will need to move the nginx.conf provided in the root of this repository into ~/tls/nginx.conf.
Deployment
Before any of the following commands, export the image you're working with. For the staging environment, the tag is assumed to be latest. Example for a locally built image (you will likely need to update this to point to your registry!): export SARA_ALERT_IMAGE=sara-alert
/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml pull/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --remove-orphan/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-enrollment bin/bundle exec rake db:create/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-enrollment bin/bundle exec rake db:migrate/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-assessment bin/bundle exec rake db:create/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-assessment bin/bundle exec rake db:migrate
Post-deployment Setup
Before any of the following commands, export the image you're working with. For the staging environment, the tag is assumed to be latest. Example for a locally built image (you will likely need to update this to point to your registry!): export SARA_ALERT_IMAGE=sara-alert
Load Jurisdictions:
/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-enrollment bin/bundle exec rake admin:import_or_update_jurisdictions/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-assessment bin/bundle exec rake admin:import_or_update_jurisdictionsNote: If you need to make live-changes to the jurisdictions loaded on they system, you'll have to updateconfig/sara/jurisdictions.ymlon the sara-alert-assessment and sara-alert-enrollment containers. The changes made to each of the jurisdictions.yml files NEED TO BE IDENTICAL
Load User Roles
/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-enrollment bin/bundle exec rake admin:create_roles
Setup the demonstration accounts and population:
- Launch a shell inside the sara-alert-enrollment container:
/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml run sara-alert-enrollment /bin/sh - Remove the protections for running the demonstration setup tasks only in development mode:
vi lib/tasks/demo.rake- Delete the environment checks at the top of the
setupandpopulatetasks - Save and close the file
- Execute the demonstration rake tasks:
bin/bundle exec rake demo:setupbin/bundle exec rake demo:populate
- Exit the container with
exit
The applications should be running on port 443 with Nginx proxying traffic between.
bundle exec rails test
By default, rails test will not run system tests. To run system tests (uses Selenium):
bundle exec rails test:system
All jurisdictions, jurisdictional hierarchies, jurisdictional symptoms-to-be-monitored, and symptom thresholds are defined in the configuration file located at config/sara/jurisdictions.yml. See this file for more details about the structure and definition required by Sara Alert.
You must run bundle exec rake admin:import_or_update_jurisdictions in order for changes made in the config/sara/jurisdictions.yml configuration to take effect.
To report issues with the Sara Alert code, please submit tickets to GitHub.
This project adheres to Semantic Versioning.
Copyright 2020 The MITRE Corporation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.