Deploy with Docker

Docker compose is the easiest way to get started with self-hosted Novu. This guide will walk you through the steps to run all services in single virtual machine using docker compose. This guide uses latest docker images. If you are looking to self host 0.24.x version, checkout 0.24.x docs

Prerequisites

You need the following installed in your system:

Docker and docker-compose
curl and openssl (pre-installed on most systems)

Quick Start

Run the setup script to download the required files, generate secure secrets, and start Novu:

curl -fsSL https://raw.githubusercontent.com/novuhq/novu/next/docker/community/setup.sh | bash

To install into a specific directory, set NOVU_DIR:

curl -fsSL https://raw.githubusercontent.com/novuhq/novu/next/docker/community/setup.sh | NOVU_DIR=~/novu bash

The script will:

Download docker-compose.yml and .env.example into the target directory (defaults to ./novu)
Generate cryptographically random values for JWT_SECRET, STORE_ENCRYPTION_KEY, and NOVU_SECRET_KEY
Create a .env file with the generated secrets
Start all Novu services via docker compose up -d

Once complete, visit http://localhost:4000 to start using Novu.

If you already have a .env file in the target directory, the script will only fill in any missing secret values without overwriting existing configuration.

Configure Environment

VPS Deployment

When deploying to a VPS, update your .env file with your server’s information:

# Replace <vps-ip-address> with your VPS IP address
HOST_NAME=http://<vps-ip-address>

Start Novu on your VPS:

docker compose up -d

Access your dashboard at http://vps-ip-address:4000.

Securing Your Setup

If you used the setup script, secure random secrets were generated automatically for JWT_SECRET, STORE_ENCRYPTION_KEY, and NOVU_SECRET_KEY. If you cloned the repository manually, update the .env file with your own secrets before going to production.

Required Variables:

JWT_SECRET: Used by the API to generate JWT keys.
STORE_ENCRYPTION_KEY: Used to encrypt/decrypt the provider credentials. It must be 32 characters long.
HOST_NAME: Host name of your installation:
- To run in local machine: http://localhost
- To run in VPS: Your server’s IP address (e.g., http://<vps-ip-address>) or domain name
REDIS_CACHE_SERVICE_HOST and REDIS_HOST can have same value for small deployments. For larger deployments, it is recommended to use separate Redis instances for caching and queue management.

Configuration

To keep the setup simple, we made some choices that may not be optimal for production:

the database is in the same machine as the servers
the storage uses localstack instead of S3

We strongly recommend that you decouple your database before deploying.

Setting Up the Inbox Component

This section explains how to integrate the Novu Inbox component into your application when using a self-hosted Novu deployment.

Install the required packages

npm install @novu/react react-router-dom

Create the Inbox component

Create a component file (e.g., inbox.tsx) in your project:

import React from 'react';
import { Inbox } from '@novu/react';
import { useNavigate } from 'react-router';
 
export function NotificationCenter() {
  const navigate = useNavigate();
 
  return (
    <Inbox
      applicationIdentifier="YOUR_APPLICATION_IDENTIFIER"
      subscriber="YOUR_SUBSCRIBER_ID"
      backendUrl="http://<your-docker-host>:3000" // Docker host address where Novu API is running
      socketUrl="http://<your-docker-host>:3002" // Docker host address where Novu socket is running
      routerPush={(path: string) => navigate(path)}
    />
  );
}

Configure the environment URLs

Adjust the backendUrl and socketUrl based on your deployment:

Testing the connection

Once your application is running, you should see the bell icon in your navbar. Clicking it will open the notification inbox UI. To test notifications, create and trigger a workflow from your self-hosted Novu dashboard, selecting In-App as the channel. For more information on customizing the Inbox component, refer to the Inbox documentation.

Initializing the Server SDK

When using a self-hosted Novu deployment with your backend services, configure the server SDK to connect to your Docker-hosted Novu API instance.

Install the package

npm install @novu/api

pip install novu-py

go get github.com/novuhq/novu-go

composer require novuhq/novu

dotnet add package Novu

Maven:

<dependency>
  <groupId>co.novu</groupId>
  <artifactId>novu-java</artifactId>
  <version>LATEST</version>
</dependency>

Initialize the SDK

Configure the SDK with your self-hosted backend URL:

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: '<YOUR_SECRET_KEY_HERE>',
  serverURL: 'http://<your-docker-host>:3000',
});

