Service: Novu - EyevinnOSC/community GitHub Wiki

Novu

Novu (serviceId novuhq-novu) is open-source notification infrastructure: a workflow engine, a dashboard and APIs to send notifications over in-app, email, SMS, push and chat channels, with subscribers, topics and user preferences. In Eyevinn Open Source Cloud (OSC) it is a long-running service instance with up to 5 GiB of storage per instance. The community edition is provided.

What it can do

  • Send notifications through one API across In-App/Inbox, email, SMS, push and chat.
  • Define workflows with branching and conditions, and batch notifications with the digest engine.
  • Embed a real-time Inbox component and a preferences component so end users control what they receive.
  • Manage subscribers, topics and preferences.

Creating an instance

Novu needs a MongoDB-compatible database and a Redis-compatible cache. Create these first and confirm each is running before the next:

  1. PostgreSQL DocumentDB instance (for example novudb).
  2. FerretDB instance (for example novuferret) that points at it. The FerretDB user is postgres with the password of the DocumentDB instance.
  3. Valkey instance (for example novuvalkey).

Use the internal DNS names, not the public URLs. describe-service-instance returns the internalEndpoint; the pattern is:

  • FerretDB: <tenant>-<name>.ferretdb-ferretdb.svc.cluster.local, port 27017
  • Valkey: <tenant>-<name>.valkey-io-valkey.svc.cluster.local, port 6379

The Valkey instance details only show an external address, so use the internal name above.

Store the FerretDB connection string as a service secret with create-service-secret (serviceId novuhq-novu), for example novudburl with mongodb://postgres:<password>@<ferretdb-internal-dns>:27017/?authSource=admin. Use the default SCRAM authentication with authSource=admin; do not add authMechanism=PLAIN, which FerretDB on OSC rejects. If your Valkey requires a password, store it as a secret too (for example novuredispw).

Then call create-service-instance with serviceId: "novuhq-novu"; the instance name must be alphanumeric and at most 20 characters.

{
  "name": "mynovu",
  "DatabaseUrl": "{{secrets.novudburl}}",
  "RedisHost": "<valkey-internal-dns>",
  "RedisPort": "6379"
}

Startup takes about 2 minutes: the API, worker and websocket service start one after another, so the instance can show as starting for a while. Use wait-for-service-ready or get-instance-status and get-logs-for-instance to follow it.

Options

Option Required Type Meaning
name Yes string Name of the instance. Alphanumeric, at most 20 characters.
DatabaseUrl Yes string, sensitive FerretDB (MongoDB-compatible) connection string. A database name (novu) is appended if missing.
RedisHost Yes string Host of the Redis-compatible cache (Valkey), for example its internal DNS name.
RedisPort Yes string Port of the cache, for example 6379.
RedisPassword No string, sensitive Password, if your Valkey requires authentication.
RedisTls No string Enables TLS towards Redis if your Valkey requires it. The catalog does not specify accepted values.
DisableUserRegistration No boolean Set to true after you have created your admin user to block further signups.
JwtSecret No string, sensitive Secret for signing sessions. Generated automatically on first start and stored on the instance volume if not set.
StoreEncryptionKey No string, sensitive Key for encrypting stored integration credentials. Must be exactly 32 characters. Generated automatically if not set.
NovuSecretKey No string, sensitive Novu secret key. Generated automatically if not set.
LogLevel No string Log level of the application. info by default.
S3BucketName No string Bucket in S3-compatible storage for uploaded assets.
S3Region No string Region of the S3 bucket.
S3Endpoint No string Endpoint URL of the S3-compatible storage.
AwsAccessKeyId No string, sensitive Access key for the S3-compatible storage.
AwsSecretAccessKey No string, sensitive Secret key for the S3-compatible storage.

Store sensitive options as service secrets and pass them as {{secrets.NAME}}, which only works as the entire field value. Overwriting a secret does not restart a running instance. For anything beyond a trial, set JwtSecret, StoreEncryptionKey and NovuSecretKey explicitly (see Limitations).

Using the instance

Open the instance URL while signed in to your OSC account. The dashboard and the API are served from the same address. OSC protects all paths other than / with your OSC login, so a blank page means you need to sign in at app.osaas.io first.

Click sign up and create the first account with an email and password; the first account creates your organization. Afterwards set DisableUserRegistration to true (for example with update-service-instance) so nobody else can register.

Create a workflow with an in-app step in the dashboard and copy your API key (Settings, API Keys). Then create a subscriber and trigger the workflow:

curl -X POST https://<your-instance-url>/v1/subscribers \
  -H "Authorization: ApiKey <your-api-key>" -H "Content-Type: application/json" \
  -d '{"subscriberId": "user-1", "email": "[email protected]"}'

curl -X POST https://<your-instance-url>/v1/events/trigger \
  -H "Authorization: ApiKey <your-api-key>" -H "Content-Type: application/json" \
  -d '{"name": "<workflow-id>", "to": "user-1", "payload": {}}'

Point your Novu SDK or inbox component at your instance URL; API and websocket share that address.

Limitations

  • All-in-one deployment. The API, worker, websocket service, dashboard and a small reverse proxy run in a single container and scale together.
  • Community edition only. Enterprise features (billing, SSO/organization sync, managed agents, AI features and similar) are proprietary and not included.
  • FerretDB compatibility. Novu officially targets MongoDB. FerretDB cannot create three of Novu's indexes (two partial unique indexes using $in and one duplicate-named index). This is non-fatal, but the affected uniqueness constraints (Slack/MS Teams chat user mapping, workflow/template type uniqueness) are not enforced by the database.
  • Persistent volume. Generated secrets live in /data. If you lose the volume but keep the database, the generated values are gone, stored integration credentials cannot be decrypted and existing sessions become invalid.
  • Email, SMS and push. Provider integrations (SendGrid, Twilio, FCM and others) are configured in the dashboard and need your own provider accounts.

Resources

⚠️ **GitHub.com Fallback** ⚠️