Getting Started

Novu is an open source notification infrastructure platform. It provides a workflow engine, a dashboard and APIs to send notifications over in-app, email, SMS, push and chat channels, and manages subscribers, topics and user preferences. Available as an open web service in Eyevinn Open Source Cloud.

Prerequisites

Step 1: Create the database and cache

In app.osaas.io, create a PostgreSQL DocumentDB instance (for example novudb), then a FerretDB instance (for example novuferret) that points at it, and a Valkey instance (for example novuvalkey). Wait for each to be running before creating the next.

Note the internal DNS name and port of each instance. Use the internal names, not the public URLs:

  • 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. The user for FerretDB is postgres with the password of the DocumentDB instance.

Step 2: Store the database URL as a secret

The FerretDB connection string contains a password, so store it as a secret. Navigate to the Novu service, open the "Service Secrets" tab and create:

  • novudburl: mongodb://postgres:<password>@<ferretdb-internal-dns>:27017/?authSource=admin

If your Valkey requires authentication, store the password in a secret as well (for example novuredispw).

Step 3: Create the Novu instance

Create an instance of the Novu service and fill in:

Field Description Example
Name A unique name for the instance mynovu
DatabaseUrl FerretDB connection string. A database name (novu) is appended if missing {{secrets.novudburl}}
RedisHost Valkey host <valkey-internal-dns>
RedisPort Valkey port 6379

Use the default SCRAM authentication with authSource=admin. Do not add authMechanism=PLAIN; FerretDB on OSC rejects it.

Startup takes about 2 minutes. The instance can show as starting for a while because the API, worker and websocket service start one after another. Click on the instance card when the status is green and "running".

Step 4: First signup

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 you can set DisableUserRegistration to true so nobody else can register.

Usage Example

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": "user@example.com"}'

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 are both on that address).

Configuration

Setting Required Description
DatabaseUrl Yes FerretDB connection string
RedisHost Yes Valkey host
RedisPort Yes Valkey port
RedisPassword / RedisTls No If your Valkey requires authentication or TLS
DisableUserRegistration No Set to true after you have created your admin user to block further signups
JwtSecret / StoreEncryptionKey / NovuSecretKey No Generated automatically on first start and stored on the instance volume. Set them only if you want to control the values (StoreEncryptionKey must be exactly 32 characters). Store them as secrets and reference them with {{secrets.NAME}}
S3BucketName / S3Region / S3Endpoint / AwsAccessKeyId / AwsSecretAccessKey No S3-compatible storage for uploaded assets
LogLevel No info by default

Limitations

  • Not fully verified on OSC. A test instance on OSC started and connected to FerretDB and Valkey without errors in the logs (API, worker and websocket service running). Signup, login, workflow triggering and notification delivery were exercised on a local setup, but not on a live OSC instance, and authenticated websocket delivery to a browser was only tested locally. Digest, snooze and environment promote were not tested at all.
  • All-in-one deployment. The API, worker, websocket service, dashboard and a small reverse proxy run in a single container. They scale together, not independently.
  • 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. In local testing core flows worked (signup, login, organizations, subscribers, topics, workflows, triggering, in-app notifications), but FerretDB cannot create three of Novu's indexes (two partial unique indexes using $in and one duplicate-named index). This is non-fatal; 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. For anything beyond a trial, set JwtSecret, StoreEncryptionKey (exactly 32 characters) and NovuSecretKey explicitly when you create the instance. 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