import os
from novu_py import Novu

novu = Novu(
    secret_key=os.getenv('NOVU_SECRET_KEY', ''),
    server_url='http://<your-docker-host>:3000',
)

import (
    novugo "github.com/novuhq/novu-go"
    "os"
)

s := novugo.New(
    novugo.WithServerURL("http://<your-docker-host>:3000"),
    novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")),
)

use novu;

$novu = novu\Novu::builder()
    ->setServerURL('http://<your-docker-host>:3000')
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

using Novu;

var novu = new NovuSDK(
    serverUrl: "http://<your-docker-host>:3000",
    secretKey: "<YOUR_SECRET_KEY_HERE>"
);

import co.novu.Novu;

Novu novu = Novu.builder()
    .serverUrl("http://<your-docker-host>:3000")
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

# Set your self-hosted API base URL for REST calls
export NOVU_API_URL=http://<your-docker-host>:3000
export NOVU_SECRET_KEY=<YOUR_SECRET_KEY_HERE>

Configure for different environments

Adjust the backendUrl based on your deployment:

Triggering events

Once initialized, you can trigger notification events:

await novu.trigger({
  workflowId: 'workflowId',
  to: { subscriberId: 'subscriberId' },
  payload: {
    name: 'John Doe',
    orderId: 'ORDER_ID_123',
  },
});

novu.trigger(trigger_event_request_dto=novu_py.TriggerEventRequestDto(
    workflow_id='workflowId',
    to={'subscriber_id': 'subscriberId'},
    payload={'name': 'John Doe', 'orderId': 'ORDER_ID_123'},
))

_, err := s.Trigger(ctx, components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Payload: map[string]any{
        "name": "John Doe", "orderId": "ORDER_ID_123",
    },
}, nil)

$novu->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        payload: ['name' => 'John Doe', 'orderId' => 'ORDER_ID_123'],
    ),
);

await novu.TriggerAsync(new TriggerEventRequestDto {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto { SubscriberId = "subscriberId" }),
    Payload = new Dictionary<string, object>() {
        { "name", "John Doe" }, { "orderId", "ORDER_ID_123" },
    },
});

novu.trigger().body(TriggerEventRequestDto.builder()
    .workflowId("workflowId")
    .to(To2.of(SubscriberPayloadDto.builder().subscriberId("subscriberId").build()))
    .payload(Map.of("name", "John Doe", "orderId", "ORDER_ID_123"))
    .build()).call();

curl -X POST 'http://<your-docker-host>:3000/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
  "name": "workflowId",
  "to": { "subscriberId": "subscriberId" },
  "payload": { "name": "John Doe", "orderId": "ORDER_ID_123" }
}'

For more information on using the server SDKs, refer to the Server-Side SDKs documentation.

Setting up local development and bridge application

Setting Up the bridge application

The bridge application is application where workflow definition are written using @novu/framework. Here’s how to set it up:

# Initialize the bridge application
npx novu@latest init \
  --secret-key=<secret_key> \
  --api-url=http://localhost:3000

# Install dependencies
npm install

# Start the bridge application on a port that does not conflict with the Dashboard (4000)
npm run dev -- --port 4005

