Configuration

Configuration Overview

GOV.UK Notify API uses environment variables for configuration. Configuration is managed through the Config class and environment-specific overrides. Reference: app/config.py:82-706

Required Environment Variables

Core Application

NOTIFY_ENVIRONMENT

string

required

Environment name: development, test, or production environment name.Default: development

SECRET_KEY

string

required

Flask secret key for session management and CSRF protection.Example: dev-notify-secret-key

DANGEROUS_SALT

string

required

Salt for cryptographic signing operations.Example: dev-notify-salt

Reference: config.py:108-109

Database Configuration

SQLALCHEMY_DATABASE_URI

string

required

PostgreSQL connection string.Format: postgresql+psycopg2://user:password@host:port/databaseExample: postgresql+psycopg2://localhost/notification_api

SQLALCHEMY_DATABASE_URI_BULK

string

Read replica connection string for bulk/analytics queries. Falls back to primary if not set.Format: postgresql+psycopg2://host1:port,host2:port/database (supports multiple hosts)

SQLALCHEMY_POOL_SIZE

integer

Database connection pool size per process.Default: 5

Reference: config.py:112-119, 174-186

Database Performance Tuning

DATABASE_STATEMENT_TIMEOUT_MS

integer

Statement timeout in milliseconds for primary database.Default: 1200000 (20 minutes)

DATABASE_STATEMENT_TIMEOUT_REPLICA_MS

integer

Statement timeout in milliseconds for replica database.Default: 1200000 (20 minutes)

DATABASE_MAX_PARALLEL_WORKERS

integer

Max parallel workers per query on primary database.Default: None (uses database default)

DATABASE_MAX_PARALLEL_WORKERS_REPLICA

integer

Max parallel workers per query on replica database.

DATABASE_DEFAULT_DISABLE_PARALLEL_QUERY

string

Set to 1 to disable parallel queries on primary.

Reference: config.py:200-212

Redis Configuration

REDIS_URL

string

Redis connection URL.Format: redis://host:port/dbExample: redis://localhost:6379/0

REDIS_ENABLED

string

Enable Redis caching. Set to 1 to enable, 0 to disable.Default: 1 (enabled unless explicitly set to 0)

Reference: config.py:139-143

AWS Configuration

AWS_REGION

string

AWS region for SQS, S3, and SES.Default: eu-west-1

AWS_ACCOUNT_ID

string

AWS account ID for SQS queue URLs.Default: 123456789012

NOTIFICATION_QUEUE_PREFIX

string

required

Prefix for SQS queue names to identify environment.Example: local_dev_john or production-

Reference: config.py:137, 170, 257

S3 Buckets

S3_BUCKET_CSV_UPLOAD

string

required

S3 bucket for CSV file uploads.

S3_BUCKET_CONTACT_LIST

string

required

S3 bucket for contact lists.

S3_BUCKET_LETTERS_PDF

string

required

S3 bucket for letter PDFs.

S3_BUCKET_TEMPLATE_EMAIL_FILES

string

required

S3 bucket for email template attachments.

S3_BUCKET_NOTIFICATION_DEEP_HISTORY

string

S3 bucket for archived notification history.

S3_BUCKET_REPORT_REQUESTS_DOWNLOAD

string

S3 bucket for report request downloads.

Reference: config.py:532-545

API Configuration

API_HOST_NAME

string

Public-facing API hostname.Example: https://api.notifications.service.gov.uk

API_HOST_NAME_INTERNAL

string

Internal API hostname (used on AWS for inter-service communication).

ADMIN_BASE_URL

string

URL of the admin application.Default: http://localhost:6012

Reference: config.py:83-88

API Keys and Secrets

INTERNAL_CLIENT_API_KEYS

json

required

JSON object mapping client IDs to API keys for internal services.Format: {"notify-admin": ["key1"], "notify-functional-tests": ["key2"]}

MMG_API_KEY

string

required

API key for MMG SMS provider.

FIRETEXT_API_KEY

string

required

API key for Firetext SMS provider.

FIRETEXT_INTERNATIONAL_API_KEY

string

API key for Firetext international SMS.Default: placeholder

ZENDESK_API_KEY

string

Zendesk API key for support ticket integration.

Reference: config.py:98, 122-130, 146

Optional Environment Variables

Logging

