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:
Ensure that Git LFS is installed and initialized.
Clone the project: git clone https://github.com/SaraAlert/SaraAlert.git
Run the following commands from the project's root directory to pull in both frontend and backend dependencies:
bundle installyarn install
Sara Alert targets compatibility with MySQL 5.7.
macOS Installation Instructions:
Migrating from a newer verison down to MySQL 5.7: Before installing MySQL, if newer versions (i.e. version 8 of MySQL) have previously been installed and initialized in the newer format, these new-format databases will be incompatible with the older 5.7 version. A simple way to install 5.7 after newer versions is to delete the MySQL data directory and let the 5.7 version recreate it in the correct format. Take care to back up existing databases before executing the following command, as it will delete them:
brew services stop mysql # stop current mysql version
rm -rf /usr/local/var/mysql # remove the macOS mysql data directory and any existing databases
brew uninstall mysql # remove current mysql versionIf Sara Alert had already been installed with a newer version of MySQL, navigate to the project directory and uninstall the mysql2 gem. It needs to build the correct native extensions for MySQL 5.7.
gem uninstall mysql2 # uninstall mysql2Newer versions of MySQL also start with incompatible options for version 5.7, so if you had a newer version installed edit /usr/local/etc/my.cnf to remove the line 'mysqlx-bind-address=127.0.0.1'.
Installation:
Now, install [email protected] using homebrew:
brew install [email protected]
brew link [email protected] --force
brew services start [email protected]# Please update this command with the appropriate <MINOR_VERSION> installed from homebrew.
bundle config --local build.mysql2 "--with-mysql-config=/usr/local/Cellar/[email protected]/5.7.<MINOR_VERSION>/bin/mysql_config --with-ldflags=-L/usr/local/opt/openssl/lib --with-cppflags=-I/usr/local/opt/openssl/include"
bundle installDatabase Initialization:
Run the following commands from the root of the project directory to initialize the database (note: make sure you have a MySQL database and Redis running):
mysql -u root -e "CREATE USER 'disease_trakker'@'localhost'; GRANT ALL PRIVILEGES ON *.* TO 'disease_trakker'@'localhost';"optional for local development only, not for docker containersrails db:createrails db:schema:loadbundle exec rake admin:import_or_update_jurisdictionsbundle exec rake demo:setup demo:populateoptional
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 -q exports
The Whenever gem is used to help schedule jobs. This gem uses the contents of config/schedule.rb to generate a crontab file.
You must update your crontab for these jobs to run periodically (defined in config/schedule.rb). To do so run:
bundle exec whenever --update-crontab
The following jobs are configured to run continuously:
ConsumeAssessmentsJob- Should always be running in order to be ready to consume assessments at any time.
- Handles consuming assessments from the assessment container into the enrollment container.
- Subscribes to the Redis
reportschannel and consumes on every message in that channel.
The following jobs are configured to run periodically (their run timing parameters are specified in config/schedule.rb):
ClosePatientsJob.- Closes (stops active monitoring of) monitorees that meet duration/symptomatic conditions
PurgeJob- Purges eligible records
SendPurgeWarningsJob- Send warnings to users of upcoming PurgeJob
CacheAnalyticsJob- Caches analytics information for faster retrieval
SendAssessmentsJob- Send assessment reminders to monitorees
PurgeJwtIdentifiersJob- Purge expired JWT Identifiers that are saved and validated when clients request access to the API.
NOTE: In any production instance, these jobs should be handled outside of any of the containers (they should be scheduled and launched via crontab by the host).
To run Sara Alert, execute: bundle exec rails s.
In a development environment, login with username/password credentials created with the demo:setup rake task
or create user accounts with the user: rake tasks (some environment variables required).
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.Nginx.Dockerfile: This Dockerfile is built fromDevelopmentTest.DockerfileorProduction.Dockerfilewhich contains all static assets (i.e. thepublic/folder).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.
- Create a
certs/directory in the root of the project
If you are building the image behined a corporate proxy:
- 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 and Nginx.Dockerfile.
docker build -f Production.Dockerfile --tag sara-alert:latest --build-arg cert="$(cat $CERT_PATH)" .docker build -f Nginx.Dockerfile --tag sara-alert-nginx:latest --build-arg sara_alert_image=sara-alert:latest .
Deploying a staging server is done with docker-compose.yml, docker-compose.prod.yml, and the two images created in the previous section. Make sure the images are on the staging server or they 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: Facilitates 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 staged 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 images 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 and export NGINX_IMAGE=sara-alert-nginx.
/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_jurisdictions
Note: If you need to make live-changes to the jurisdictions loaded on they system, you'll have to update config/sara/jurisdictions.yml on the sara-alert-assessment and sara-alert-enrollment containers. The changes made to each of the jurisdictions.yml files NEED TO BE IDENTICAL
Setup the demonstration accounts and population if desired:
/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml -e DISABLE_DATABASE_ENVIRONMENT_CHECK=true run sara-alert-enrollment bin/bundle exec rake demo:setup/usr/local/bin/docker-compose -f docker-compose.yml -f docker-compose.prod.yml -e DISABLE_DATABASE_ENVIRONMENT_CHECK=true run sara-alert-enrollment bin/bundle exec rake demo:populate
The applications should be running on port 443 with Nginx proxying traffic between.
See API documentation for more information.
bundle exec rails test
yarn run test
See frontend tests documentation for more information.
By default, the rails test command used to execute all the other tests will not run system tests. To run all the system tests:
bundle exec rails test:system
See System tests documentation for more information.
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.
Please note that Apache 2.0 does not allow the use of trademark. Sara Alert™ is a MITRE trademark. If you are interested in using the trademark in your work, please contact [email protected]