A Next.js bridge application with a sample @novu/framework workflow runs on the port you choose (for example http://localhost:4005). Visit http://localhost:4005/api/novu to verify the bridge endpoint.

The self-hosted Dashboard also runs on port 4000. Use a different port (such as 4005) for your bridge application to avoid a conflict.

Setting up local development

Local development with npx novu dev opens the Novu Dashboard in Local mode, so you can test and manage the workflows running on your machine. The setup varies based on your deployment:

Local
VPS

if novu is run using above docker compose command in local machine, use below commmand

npx novu@latest dev -d http://localhost:4000 -p 4005

Following actions will occur:

Your self-hosted Dashboard will open in the Local environment,
Novu will generate a tunnel url that will forward the request to bridge application running on <bridge_application_port>
The Local environment will use http://localhost:4000 as dashboard url

Using bridge application url as bridge urlTo use bridge application url as bridge url, use below command:

npx novu@latest dev -d http://localhost:4000 -p 4005 -t http://host.docker.internal:4005

In Windows OS, there are some additional steps:

stop the running docker compose process using ctrl + c
update the docker-compose.yml file and add below config with each service (api, dashboard, worker and ws)

extra_hosts:
    - "host.docker.internal:host-gateway"

start the docker compose process again using docker compose up
now you can use host.docker.internal as bridge url hostname inplace of localhost

# update the bridge .env file with below variables
NOVU_API_URL=http://<vps-ip-address>:3000

# Start local development with your VPS dashboard URL and bridge application URL
npx novu@latest dev -d http://<vps-ip-address>:4000

Check all available flags with npx novu dev command

Synchronizing Workflows

Local
VPS

npx novu@latest sync \
  --bridge-url <tunnel-url>/api/novu \
  --api-url http://localhost:3000 \
  --secret-key <secret_key>

npx novu@latest sync \
  --bridge-url <tunnel_url>/api/novu \
  --api-url http://<vps-ip-address>:3000 \
  --secret-key <secret_key>

VPS Security Considerations

When deploying to a VPS, consider these additional security measures:

Use a firewall to restrict access to only necessary ports
Set up SSL/TLS certificates for HTTPS access
Regularly update your Docker images and host system
Use strong, unique secrets in your .env file
Consider using a reverse proxy like Nginx for additional security layers

Triggering events with custom installation

When self-hosting Novu, configure your server SDK with the self-hosted serverURL (or server_url) before triggering events.

import { Novu } from '@novu/api';

const novu = new Novu({
  secretKey: '<YOUR_SECRET_KEY_HERE>',
  serverURL: 'http://<your-docker-host>:3000',
});

await novu.trigger({
  workflowId: 'workflowId',
  to: { subscriberId: 'subscriberId' },
  payload: {},
});

from novu_py import Novu

novu = Novu(
    secret_key='<YOUR_SECRET_KEY_HERE>',
    server_url='http://<your-docker-host>:3000',
)

novu.trigger(trigger_event_request_dto={
    'workflow_id': 'workflowId',
    'to': {'subscriber_id': 'subscriberId'},
    'payload': {},
})

s := novugo.New(
    novugo.WithServerURL("http://<your-docker-host>:3000"),
    novugo.WithSecurity(os.Getenv("NOVU_SECRET_KEY")),
)

_, err := s.Trigger(ctx, components.TriggerEventRequestDto{
    WorkflowID: "workflowId",
    To: components.CreateToSubscriberPayloadDto(components.SubscriberPayloadDto{
        SubscriberID: "subscriberId",
    }),
    Payload: map[string]any{},
}, nil)

$novu = novu\Novu::builder()
    ->setServerURL('http://<your-docker-host>:3000')
    ->setSecurity('<YOUR_SECRET_KEY_HERE>')
    ->build();

$novu->trigger(
    triggerEventRequestDto: new Components\TriggerEventRequestDto(
        workflowId: 'workflowId',
        to: new Components\SubscriberPayloadDto(subscriberId: 'subscriberId'),
        payload: [],
    ),
);

var novu = new NovuSDK(
    serverUrl: "http://<your-docker-host>:3000",
    secretKey: "<YOUR_SECRET_KEY_HERE>"
);

await novu.TriggerAsync(new TriggerEventRequestDto {
    WorkflowId = "workflowId",
    To = To.CreateSubscriberPayloadDto(new SubscriberPayloadDto { SubscriberId = "subscriberId" }),
});

Novu novu = Novu.builder()
    .serverUrl("http://<your-docker-host>:3000")
    .secretKey("<YOUR_SECRET_KEY_HERE>")
    .build();

novu.trigger().body(TriggerEventRequestDto.builder()
    .workflowId("workflowId")
    .to(To2.of(SubscriberPayloadDto.builder().subscriberId("subscriberId").build()))
    .build()).call();

curl -X POST 'http://<your-docker-host>:3000/v1/events/trigger' \
-H 'Content-Type: application/json' \
-H 'Authorization: ApiKey <NOVU_SECRET_KEY>' \
-d '{
  "name": "workflowId",
  "to": { "subscriberId": "subscriberId" },
  "payload": {}
}'

