Email, search & push

Email

The server sends email for verifying addresses, resetting passwords and changing email addresses. It sends through any SMTP server, or Amazon SES.

SMTP, in .env:

EMAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=refract
SMTP_PASSWORD=...
SMTP_FROM="Refract.Chat <noreply@example.com>"

Amazon SES:

EMAIL_PROVIDER=ses
AWS_SES_ACCESS_KEY_ID=...
AWS_SES_SECRET_ACCESS_KEY=...
AWS_SES_REGION=us-east-1
SMTP_FROM="Refract.Chat <noreply@example.com>"

With SES, verify the sender address in the SES console and request production access first, since SES starts in sandbox mode. The SES keys fall back to AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY when they aren't set.

Without working email, leave email.verificationRequired off in app.config.yaml, or new accounts can't finish signing up.

Message search

Message search runs on Meilisearch, the search service in the Compose file. It's required: the server won't start without MEILI_URL.

• Set MEILI_MASTER_KEY in .env, at least 16 characters. The search container and the server share it.
• It holds a copy of message text, so keep it on the private Docker network, as the Compose file does. The database stays the source of truth: every result is checked against the database and the searcher's current permissions, so a stale index can only miss results, never show something it shouldn't.
• It needs no backup. If the index is ever empty, the server rebuilds it from the database, so data/search/ can be deleted at any time.
• If it's down, chat carries on and searches answer 503 search_unavailable until it's back.
• To rebuild it by hand, run docker compose run --rm backend yarn cli --reindex-search.

Push notifications

The mobile app gets notifications for direct messages, mentions and incoming calls through a push relay, which forwards them to Google (FCM) and Apple (APNs). Every push is encrypted for the phone: the relay, Google and Apple carry only a device token and ciphertext, never who it's for, who sent it or what it says. Only your Refract server and the phone can read it.

Instances use the project's relay at https://relay.refract.chat by default. To connect yours:

1. Open Manage instance → Config → Mobile push relay and choose Register for pushes. The instance signs the request with its identity key. No keys or tokens need copying.
2. The relay's operator approves the request.
3. Choose Check status. Once approved, the instance saves its relay credentials and starts sending pushes.

The credentials are saved to PUSH_RELAY_STATE_FILE, beside the federation key in /data/federation/. Keep both on persistent storage: losing them means asking for approval again. To use a different relay, set PUSH_RELAY_URL to its HTTPS address. Running your own relay is only needed with your own build of the mobile app; see Run with Docker.

People can send themselves a test notification from the app's notification settings.