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
• Git

Quick Start

Get the code

Clone the Novu repo and enter the docker directory:

# Get the code
git clone --depth 1 https://github.com/novuhq/novu
 
# Go to the docker community folder
cd novu/docker/community
 
# Copy the example env file
cp .env.example .env

Configure Environment

Local Deployment

To run Novu in local machine, default configuration can be used. Start Novu with:

docker-compose up
 
## if above command is not working, use docker compose
docker compose up

Now visit http://localhost:4200 to start using Novu.

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 -f docker-compose.yml up

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

Securing Your Setup

While we provide example secrets for getting started, you should NEVER deploy your Novu setup using the defaults provided.

Update the .env file with your own secrets.

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 local studio 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
npm run dev

Nextjs based bridge application having one test workflow written using @novu/framework will be running on http://localhost:4000, Go to http://localhost:4000/api/novu to see status.

Setting Up Novu Studio

Novu Local Studio is a development environment that allows you to test and manage your workflows. The setup varies based on your deployment:

1. Running in local machine

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

npx novu@latest dev -d http://localhost:4200 -p <bridge_application_port>

Following actions will occur:

• Novu local studio will be started on default port 2002,
• Novu will generate a tunnel url that will forward the request to bridge application running on <bridge_application_port>
• Studio will use http://localhost:4200 as dashboard url

Using bridge application url as bridge url

To use bridge application url as bridge url, use below command:

npx novu@latest dev -d http://localhost:4200 -p <bridge_application_port> -t http://host.docker.internal:<bridge_application_port>
 
# example:
npx novu@latest dev -d http://localhost:4200 -p 4000 -t http://host.docker.internal:4000

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

2. Running in VPS

# update the bridge .env file with below variables
NOVU_API_URL=http://<vps-ip-address>:3000
 
# Start Novu Studio with your VPS dashboard URL and bridge application URL
npx novu@latest dev -d http://<vps-ip-address>:4200

Check all available flags with npx novu dev command

Synchronizing Workflows

1. For local deployment:

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

2. For VPS deployment:

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:

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

Triggering events with custom installation

When self-hosting Novu, in order to trigger an event you must first create a new Novu object and configure it with the proper backendUrl.

import { Novu } from '@novu/node';
 
const config = {
  backendUrl: '<REPLACE_WITH_SELF_HOSTED_BACKEND_URL>',
};
 
const novu = new Novu('<API_KEY>', config);
 
await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>', {
  to: {
    subscriberId: '<SUBSCRIBER_ID>',
  },
  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, we are caching data in the most heavily loaded areas of the system: the widget requests such as feed and unseen count, as well as common DAL requests during the execution of trigger event flow. These are the most heavily used areas of our system, and we hope that by implementing caching in these areas, we can improve performance in the near future.

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, web, and websocket connections.

The following environment variables are used to set the context path for each public service that Novu provides: API_CONTEXT_PATH WIDGET_CONTEXT_PATH WS_CONTEXT_PATH WEB_CONTEXT_PATH

These allow you to set the context path for each service independently or dependently of the GLOBAL_CONTEXT_PATH.

For example, if I was using a reverse proxy to serve Novu from company.com/novu, I would set the GLOBAL_CONTEXT_PATH to novu, and then set the API_CONTEXT_PATH to api, the WIDGET_CONTEXT_PATH to widget, the WS_CONTEXT_PATH to ws, and the WEB_CONTEXT_PATH to web.

This would produce the following urls: - API: company.com/novu/api - WIDGET: company.com/novu/widget - WS: company.com/novu/ws - WEB: company.com/novu/web

However the Service context path can be used entirely independently of the GLOBAL_CONTEXT_PATH.

For example, if I wanted to expose the api as novu-api, I would set the API_CONTEXT_PATH to novu-api without setting the GLOBAL_CONTEXT_PATH. This would producte the following url: - API: company.com/novu-api

FAQs

Local Tunnel and Self-Hosted Deployments

Novu uses a local tunnel as bridge url. It can be used as bridge url with local studio 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