Caching

We are introducing the first stage of caching in our system to improve performance and efficiency. Caching is turned off by default, but can easily be activated by setting the following environment variables:

REDIS_CACHE_SERVICE_HOST
REDIS_CACHE_SERVICE_PORT

Currently, caching is applied in the most heavily loaded areas of the system: Inbox feed and unseen-count requests, as well as common DAL requests during the trigger-event flow.

Reverse-Proxy / Load Balancers

To implement a reverse-proxy or load balancer in front of Novu, you need to set the GLOBAL_CONTEXT_PATH for the base path of the application. This is the path that the application will be served from after the domain. For example: - company.com/novu This is used to set the base path for the application, and is used to set the base path for the API, Dashboard, and WebSocket connections. The following environment variables set the context path for each public service: API_CONTEXT_PATH, WS_CONTEXT_PATH, WEBHOOK_CONTEXT_PATH, and FRONT_BASE_CONTEXT_PATH. These can be set independently or together with GLOBAL_CONTEXT_PATH. For example, to serve Novu from company.com/novu, set GLOBAL_CONTEXT_PATH=novu, then set API_CONTEXT_PATH=api and WS_CONTEXT_PATH=ws. That produces:

API: company.com/novu/api
WS: company.com/novu/ws

You can also set a service context path without GLOBAL_CONTEXT_PATH. For example, API_CONTEXT_PATH=novu-api exposes the API at company.com/novu-api. The Dashboard container is served separately on its configured port (default 4000) and is not controlled by these API/WS context-path variables.

These env variables should be present on all services novu provides due to tight coupling.

FAQs

Local Tunnel and Self-Hosted Deployments

Novu uses a local tunnel as bridge url. It can be used as bridge url during local development (npx novu dev) and for testing purpose in development environment. It should not be used in production environment. It is recommended to use deployed application url as bridge url

When is Local Tunnel Not Required?

If the customer’s application and the self-hosted Novu deployment are within the same network, there is no need for a local tunnel. In this case, the application can communicate directly with Novu through the internal network. Checkout Using bridge application url as bridge url section to learn more.

When is Local Tunnel Required?

If the application and Novu deployment reside on different networks, you can still interact with your self-hosted Novu instance using the Novu CLI. The CLI allows you to specify the Dashboard URL and Bridge Endpoint Origin to enable communication across networks via the Novu Cloud Local Tunnel.For example, you can use the following command:

npx novu@latest dev -d http://my-self-hosted-novu-domain.com:my-port

​Prerequisites

​Quick Start

​Configure Environment

​VPS Deployment

​Securing Your Setup

​Required Variables:

​Configuration

​Setting Up the Inbox Component

​Install the required packages

​Create the Inbox component

​Configure the environment URLs

​Testing the connection

​Initializing the Server SDK

​Install the package

​Initialize the SDK

​Configure for different environments

​Triggering events

​Setting up local development and bridge application

​Setting Up the bridge application

​Setting up local development

​Synchronizing Workflows

​VPS Security Considerations

​Triggering events with custom installation

​Caching

​Reverse-Proxy / Load Balancers

​FAQs

Prerequisites

Quick Start

Configure Environment

VPS Deployment

Securing Your Setup

Required Variables:

Configuration

Setting Up the Inbox Component

Install the required packages

Create the Inbox component

Configure the environment URLs

Testing the connection

Initializing the Server SDK

Install the package

Initialize the SDK

Configure for different environments

Triggering events

Setting up local development and bridge application

Setting Up the bridge application

Setting up local development

Synchronizing Workflows

VPS Security Considerations

Triggering events with custom installation

Caching

Reverse-Proxy / Load Balancers

FAQs