US Notify API

This project is the core of Notify. It's cloned from the brilliant work of the team at GOV.UK Notify, cheers!

This repo contains:

• A public-facing REST API for Notify, which teams can integrate with using API clients built by UK
• An internal-only REST API built using Flask to manage services, users, templates, etc., which the admin UI talks to)
• Asynchronous workers built using Celery to put things on queues and read them off to be processed, sent to providers, updated, etc.

Our other repositories are:

• notifications-admin
• notifications-utils
• us-notify-compliance
• notify-python-demo

Local setup

Common steps

On MacOS, using Homebrew for package management is highly recommended. This helps avoid some known installation issues.

1. Install pre-requisites for setup:

   • jq: brew install jq
   • terraform: brew install terraform or brew install tfenv and use tfenv to install terraform ~> 1.4.0
   • cf-cli@8: brew install cloudfoundry/tap/cf-cli@8
   • postgresql: brew install postgresql@15 (Homebrew requires a version pin, but any recent version will work)
   • redis: brew install redis
   • pyenv: brew install pyenv

2. Log into cloud.gov: cf login -a api.fr.cloud.gov --sso

3. Ensure you have access to the notify-local-dev and notify-staging spaces in cloud.gov

4. Run the development terraform with:

    ```
    $ cd terraform/development
    $ ./run.sh
    ```
   

5. If you want to send data to New Relic from your local develpment environment, set NEW_RELIC_LICENSE_KEY within .env

6. Follow the instructions for either Direct installation or Docker installation below

Direct installation

1. Set up Postgres && Redis on your machine

2. Install poetry

3. Run the project setup

   make bootstrap

4. Run the web server and background worker

   make run-procfile

5. Or run them individually:

   • Run Flask (web server)

     make run-flask

   • Run Celery (background worker)

     make run-celery

VS Code && Docker installation

If you're working in VS Code, you can also leverage Docker for a containerized dev environment

1. Uncomment the Local Docker setup lines in .env and comment out the Local direct setup lines.

2. Install the Remote-Containers plug-in in VS Code

3. With Docker running, create the network:

   docker network create notify-network

4. Using the command palette (shift+cmd+p) or green button thingy in the bottom left, search and select “Remote Containers: Open Folder in Container...” When prompted, choose devcontainer-api folder (note: this is a subfolder of notifications-api). This will start the container in a new window, replacing the current one.

5. Wait a few minutes while things happen 🍵

6. Open a VS Code terminal and run the Flask application:

   make run-flask

7. Open another VS Code terminal and run Celery:

   make run-celery

NOTE: when you change .env in the future, you'll need to rebuild the devcontainer for the change to take effect. VS Code should detect the change and prompt you with a toast notification during a cached build. If not, you can find a manual rebuild in command pallette or just docker rm the notifications-api container.

Known installation issues

On M1 Macs, if you get a fatal error: 'Python.h' file not found message, try a different method of installing Python. Installation via pyenv is known to work.

A direct installation of PostgreSQL will not put the createdb command on your $PATH. It can be added there in your shell startup script, or a Homebrew-managed installation of PostgreSQL will take care of it.

Documentation

• Infrastructure overview
  • GitHub Repositories
  • Terraform
  • AWS
  • New Relic
  • Onboarding
  • Setting up the infrastructure
• Testing
  • CI testing
  • Manual testing
  • To run a local OWASP scan
• Deploying
  • Egress Proxy
  • Sandbox environment
• Database management
  • Initial state
  • Data Model Diagram
  • Migrations
  • Purging user data
• One-off tasks
• How messages are queued and sent
• Writing public APIs
  • Overview
  • Documenting APIs
  • New APIs
• API Usage
  • Connecting to the API
  • Postman Documentation
  • Using OpenAPI documentation
• Queues and tasks
  • Priority queue
  • Celery scheduled tasks
• US Notify
  • System Description
• Run Book
  • Alerts, Notifications, Monitoring
  • Restaging Apps
  • Smoke-testing the App
  • Configuration Management
  • DNS Changes
  • Exporting test results for compliance monitoring
  • Known Gotchas
  • User Account Management
  • SMS Phone Number Management
• Data Storage Policies & Procedures
  • Potential PII Locations
  • Data Retention Policy

License && public domain

Work through commit e604385 is licensed by the UK government under the MIT license. Work after that commit is in the worldwide public domain. See LICENSE.md for more information.

Contributing

As stated in CONTRIBUTING.md, all contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.