restructure readme & docs

docs/database-management.md

@@ -0,0 +1,55 @@
+# Database management
+
+## Initial state
+
+In Notify, several aspects of the system are loaded into the database via migration. This means that
+application setup requires loading and overwriting historical data in order to arrive at the current
+configuration.
+
+[Here are notes](https://docs.google.com/document/d/1ZgiUtJFvRBKBxB1ehiry2Dup0Q5iIwbdCU5spuqUFTo/edit#)
+about what is loaded into which tables, and some plans for how we might manage that in the future.
+
+Flask does not seem to have a great way to squash migrations, but rather wants you to recreate them
+from the DB structure. This means it's easy to recreate the tables, but hard to recreate the initial data.
+
+## Migrations
+
+Create a migration:
+
+```
+flask db migrate
+```
+
+Trim any auto-generated stuff down to what you want, and manually rename it to be in numerical order.
+We should only have one migration branch.
+
+Running migrations locally:
+
+```
+flask db upgrade
+```
+
+This should happen automatically on cloud.gov, but if you need to run a one-off migration for some reason:
+
+```
+cf run-task notifications-api-staging --commmand "flask db upgrade" --name db-upgrade
+```
+
+## Purging user data
+
+There is a Flask command to wipe user-created data (users, services, etc.).
+
+The command should stop itself if it's run in a production environment, but, you know, please don't run it
+in a production environment.
+
+Running locally: 
+
+```
+flask command purge_functional_test_data -u <functional tests user name prefix>
+```
+
+Running on cloud.gov:
+
+```
+cf run-task notify-api "flask command purge_functional_test_data -u <functional tests user name prefix>"
+```

docs/infra-onboarding.md

@@ -0,0 +1,7 @@
+# Infrastructure onboarding
+
+- [ ] Join [the GSA GitHub org](https://github.com/GSA/GitHub-Administration#join-the-gsa-organization)
+- [ ] Get permissions for the repos
+- [ ] Get access to the cloud.gov org && space
+- [ ] Get access to AWS, if necessary
+- [ ] Pull down creds from cloud.gov and create the local .env file

docs/infra-setup.md

@@ -0,0 +1,20 @@
+# Setting up the infrastructure
+
+## Steps to prepare SES
+
+1. Go to SES console for \$AWS_REGION and create new origin and destination emails. AWS will send a verification via email which you'll need to complete.
+2. Find and replace instances in the repo of "testsender", "testreceiver" and "dispostable.com", with your origin and destination email addresses, which you verified in step 1 above.
+
+TODO: create env vars for these origin and destination email addresses for the root service, and create new migrations to update postgres seed fixtures
+
+## Steps to prepare SNS
+
+1. Go to Pinpoints console for \$AWS_PINPOINT_REGION and choose "create new project", then "configure for sms"
+2. Tick the box at the top to enable SMS, choose "transactional" as the default type and save
+3. In the lefthand sidebar, go the "SMS and Voice" (bottom) and choose "Phone Numbers"
+4. Under "Number Settings" choose "Request Phone Number"
+5. Choose Toll-free number, tick SMS, untick Voice, choose "transactional", hit next and then "request"
+6. Go to SNS console for \$AWS_PINPOINT_REGION, look at lefthand sidebar under "Mobile" and go to "Text Messaging (SMS)"
+7. Scroll down to "Sandbox destination phone numbers" and tap "Add phone number" then follow the steps to verify (you'll need to be able to retrieve a code sent to each number)
+
+At this point, you _should_ be able to complete both the email and phone verification steps of the Notify user sign up process! 🎉

docs/one-off-tasks.md

@@ -0,0 +1,22 @@
+# One-off tasks
+
+For these, we're using Flask commands, which live in [`/app/commands.py`](../app/commands.py).
+
+This includes things that might be one-time operations! Using a command allows the operation to be tested, 
+both with `pytest` and with trial runs.
+
+To run a command on cloud.gov, use this format:
+
+```
+cf run-task CLOUD-GOV-SPACE --commmand "YOUR COMMAND HERE" --name YOUR-COMMAND
+```
+
+[Here's more documentation](https://docs.cloudfoundry.org/devguide/using-tasks.html) about Cloud Foundry tasks.
+
+## Celery scheduled tasks
+
+After scheduling some tasks, run celery beat to get them moving:
+
+```
+make run-celery-beat
+```

docs/testing.md

@@ -0,0 +1,31 @@
+# Testing
+
+```
+# install dependencies, etc.
+make bootstrap
+
+make test
+```
+
+This will run:
+- flake8 for code styling
+- isort for import styling
+- pytest for the test suite
+
+On GitHub, in addition to these tests, we run:
+- bandit for code security
+- pip-audit for dependency vulnerabilities
+- OWASP for dynamic scanning
+
+## CI testing
+
+We're using GitHub Actions. See [/.github](../.github/) for the configuration.
+
+## To run a local OWASP scan
+
+1. Run `make run-flask` from within the dev container.
+2. On your host machine run:
+
+```
+docker run -v $(pwd):/zap/wrk/:rw --network="notify-network" -t owasp/zap2docker-weekly zap-api-scan.py -t http://dev:6011/_status -f openapi -c zap.conf
+```