Skip to content

Commit

Permalink
Document local dev vs deployment
Browse files Browse the repository at this point in the history 
We also seed an admin user, so mention that in the README.
  • Loading branch information
@stevenharman
stevenharman committed Mar 20, 2020
1 parent 359f851 commit f6e7ce5
Show file tree
Hide file tree
Showing 3 changed files with 174 additions and 90 deletions.
164 changes: 76 additions & 88 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,138 +6,126 @@ If you need help setting this platform up, please email me at brandon.cummings@b

## Introduction

This platform was created for local cities or municipalities to help manage corona virus testing sites. This platform accomplishes 3 main goals:
This platform was created for local cities or municipalities to help manage corona virus testing sites.
This platform accomplishes 3 main goals:

Questionnaire to self diagnose symptoms: If symptoms are present, the user will be shown a map that shows all local testing sites, and a google map link to direct them to the site.
Testing site management: For all testing sites, there is a portal to keep track of number of tests administered and number of patients in line.
#### Questionnaire to self diagnose symptoms

Admin management: Full admin suite to create/edit testing site officials, testing sites, and a dashboard for analytics to gain real time insights.
If symptoms are present, the user will be shown a map that shows all local testing sites, and a google map link to direct them to the site.

## Proving the value of more testing centers:
#### Testing site management

Some local cities will not immediately see the need for more public testing centers and will need a digestible way of analyzing this solution, so we created a slide deck to explain why cities should implement this platform.
For all testing sites, there is a portal to keep track of number of tests administered and number of patients in line.

https://docs.google.com/presentation/d/1dOQSBMMUycuwKto4_SnoCBAIxSTDLVvGNfzxb64Z7nI/edit#slide=id.p
#### Admin management

## Table Of Contents
Full admin suite to create/edit testing site officials, testing sites, and a dashboard for analytics to gain real time insights.

1. Domain registration
2. Hosting setup
3. Google Maps API setup
4. Sendgrid setup
5. App setup
6. Recaptcha Setup
7. Example usage
8. Environment Variables
#### Proving the value of more testing centers:

## Domain registration
Some local cities will not immediately see the need for more public testing centers and will need a digestible way of analyzing this solution.
To aide with that, we created a [slide deck to explain why cities should implement this platform][deck].

I highly recommend not using GoDaddy to register your domain, you need to use a domain manager that allows you to update A records without having a static IP address, such as https://dnsimple.com/.
## Hosting and Deploying

Go purchase a domain, such as the domain we purchased: atlanta-covid19-testing-sites.com
Please see the [self hosting guide](docs/self-hosting.md).

Once you have registered this domain, we will revisit to connect heroku site and to prove to google you are the owner by adding CNAME records.
## 🏎 Getting up and Running

## Hosting setup
Because installing dependencies is such a pain, we've bootstrapped this thing for you!

I highly recommend using Heroku, it’s very easy to get setup.
```bash
bin/setup

Heroku signup: https://signup.heroku.com/t/platform
# for all options:

Setup the heroku app and prepare an app to push to from your command line. Head to your settings of this app you just created, select “Reveal Config Vars” these are all environment variables for you application.
Save RAILS_APP_ROOT_DOMAIN as the root domain you just purchased.
bin/setup -h
```

## Google Maps API setup
being sure to follow any instructions it gives you.
After you've done that you should have:

The google maps api is a crucial part of this application, so please follow these steps:
* the following soft dependencies installed: PostgreSQL, Heroku Toolbelt, etc...
* the correct version of Ruby installed and activated
* hard dependencies (via `Gemfile`) installed
* a local `.env` file for setting ENV Vars
* databases created w/schemas loaded for both `development` and `test` environments.
* seed `development` databases

Go to https://console.developers.google.com/
1. Create a new project called “COVID19-Testing”
2. Enable the Google Maps Javascript API
3. You will need to have a verified domain in order to create credentials, create a verified domain by following the steps.
4. Visit https://console.developers.google.com/apis/credentials/domainverification Follow the steps provided, I had to add a CNAME record to my DNS that pointed to the value google provided
5. Create API credentials, which will produce an API key that you should keep safe and never store publicly, only store within environment variables.
6. Restrict your API key to only the Google Maps Javascript API and add the urls that you purchased, so only those urls can access your application. In our case we added the following urls:
#### 🗂 ENV Vars

