Skip to content

Activity notifications ​

Stellarr can notify users about channel mentions and direct messages over email and Web Push when they opt in under Settings → Notifications.

Preferences apply at the moment a message is posted. Turning notifications on later does not send alerts for older messages.

Privacy design ​

Notifications avoid leaking private conversation data to external email relays or push providers:

  • No conversation details: Emails and push payloads exclude sender names, server names, channel names, and message text.
  • Generic localized text: Copy uses the instance language (STELLARR_LANGUAGE, en or pl) and links only to the instance root (STELLARR_PUBLIC_URL or STELLARR_DOMAIN), since channels and DMs have no public permalinks:
    • Mention: "Someone mentioned you in a channel. Open Stellarr to read it."
    • Direct message: "You have a new direct message. Open Stellarr to read it."
  • No PII in logs: Push endpoints, encryption keys, recipients, and message content are never logged.

Email notifications ​

Email notifications require:

  • Instance setup: Working mail transport (SMTP in Cockpit → Settings, or Resend under Integrations).
  • User setup: Email notifications enabled in Settings → Notifications, plus a confirmed email second factor on their current address.

NOTE

Activity notification emails use the instance's regular mail configuration whenever users enable them. They are independent of the security-alert email switch (mail.alerts.enabled). Server invitations continue using in-app notifications only.

Web Push ​

Web Push lets Stellarr wake a user's browser even when the Stellarr tab is closed. It stays disabled until you supply a persistent VAPID key pair and users enable Push notifications in Settings → Notifications.

1. Generate a persistent VAPID key pair ​

Generate one P-256 VAPID key pair per installation and store it with your instance secrets.

WARNING

Never regenerate VAPID keys on container restarts. Browsers bind subscriptions to the application server public key, so changing or losing the key breaks all existing subscriptions until users re-subscribe.

Using OpenSSL:

bash
openssl ecparam -name prime256v1 -genkey -noout -out vapid-private.pem
openssl ec -in vapid-private.pem -pubout -outform DER -out vapid-public.der

# Public key (base64url, 65 bytes decoded):
tail -c 65 vapid-public.der | base64 -w0 | tr '+/' '-_' | tr -d '='

# Private key (base64url, 32 bytes decoded):
priv_hex="$(openssl ec -in vapid-private.pem -text -noout 2>/dev/null \
  | awk '/priv:/{flag=1;next}/pub:/{flag=0}flag' | tr -d ' :\n')"
printf '%s' "$priv_hex" | xxd -r -p | base64 -w0 | tr '+/' '-_' | tr -d '='

On macOS BSD base64, omit -w0, or generate keys with npx web-push generate-vapid-keys.

2. Configure environment variables ​

Add the key pair to .env and apply with docker compose up -d:

dotenv
STELLARR_PUSH_ENABLED=true
STELLARR_PUSH_SUBJECT=mailto:admin@example.com
STELLARR_PUSH_PUBLIC_KEY=YOUR_PUBLIC_KEY
STELLARR_PUSH_PRIVATE_KEY=YOUR_PRIVATE_KEY
Compose .envASP.NET configDescription
STELLARR_PUSH_ENABLEDPush:EnabledTurns Web Push on when valid keys and subject are present.
STELLARR_PUSH_SUBJECTPush:Subjectmailto: address or https:// URL identifying the operator.
STELLARR_PUSH_PUBLIC_KEYPush:PublicKeyBase64url uncompressed P-256 public key (65 bytes decoded).
STELLARR_PUSH_PRIVATE_KEYPush:PrivateKeyBase64url P-256 private key (32 bytes decoded). Keep secret.

If keys are missing, malformed, or mismatched, the container still boots normally and reports Web Push as unavailable in Settings → Notifications.

NOTE

Browsers require HTTPS (or localhost during local development) for Service Workers and Web Push. Set STELLARR_DOMAIN or STELLARR_PUBLIC_URL so notification links target your public instance URL.

Subscription limits and security ​

PropertyLimit / Rule
Subscriptions per accountMaximum 10 active browser subscriptions (PUT/DELETE /api/me/push-subscriptions, status via GET /api/me/notification-delivery).
Ownership and session bindingBound to both account and active sign-in session. Conflicts return 409; once an older session ends, the same account can re-register that endpoint from a new session.
Endpoint validationMust be an absolute https:// URL on port 443 with no credentials or fragments. Private and reserved IP ranges are blocked before connecting, redirects are rejected, and proxies/cookies are not used.
Payload and privacyEncrypted camelCase JSON (id, title, body, url, tag), capped at 3072 UTF-8 bytes before encryption, 300 s TTL. Endpoints, keys, and Authorization headers are never logged.

Push service status handling ​

ResponseAction
2xxDelivered.
404, 410Subscription removed (Gone); not retried.
408, 425, 429, 5xx, timeout, network errorRetried with backoff (up to 5 attempts).
401, 403Retried; indicates a VAPID configuration problem rather than an expired browser subscription.
Other 4xx (e.g. 400, 413), 3xx redirectRetried up to the attempt cap without deleting the subscription.

Delivery, cancellation, and retries ​

Pending deliveries are stored in SQLite (NotificationDeliveries) and sent with at-least-once delivery: one item for the user's verified email address and one per active Web Push subscription.

Pre-send checks ​

Before calling an email or push provider, the dispatcher re-validates that the alert is still relevant and cancels it silently if:

  • The user disabled notifications or the account was disabled
  • The message was deleted, or an edit removed the mention
  • Either user blocked the other, the channel was deleted, or the user lost channel access
  • The user muted the channel or already read past the message
  • For direct messages: the user is no longer a participant or no longer allows DMs from that sender
  • For email: the verified email address changed or its email second factor was revoked
  • For Web Push: the subscription's session expired, was revoked, or its security version changed

Retry limits ​

RuleValue
Retry attemptsUp to 5 attempts with exponential backoff from 2 minutes to 1 hour
Missing mail transportEmail rows defer up to 1 hour without calling providers
Expiration and pruningUndelivered items expire after 7 days; completed rows prune after 30 days
Expired push endpoints404 or 410 deletes the push subscription and marks delivery complete
DeduplicationEmails send a stable idempotency key (activity-notification/<id>). Web Push lacks a provider-side key, so rare crash windows can repeat a push

Upgrades ​

The PushSubscriptions and NotificationDeliveries tables and indexes are created automatically on startup. Because push subscriptions bind to the current sign-in session, users reopen Settings → Notifications once after upgrading to re-save their browser subscription (browser keys stay valid while STELLARR_PUSH_PUBLIC_KEY stays unchanged).