https://github.com/alphagov/notifications-api
GOV.UK Notify API
https://github.com/alphagov/notifications-api
government-as-a-platform govuk-notify
Last synced: 5 months ago
JSON representation
GOV.UK Notify API
- Host: GitHub
- URL: https://github.com/alphagov/notifications-api
- Owner: alphagov
- License: mit
- Created: 2015-11-18T13:57:17.000Z (about 10 years ago)
- Default Branch: main
- Last Pushed: 2025-05-08T16:04:03.000Z (8 months ago)
- Last Synced: 2025-05-08T22:49:46.102Z (8 months ago)
- Topics: government-as-a-platform, govuk-notify
- Language: Python
- Homepage: https://www.notifications.service.gov.uk/documentation
- Size: 27 MB
- Stars: 68
- Watchers: 22
- Forks: 27
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# GOV.UK Notify API
Contains:
- the public-facing REST API for GOV.UK Notify, which teams can integrate with using [our clients](https://www.notifications.service.gov.uk/documentation)
- an internal-only REST API built using Flask to manage services, users, templates, etc (this is what the [admin app](http://github.com/alphagov/notifications-admin) 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](https://github.com/psycopg/psycopg2/issues/1216#issuecomment-1068150544).
### AWS credentials
To run the API you will need appropriate AWS credentials. See the [Wiki](https://github.com/alphagov/notifications-manuals/wiki/aws-accounts#how-to-set-up-local-development) 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_`.
* 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](https://github.com/alphagov/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](http://postgresapp.com/). 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](https://github.com/astral-sh/uv) for Python dependency management. Follow the [install instructions](https://github.com/astral-sh/uv?tab=readme-ov-file#installation) or run:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Pre-commit
We use [pre-commit](https://pre-commit.com/) 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
```
To execute in ecs, you [can use the ecs-exec.sh script](https://github.com/alphagov/notifications-aws/blob/a1e8075926dc8d2f6c0b2e8f48479fc309742b35/scripts/ecs-exec/ecs-exec.sh)
```
./scripts/ecs-exec/ecs-exec.sh
flask command purge_functional_test_data -u
```
All flask commands and command options have a --help command if you need more information.
## Further documentation
- [Writing public APIs](docs/writing-public-apis.md)
- [Updating dependencies](https://github.com/alphagov/notifications-manuals/wiki/Dependencies)