GOV.UK Notify API

Contains:

• the public-facing REST API for GOV.UK Notify, which teams can integrate with using our clients
• an internal-only REST API built using Flask to manage services, users, templates, etc (this is what the admin app talks to)
• asynchronous workers built using Celery to put things on queues and read them off to be processed, sent to providers, updated, etc

Setting Up

Python version

We run python 3.11 both locally and in production.

psycopg2

Follow these instructions on Mac M1 machines.

AWS credentials

To run the API you will need appropriate AWS credentials. See the Wiki for more details.

environment.sh

Creating and edit an environment.sh file.

echo "
export NOTIFY_ENVIRONMENT='development'

export MMG_API_KEY='MMG_API_KEY'
export FIRETEXT_API_KEY='FIRETEXT_ACTUAL_KEY'
export NOTIFICATION_QUEUE_PREFIX='YOUR_OWN_PREFIX'

export FLASK_APP=application.py
export FLASK_DEBUG=1
export WERKZEUG_DEBUG_PIN=off
"> environment.sh

Things to change:

• Replace YOUR_OWN_PREFIX with local_dev_<first name>.
• Run the following in the credentials repo to get the API keys.

notify-pass credentials/firetext
notify-pass credentials/mmg

Postgres

This app requires Postgres to run.

If you are using notifications-local, the correct Postgres version will be provided automatically by the docker-compose file.

If you are running this app manually, you will need to manage Postgres yourself. Install Postgres.app. Check the docker-compose file above to find the correct Postgres version to use.

When our unit tests are run in Concourse, Postgres is based into the container via the concourse_tests step of docker/Dockerfile.

Redis

To switch redis on you'll need to install it locally. On a Mac you can do:

# assuming you use Homebrew
brew install redis
brew services start redis

To use redis caching you need to switch it on with an environment variable:

export REDIS_ENABLED=1

uv

We use uv for Python dependency management. Follow the install instructions or run:

curl -LsSf https://astral.sh/uv/install.sh | sh

Pre-commit

We use pre-commit to ensure that committed code meets basic standards for formatting, and will make basic fixes for you to save time and aggravation.

Install pre-commit system-wide with, eg brew install pre-commit. Then, install the hooks in this repository with pre-commit install --install-hooks.

To run the application

# install dependencies, etc.
make bootstrap

# run the web app
make run-flask

# run the background tasks
make run-celery

# run scheduled tasks (optional)
make run-celery-beat

We've had problems running Celery locally due to one of its dependencies: pycurl. Due to the complexity of the issue, we also support running Celery via Docker:

# install dependencies, etc.
make bootstrap-with-docker

# run the background tasks
make run-celery-with-docker

# run scheduled tasks
make run-celery-beat-with-docker

To test the application

# install dependencies, etc.
make bootstrap

make test

To run one off tasks

Tasks are run through the flask command - run flask --help for more information. There are two sections we need to care about: flask db contains alembic migration commands, and flask command contains all of our custom commands. For example, to purge all dynamically generated functional test data, do the following:

Locally

flask command purge_functional_test_data -u <functional tests user name prefix>

To execute in ecs, you can use the ecs-exec.sh script

./scripts/ecs-exec/ecs-exec.sh
<select notify-api>
flask command purge_functional_test_data -u <functional tests user name prefix>

All flask commands and command options have a --help command if you need more information.

Further documentation

• Writing public APIs
• Updating dependencies