Deploying Novu

Introduction

Novu is an open-source notification infrastructure platform designed to simplify the implementation of notification systems in applications. It provides a unified API and dashboard for managing in-app notifications, emails, SMS, push notifications, and chat messages across multiple channels.

Built with a developer-first approach, Novu offers SDKs for major programming languages, a visual workflow editor, and a notification center component that can be embedded directly into your applications. The platform handles the complexity of notification delivery, retry logic, and user preferences while providing detailed analytics.

Key highlights of Novu:

Multi-Channel Support: Email, SMS, push, in-app, and chat notifications
Workflow Editor: Visual designer for complex notification flows
Notification Center: Embeddable React component for in-app notifications
Template Engine: Dynamic templates with variable substitution
User Preferences: Subscriber-level notification preferences
Provider Integrations: 50+ integrations (SendGrid, Twilio, Firebase, etc.)
Digest Engine: Aggregate multiple notifications into summaries
Delay Actions: Schedule notifications with timing controls
Activity Feed: Track all notification activity
Multiple SDKs: Node.js, Python, PHP, Ruby, Go, and more
Open Source: MIT licensed with active community

This guide walks through deploying Novu on Klutch.sh using Docker.

Why Deploy Novu on Klutch.sh

Deploying Novu on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the multi-service deployment automatically.

Persistent Storage: Attach persistent volumes for your notification data and configurations.

HTTPS by Default: Automatic SSL certificates ensure secure API and dashboard access.

GitHub Integration: Version-controlled deployments through your GitHub repository.

Scalable Resources: Allocate CPU and memory based on your notification volume.

Environment Variable Management: Securely store API keys and provider credentials.

Custom Domains: Use your own domain for your notification infrastructure.

Always-On Availability: Your notification system remains accessible 24/7.

Prerequisites

Before deploying Novu on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
A MongoDB database (MongoDB Atlas or self-hosted)
A Redis instance for queue management
(Optional) Provider credentials (SendGrid, Twilio, etc.)
(Optional) A custom domain for your Novu instance

Understanding Novu Architecture

Novu consists of several microservices:

API Service: Handles all REST API requests and business logic.

Worker Service: Processes notification jobs from the queue.

Web Dashboard: Management interface for workflows and configuration.

Widget Service: Serves the embeddable notification center.

MongoDB: Stores subscribers, templates, workflows, and activity.

Redis: Message queue for job processing and caching.

Deploying Novu on Klutch.sh

Create Your GitHub Repository

Create a new GitHub repository for your Novu deployment configuration.

Create the Dockerfile

Create a Dockerfile in your repository root:

FROM ghcr.io/novuhq/novu/api:latest

# Environment configuration
ENV NODE_ENV=production
ENV PORT=3000

# MongoDB and Redis configuration
ENV MONGO_URL=${MONGO_URL}
ENV REDIS_HOST=${REDIS_HOST}
ENV REDIS_PORT=${REDIS_PORT}

# Security
ENV JWT_SECRET=${JWT_SECRET}
ENV STORE_ENCRYPTION_KEY=${STORE_ENCRYPTION_KEY}

EXPOSE 3000

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
`NODE_ENV`	`production`
`MONGO_URL`	Your MongoDB connection string
`REDIS_HOST`	Your Redis host
`REDIS_PORT`	`6379`
`JWT_SECRET`	Generate a secure random string
`STORE_ENCRYPTION_KEY`	Generate a 32-character key
`API_ROOT_URL`	`https://your-app.klutch.sh`

Deploy Worker Service

Create a separate app for the worker:

FROM ghcr.io/novuhq/novu/worker:latest

ENV NODE_ENV=production
ENV MONGO_URL=${MONGO_URL}
ENV REDIS_HOST=${REDIS_HOST}
ENV REDIS_PORT=${REDIS_PORT}

Deploy Web Dashboard

Create another app for the dashboard:

FROM ghcr.io/novuhq/novu/web:latest

ENV REACT_APP_API_URL=https://your-api-app.klutch.sh
ENV REACT_APP_ENVIRONMENT=production

EXPOSE 4200

Configure All Services

Ensure all services share the same MongoDB and Redis connections.

Access the Dashboard

Once deployed, access the web dashboard and create your admin account.

Initial Configuration

Creating Your Organization

Set up your Novu organization:

Access the web dashboard
Create your admin account
Set up your organization details
Generate API keys

Configuring Providers

Enable notification channels:

Navigate to Settings > Integrations
Add email provider (SendGrid, Mailgun, etc.)
Add SMS provider (Twilio, Plivo, etc.)
Configure push notification service

Creating Workflows

Design notification workflows:

Go to Workflows in the dashboard
Click “Create Workflow”
Drag and drop steps
Configure triggers and templates

Using Novu

Sending Notifications (Node.js)

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

const novu = new Novu('YOUR_API_KEY');

await novu.trigger('workflow-identifier', {
  to: {
    subscriberId: 'user-123',
    email: 'user@example.com'
  },
  payload: {
    name: 'John',
    message: 'Welcome to our platform!'
  }
});

Managing Subscribers

await novu.subscribers.identify('user-123', {
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe'
});

Notification Center

Embed the notification center in React:

import { NovuProvider, PopoverNotificationCenter } from '@novu/notification-center';

function App() {
  return (
    <NovuProvider
      subscriberId="user-123"
      applicationIdentifier="YOUR_APP_ID"
    >
      <PopoverNotificationCenter>
        {({ unseenCount }) => <BellIcon count={unseenCount} />}
      </PopoverNotificationCenter>
    </NovuProvider>
  );
}

Workflow Features

Digest Notifications

Aggregate multiple notifications:

Add a Digest step to your workflow
Configure digest interval
Use digest template for summary

Delay Actions

Schedule notification timing:

Add Delay step
Set delay duration
Continue workflow after delay

Conditional Logic

Add branching logic:

Use conditions based on payload
Route to different channels
Personalize content

Production Best Practices

Performance Optimization

Use Redis cluster for high volume
Configure worker concurrency
Enable caching appropriately
Monitor queue lengths

Security Recommendations

Rotate API keys regularly
Encrypt sensitive data
Use HTTPS for all endpoints
Implement rate limiting

Monitoring

Track delivery rates
Monitor worker health
Set up alerting for failures
Review activity logs

Troubleshooting Common Issues

Notifications Not Delivered

Check provider configuration
Verify subscriber data
Review workflow triggers
Check activity feed for errors

Worker Not Processing

Verify Redis connection
Check worker logs
Ensure queue is accessible
Monitor memory usage

Dashboard Not Loading

Verify API URL configuration
Check CORS settings
Review browser console errors

Additional Resources

Conclusion

Deploying Novu on Klutch.sh provides a complete notification infrastructure for your applications. With its visual workflow editor, multi-channel support, and embeddable notification center, Novu simplifies building sophisticated notification systems while maintaining full control over your data and infrastructure.