https://www.atlanta-covid19-testing-sites.com
https://atlanta-covid19-testing-sites.com
http://localhost:3000 (for developing locally)
You can set some *optional* [ENV Vars][env-vars] to tweak the way the app runs, or simulate the app running on other platforms.
In development and test, you should configure these via a [`.env` file][dotenv].

Once you have your API key, save it to your heroku apps settings, under the “Reveal Config Vars”, and add it as GOOGLE_API_KEY.
- `DATABASE_URL`: set to mimic the behavior of setting the database connection on Heroku. *(Default to using `config/database.yml`)*
- `DB_REAPING_FREQUENCY`: how often (in seconds) the database connection pool should be reaped. _(Default = `10`)_
- `WEB_CONCURRENCY`: set the number of [Puma][puma] worker process to run. *(Default = `2`)*
- `RAILS_MAX_THREADS`: set the number of [Puma][puma] threads & ActiveRecord's connection pool size. *(Default = `5`)*

## Sendgrid Setup
There are also some **required** [ENV Vars][env-vars] that you'll need to set for all environments.

Go to https://sendgrid.com/ and signup. Go to https://app.sendgrid.com/settings/api_keys to setup an API key with full access.
- `GOOGLE_API_KEY`: the API key used to render Google Maps.
- `RECAPTCHA_SECRET_KEY` and `RECAPTCHA_SITE_KEY`: used to render the reCAPTCHA element on index page.
RECAPTCHA_SITE_KEY

Save this API key in your heroku config vars as SEND_GRID_API_KEY
Also save to your heroku config vars SEND_GRID_USERNAME with the value of “apikey” (literally the word “apikey” not your actual API key)
Further there are some **required** [ENV Vars][env-vars] that you'll need to set in `production`.
These are covered in more detail in the [self-hosting docs](docs/self-hosting.md).
These can also be overridden in local `development` and `test` environments via your `.env` file.

## App setup
- `DEFAULT_MAP_CENTER_LAT`: the latitude of the default center of your map
- `DEFAULT_MAP_CENTER_LON`: the longitude of the default center of your map
- `RAILS_APP_ROOT_DOMAIN`: the HTTP host to use when generating URLS for emails, assets, etc... *(Default = `localhost:5000`)*
- `SEND_GRID_API_KEY` and `SEND_GRID_USERNAME`: for sending emails.

Fork this repo so that you can push any changes to your own custom repository.
#### ⚗️ Development data

Once pulled down, run:
### 🏁 Running the app

rake db:create
We use a [`Procfile`][procfile] to declare all of the processes we use.
This includes starting the Rails app (via the [Puma][puma] web server).
Use [Heroku-local][heroku-local] to start/stop all of the processes in the `Procfile`:

Here is a great resource to get rails up and running: https://www.tutorialspoint.com/ruby-on-rails/rails-installation.htm
```bash
heroku local:start
```

