Skip to main content

​
Prerequisites

​
Python Version

GOV.UK Notify API runs on Python 3.13 both locally and in production.

​
Required Services

  • PostgreSQL 15 - Database server
  • Redis - Caching and message broker (optional but recommended)
  • AWS credentials - For local development access

​
System Dependencies

​
PostgreSQL

If using notifications-local, PostgreSQL is provided automatically via Docker Compose. For manual setup:
  • Install Postgres.app on macOS
  • Use PostgreSQL 15 (check the docker-compose file for the exact version)

​
Redis

On macOS using Homebrew: 
brew install redis
brew services start redis
Enable Redis caching with an environment variable: 
export REDIS_ENABLED=1

​
psycopg2 on Apple M1/M2

On Mac M1/M2 machines, follow these special instructions to install psycopg2.

​
Installation

​
1. Install uv

We use uv for Python dependency management: 
curl -LsSf https://astral.sh/uv/install.sh | sh

​
2. Install pre-commit

We use pre-commit to ensure code quality and consistent formatting: 
# Install system-wide (macOS)
brew install pre-commit

# Install hooks in the repository
pre-commit install --install-hooks
Pre-commit runs automatically on commit and includes:
  • Trailing whitespace removal
  • End-of-file fixing
  • YAML validation
  • Debug statement detection
  • Ruff linting and formatting

​
3. Configure AWS Credentials

See the Notify Wiki for AWS setup details.

​
4. Create environment.sh

Create an environment.sh file in the project root: 
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
Customize the following:
  • Replace YOUR_OWN_PREFIX with local_dev_<your_first_name>
  • Get API keys from the credentials repo:
notify-pass credentials/firetext
notify-pass credentials/mmg

​
5. Bootstrap the Application

Run the bootstrap command to install dependencies and set up the database: 
make bootstrap
This command will:
  • Install Python dependencies from requirements_for_test.txt using uv
  • Create the notification_api database
  • Run database migrations
  • Generate the app version file

​
Running the Application

​
Standard Method

Run these commands in separate terminal windows: 
# Run the Flask web application (port 6011)
make run-flask

# Run Celery background workers
make run-celery

# Run Celery Beat scheduled tasks (optional)
make run-celery-beat

​
Docker Method (Alternative)

If you have issues with pycurl (a Celery dependency), you can run Celery via Docker: 
# Build Docker image
make bootstrap-with-docker

# Run Flask locally
make run-flask

# Run Celery workers in Docker
make run-celery-with-docker

# Run Celery Beat in Docker
make run-celery-beat-with-docker
You can also run Flask with Docker: 
# Development mode with Flask reloader
make run-flask-with-docker

# Production mode with Gunicorn
make run-gunicorn-with-docker

​
Database Migrations

Database migrations are managed using Alembic via Flask-Migrate: 
# Source environment variables
. environment.sh

# Run migrations
flask db upgrade

# Create a new migration
flask db migrate -m "Description of changes"

# Run migrations in Docker
make run-migrations-with-docker

​
Flask Commands

The application includes custom Flask commands for various tasks: 
# View all available commands
flask --help

# Database commands (Alembic)
flask db --help

# Custom application commands
flask command --help

# Example: Purge functional test data
flask command purge_functional_test_data -u <username_prefix>

​
Dependency Management

​
Installing Dependencies

Dependencies are managed through .in files and compiled to .txt files: 
# Freeze and sync requirements
make freeze-requirements
This command:
  1. Compiles requirements.in to requirements.txt
  2. Syncs the virtual environment
  3. Compiles requirements_for_test.in to requirements_for_test.txt
  4. Syncs test requirements

​
Updating notifications-utils

To bump the notifications-utils package to the latest version: 
make bump-utils
For more details, see Updating Dependencies.

​
Troubleshooting

​
Database Issues

# Recreate the database
dropdb notification_api
creatdb notification_api
. environment.sh && flask db upgrade

​
Celery Issues

If Celery fails to start due to pycurl issues, use the Docker method described above.

​
Redis Connection Issues

Ensure Redis is running: 
# Check if Redis is running
redis-cli ping

# Should return "PONG"

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us