NOTIFY_LOG_LEVEL

string

Application log level.Options: DEBUG, INFO, WARNING, ERROR, CRITICALDefault: INFO

NOTIFY_LOG_LEVEL_HANDLERS

string

Log level for handlers. Falls back to NOTIFY_LOG_LEVEL.

NOTIFY_REQUEST_LOG_LEVEL

string

Log level for HTTP request logging.Default: INFO

Reference: config.py:151-154

Celery Configuration

CELERY_WORKER_LOG_LEVEL

string

Celery worker log level.Options: DEBUG, INFO, WARNING, ERROR, CRITICALDefault: CRITICAL

CELERY_BEAT_LOG_LEVEL

string

Celery Beat log level.Default: INFO

CELERYD_PREFETCH_MULTIPLIER

integer

Number of tasks a worker prefetches. Set to 1 for long-running tasks.Default: Celery default (4)

Reference: config.py:91-92, 480-482

Monitoring and Metrics

STATSD_HOST

string

StatsD hostname for metrics collection.Example: statsd.example.com

STATSD_PORT

integer

StatsD port.Default: 8125

STATSD_ENABLED

boolean

Automatically enabled if STATSD_HOST is set.

Reference: config.py:484-486

CRONITOR_ENABLED

string

Enable Cronitor monitoring. Set to 1 to enable.Default: 0

CRONITOR_KEYS

json

JSON object mapping task names to Cronitor monitor keys.

Reference: config.py:157-158

Performance Tuning

HTTP_SERVE_TIMEOUT_SECONDS

integer

Gunicorn worker timeout in seconds.Default: 30

NOTIFY_GUNICORN_DEBUG_POST_REQUEST_LOG_THRESHOLD_SECONDS

float

Log detailed diagnostics for requests exceeding this duration.

Reference: gunicorn_config.py:23, 25-26

NOTIFY_EVENTLET_STATS

string

Enable eventlet statistics. Set to 1 to enable.Default: 0

Reference: config.py:163

External Services

TEMPLATE_PREVIEW_API_HOST

string

Template preview service URL.Default: http://localhost:6013

TEMPLATE_PREVIEW_API_KEY

string

Template preview service API key.Default: my-secret-key

DOCUMENT_DOWNLOAD_API_HOST

string

Document download service URL.Default: http://localhost:7000

DOCUMENT_DOWNLOAD_API_HOST_INTERNAL

string

Internal document download service URL.

DOCUMENT_DOWNLOAD_API_KEY

string

Document download service API key.Default: auth-token

Reference: config.py:506-511

SMS Provider Configuration

MMG_URL

string

MMG API endpoint.Default: https://api.mmg.co.uk/jsonv2a/api.php

FIRETEXT_URL

string

Firetext API endpoint.Default: https://www.firetext.co.uk/api/sendsms/json

FROM_NUMBER

string

Default SMS sender number.

Reference: config.py:513-514, 547

SMS_PROVIDER_RESTING_POINTS

dict

Distribution of SMS traffic between providers (must total 100%).Default: {"mmg": 51, "firetext": 49}

Reference: config.py:222

Email Configuration

SES_STUB_URL

string

AWS SES stub URL for testing. When set, uses stub client instead of real SES.

NOTIFY_EMAIL_DOMAIN

string

Email domain for Notify-generated emails.Example: notifications.service.gov.uk

Reference: config.py:515, 530

Feature Flags

API_RATE_LIMIT_ENABLED

string

Enable API rate limiting. Set to 1 to enable.Default: 1

ANTIVIRUS_ENABLED

string

Enable antivirus scanning for uploaded files.Default: 1 (enabled in production)

REGISTER_FUNCTIONAL_TESTING_BLUEPRINT

string

SEND_ZENDESK_ALERTS_ENABLED

string

Send alerts to Zendesk. Set to 1 to enable.Default: 0

CHECK_SLOW_TEXT_MESSAGE_DELIVERY

string

Monitor and alert on slow SMS delivery. Set to 1 to enable.Default: 0

Reference: config.py:548-554

Notification Archiving

NOTIFICATION_DEEP_HISTORY_MIN_AGE_DAYS

integer

Minimum age in days before notifications are archived to S3.Default: 365

NOTIFICATION_DEEP_HISTORY_MAX_HOURS_ARCHIVED_IN_RUN

