Service: Novu - EyevinnOSC/community GitHub Wiki
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.
- 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.
Novu needs a MongoDB-compatible database and a Redis-compatible cache. Create these first and confirm each is running before the next:
-
PostgreSQL DocumentDB instance (for example
novudb). -
FerretDB instance (for example
novuferret) that points at it. The FerretDB user ispostgreswith the password of the DocumentDB instance. -
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, port27017 - Valkey:
<tenant>-<name>.valkey-io-valkey.svc.cluster.local, port6379
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.
| 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).
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.
- 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
$inand 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.