Once you have the repo, follow these steps:
*NOTE: You can shut everything down by hitting `^C` _(that's `Control` + `C`)_.*

1. bundle install
2. rake db:create db:migrate
3. Store your environment variables, from your command line write:
4. export GOOGLE_API_KEY=<api_key_you_created>
5. export RECAPTCHA_SITE_KEY=<recaptcha site key>
6. export RECAPTCHA_SECRET_KEY=<recaptcha secret key>
Point your browser/client at <http://localhost:5000> to see the app in action!

Run the app locally by running “rails s”, then visit http://localhost:3000 on your local machine and browser of choice.
With the app running, you should be able to sign in with the seeded admin account `[email protected]` and the password `password1234`.

In order to see the Site Official View, you will need to create a new User and Host through the Admin view, and in order to view the admin view at http://localhost:3000/admin you will need to create a new AdminUser.
In order to see the Site Official View, you will need to create a new User and Host through the [Admin view](http://localhost:5000/admin).

1. Run “rails c” to run the rails console
2. Then create a new AdminUser by running “AdminUser.create(email: “[email protected]”, password: “password”)
3. Then visit http://localhost:3000/admin, sign in with the email and password created.
4. You can then go to the tab “Testing Sites” and “Location Officials” to create a new Host and User.
5. The User your create must be associated to a Host, and make sure the host address is correctly populated by Geocoder by checking the fields “latitude” and “longitude”, if the address is correct, those fields should be populated correctly.
1. Go to the “Testing Sites” tab to create a new Host.
1. Go to the “Location Officials” tab and create a new User.

You will most likely run into some issues with setup, most can be googled and have been addressed, stay patient and you will get through it.

## Recaptcha Setup

Recaptcha is used to prevent bots from overwhelming your site and wasting you google maps API calls by implementing a simple checkbox that says "I am not a robot".

To setup, visit https://www.google.com/recaptcha/admin/create

Choose V2 "Checkbox"

Input the domains you have purchased.

Save RECATPCHA_SITE_KEY and RECATPCHA_SECRET_KEY as environment variables on your heroku instance.
_NOTE:_ The User your create must be associated to the Host you just created.
Also be sure the host address is correctly populated by Geocoder by checking the fields “latitude” and “longitude”.

## Example usage

This platform can be used the following way.

A local government IT team sets up the platform and designates where in the city a testing site will be located and how many officials will work at each location.

Citizen View: The city will market to the citizens the url of the site, the citizen can self diagnose symptoms and find a testing site if needed.
#### Citizen View

Testing Site Officials View: there are two main actions that can occur in the testing site officials view, increasing the number of test kits used, and keeping track of people in line waiting to receive a test kit.
The city will market to the citizens the url of the site, the citizen can self diagnose symptoms and find a testing site if needed.

If there are 3 individuals working a testing site, one can be administering the test, one can be capturing the patient information and updating the number of test kits used through the platform, and one can be keeping the line count up to date and organized.
#### Testing Site Officials View

Admin View: The admin view allows for new testing sites and testing site officials to be created/updated, as well as showing in real time the number of test kits used, total wait time and testing sites that may need additional resources, per testing site.
There are two main actions that can occur in the testing site officials view, increasing the number of test kits used, and keeping track of people in line waiting to receive a test kit.

If there are 3 individuals working a testing site, one can be administering the test, one can be capturing the patient information and updating the number of test kits used through the platform, and one can be keeping the line count up to date and organized.

## Environment Variables
#### Admin View

The environment variables needed to be set in heroku are as follows:
The admin view allows for new testing sites and testing site officials to be created/updated, as well as showing in real time the number of test kits used, total wait time and testing sites that may need additional resources, per testing site.

1. GOOGLE_API_KEY - your Google Maps Javascript api key
2. DEFAULT_MAP_CENTER_LAT - the latitude of the default center of your map
3. DEFAULT_MAP_CENTER_LON - the longitude of the default center of your map
4. RAILS_APP_ROOT_DOMAIN - root domain you are using
5. SEND_GRID_USERNAME - which is "apikey" (the literal word "apikey")
6. SEND_GRID_API_KEY - your sendgrid api key
7. RECATPCHA_SECRET_KEY - Recaptcha secret key
8. RECATPCHA_SITE_KEY - Recaptcha site key
[deck]: https://docs.google.com/presentation/d/1dOQSBMMUycuwKto4_SnoCBAIxSTDLVvGNfzxb64Z7nI/edit#slide=id.p "Coronavirus Drive Through Testing Site Application"
[dotenv]: https://github.com/bkeepers/dotenv "A Ruby gem to load environment variables from `.env`."
[env-vars]: https://devcenter.heroku.com/articles/config-vars "Configuration and Config Vars"
[heroku-local]: https://devcenter.heroku.com/articles/heroku-local "Heroku Local"
[procfile]: https://devcenter.heroku.com/articles/procfile "Process Types and the Procfile"
[puma]: http://puma.io/ "A modern, concurrent web server for Ruby"
4 changes: 2 additions & 2 deletions db/seeds.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@
# Examples:
#
# movies = Movie.create([{ name: 'Star Wars' }, { name: 'Lord of the Rings' }])
# Character.create(name: 'Luke', movie: movies.first)
AdminUser.create!(email: "[email protected]", password: "password", password_confirmation: "password") if Rails.env.development?
# Character.create(name: 'Luke', movie: movies.first
AdminUser.create!(email: "[email protected]", password: "password1234", password_confirmation: "password1234") if Rails.env.development?
96 changes: 96 additions & 0 deletions docs/self-hosting.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
# Deploying your own instance

This documentation explains how to set up your own instance of this tool.
We prefer Heroku as the hosting platform, and the instructions are written from that angle.
You can adjust to your own hosting preference as needed.

## Table Of Contents

1. [Domain Registration](#domain-registration)
1. [Hosting Setup](#hosting-setup)
1. [Google Maps API Setup](#google-maps-api-setup)
1. [Sendgrid Setup](#sendgrid-setup)
1. [Recaptcha Setup](#recaptcha-setup)
1. [Environment Variables](#environment-variables)

For local development instructions, please see the [`README`](../README.md).

## Domain Registration

We recommend a domain registrar and DNS provider that supports the `ALIAS`/`ANAME` record type.
This is required to [configure your DNS for a root domain][dns-config], if you are using a hosting provider such as [Heroku][heroku].

You probably want a domain that is specific to your municipality and/or geographical region. e.g., `atlanta-covid19-testing-sites.com`

## Hosting Setup

We recommend using [Heroku][heroku], it's easy to get setup.

Setup the Heroku app and prepare an app to push to from your command line.
Head to your settings of this app you just created, select “Reveal Config Vars” these are all environment variables for you application.
Save `RAILS_APP_ROOT_DOMAIN` as the root domain you just purchased.

## Google Maps API Setup

The [Google Maps API][google-maps-api] is a crucial part of this application, so please follow these steps:

1. Create a new project called “COVID19-Testing”
1. Enable the Google Maps Javascript API
1. You will need to have a verified domain in order to create credentials, create a verified domain by following the steps.

1. From the Google console, go to the [domain verification][google-domain-verification] page.
1. Follow the instructions, being sure to add a `CNAME` record to your DNS that points to the value Google gives you.

1. Create Google Maps API credentials.

1. From the Google console, go to the "Credentials" tab.
1. Create a new key and store it somewhere safe.
**NEVER** store this key publicly, such as in your source code.
1. Restrict your API key to only the Google Maps Javascript API and add the domains that you purchased, so only those domains can access your application.
In our case we added the following urls:

```
https://www.atlanta-covid19-testing-sites.com
https://atlanta-covid19-testing-sites.com
http://localhost:5000
```
_NOTE:_ the `localhost:5000` is for local development testing.
1. Open your Heroku app's Settings, then “Reveal Config Vars”, and add the Google Maps API key as `GOOGLE_API_KEY`.
## Sendgrid Setup
Go to [Sendgrid][sendgrid] and sign up.
Then visit the [API Keys Settings][sendgrid-keys] to setup an API key with **full access**.
Next, open your Heroku app's Settings, then “Reveal Config Vars”, and add the Sendgrid API Key with the name `SEND_GRID_API_KEY`.
Also add a Heroku Config Var with the name `SEND_GRID_USERNAME` and a vlue of `apikey`.
## Recaptcha Setup
Recaptcha is used to prevent bots from overwhelming your site and wasting you Google Maps API calls by implementing a simple checkbox that says "I am not a robot".
To set it up:
1. Visit [reCAPTCHA setup].
1. Choose V2 "Checkbox"
1. Input the domains you have purchased.
1. In your Heroku app's Settings, add the `RECAPTCHA_SITE_KEY` and `RECAPTCHA_SECRET_KEY` Config Vars with the values from the reCAPTCHA setup.
## Environment Variables
The necessary and optional Environment Variables are described in the [`README`](../README.md#env-vars)
## Up and Running
With all of that done, you should be able to deploy your instance, and be up and running.
Good luck!
[dns-config]: https://devcenter.heroku.com/articles/custom-domains#configuring-dns-for-root-domains "Configuring DNS for root domains"
[google-domain-verification]: https://console.developers.google.com/apis/credentials/domainverification
[google-maps-api]: https://console.developers.google.com/ "Google Cloud Platform"
[heroku]: https://heroku.com "Cloud Application Platform"
[recaptcha]: https://www.google.com/recaptcha/admin/create
[sendgrid-keys]: https://app.sendgrid.com/settings/api_keys
[sendgrid]: https://sendgrid.com/

0 comments on commit f6e7ce5

Please sign in to comment.