Notifications Service — Deployment¶

Prerequisites¶

Node.js 20+
npm
Redis (or Valkey) — stream backend
PostgreSQL — same database as Auth Center
Firebase service account JSON file (from Firebase Console)

Install Dependencies¶

cd projects/notifications-service
npm install

Environment Variables¶

Copy .env.example to .env and fill in required values:

cp .env.example .env

Variable	Required	Default	Description
`REDIS_URL`	No	`redis://localhost:6379`	Redis connection URL
`JOBS_STREAM`	No	`stream.notifications.jobs`	Redis stream name
`CONSUMER_GROUP`	No	`notifications-worker`	Consumer group name
`CONSUMER_NAME`	No	`worker-{hostname}-{pid}`	Consumer identity (auto if not set)
`BLOCK_MS`	No	`5000`	XREADGROUP blocking timeout (ms)
`AUTOCLAIM_MIN_IDLE_MS`	No	`30000`	Idle time before XAUTOCLAIM reclaims message (ms)
`MAX_DELIVERY_COUNT`	No	`5`	Max delivery attempts before discard
`PG_HOST`	No	`localhost`	PostgreSQL host
`PG_PORT`	No	`5432`	PostgreSQL port
`PG_DATABASE`	Yes	—	Database name
`PG_USER`	Yes	—	Database user
`PG_PASSWORD`	Yes	—	Database password
`FCM_SERVICE_ACCOUNT_PATH`	Conditional	—	Path to Firebase service account JSON
`FCM_SERVICE_ACCOUNT_JSON`	Conditional	—	Firebase service account JSON as inline string
`LOG_LEVEL`	No	`info`	pino log level (`debug`, `info`, `warn`, `error`)

Either FCM_SERVICE_ACCOUNT_PATH or FCM_SERVICE_ACCOUNT_JSON must be set. The service exits on startup if neither is provided.

Database Initialisation¶

Run once to create the notifications schema and notification_log table:

psql "$DATABASE_URL" < sql/001_init.sql

Then run the DBA grants for cross-schema access (see INTEGRATIONS.md — Database Grants section).

Run¶

Development (with auto-reload via nodemon):

npm run dev

Production:

npm start
# or
node src/index.js

Graceful Shutdown¶

Send SIGTERM or SIGINT to initiate a clean shutdown. The service: 1. Stops accepting new stream messages 2. Closes the Redis connection 3. Drains and closes the PostgreSQL connection pool 4. Exits with code 0

In a container environment: set stopSignal: SIGTERM and allow at least 10 seconds for shutdown before SIGKILL.

Docker¶

A Dockerfile is present in projects/notifications-service/. Build and run:

docker build -t notifications-service .
docker run -d \
  --env-file .env \
  -v /etc/onewallet/fcm-service-account.json:/etc/onewallet/fcm-service-account.json:ro \
  notifications-service

The service has no inbound HTTP port — it only reads from Redis and writes to PostgreSQL + Firebase.

Logging¶

All logs are JSON via pino. Each log line includes: - level — log level - traceId — intent_id for payment notifications, UUID for others, null if unavailable - event — dot-notation event name (e.g., notifications.processed, notifications.token_removed) - Additional context fields depending on event