integer

Maximum hours of notifications to archive in a single run.Default: 240 (10 days)

NOTIFICATION_DEEP_HISTORY_S3_KEY_PREFIX

string

S3 key prefix for archived notifications.Default: “ (empty)

NOTIFICATION_DEEP_HISTORY_DELETE_ARCHIVED

string

Delete notifications from database after archiving. Set to 1 to enable.Default: 1

Reference: config.py:556-561

Environment-Specific Configuration

Development

Development environment automatically sets:

DEBUG = True
REDIS_ENABLED = False (unless explicitly set)
Development S3 bucket names
Local API endpoints
Test API keys for providers

Reference: config.py:572-639

Test

Test environment automatically sets:

TESTING = True
Test S3 bucket names
Mock Celery broker
Simulated email/SMS endpoints
SQLALCHEMY_RECORD_QUERIES = True

Reference: config.py:641-700

Example Configuration

Development Setup

Create environment.sh:

export NOTIFY_ENVIRONMENT='development'

export MMG_API_KEY='your-mmg-api-key'
export FIRETEXT_API_KEY='your-firetext-api-key'
export NOTIFICATION_QUEUE_PREFIX='local_dev_yourname'

export FLASK_APP=application.py
export FLASK_DEBUG=1
export WERKZEUG_DEBUG_PIN=off

export REDIS_ENABLED=1

Reference: README.md:22-37

Production Setup

export NOTIFY_ENVIRONMENT='production'

export SECRET_KEY='<secure-random-key>'
export DANGEROUS_SALT='<secure-random-salt>'

export SQLALCHEMY_DATABASE_URI='postgresql+psycopg2://user:pass@db:5432/notification_api'
export SQLALCHEMY_DATABASE_URI_BULK='postgresql+psycopg2://replica1:5432,replica2:5432/notification_api'

export REDIS_URL='redis://redis:6379/0'
export REDIS_ENABLED=1

export AWS_REGION='eu-west-1'
export AWS_ACCOUNT_ID='123456789012'
export NOTIFICATION_QUEUE_PREFIX='production-'

export STATSD_HOST='statsd.internal'
export CRONITOR_ENABLED=1

export API_HOST_NAME='https://api.notifications.service.gov.uk'
export ADMIN_BASE_URL='https://www.notifications.service.gov.uk'

Configuration Validation

The application validates configuration on startup:

Required variables must be set
Database connection is tested
AWS credentials are verified
Redis connection is tested (if enabled)

Check logs for configuration errors during startup.

Get Started

Core Concepts

API Guide

Operations

Configuration Overview

Required Environment Variables

Core Application

Database Configuration

Database Performance Tuning

Redis Configuration

AWS Configuration

S3 Buckets

API Configuration

API Keys and Secrets

Optional Environment Variables

Logging

Celery Configuration

Monitoring and Metrics

Performance Tuning

External Services

SMS Provider Configuration

Email Configuration

Feature Flags

Notification Archiving

Environment-Specific Configuration

Development

Test

Example Configuration

Development Setup

Production Setup

Configuration Validation

Build docs developers (and LLMs) love

Get Started

Core Concepts

API Guide

Operations

​Configuration Overview

​Required Environment Variables

​Core Application

​Database Configuration

​Database Performance Tuning

​Redis Configuration

​AWS Configuration

​S3 Buckets

​API Configuration

​API Keys and Secrets

​Optional Environment Variables

​Logging

​Celery Configuration

​Monitoring and Metrics

​Performance Tuning

​External Services

​SMS Provider Configuration

​Email Configuration

​Feature Flags

​Notification Archiving

​Environment-Specific Configuration

​Development

​Test

​Example Configuration

​Development Setup

​Production Setup

​Configuration Validation

Build docs developers (and LLMs) love

Configuration Overview

Required Environment Variables

Core Application

Database Configuration

Database Performance Tuning

Redis Configuration

AWS Configuration

S3 Buckets

API Configuration

API Keys and Secrets

Optional Environment Variables

Logging

Celery Configuration

Monitoring and Metrics

Performance Tuning

External Services

SMS Provider Configuration

Email Configuration

Feature Flags

Notification Archiving

Environment-Specific Configuration

Development

Test

Example Configuration

Development Setup

Production Setup

Configuration Validation