Skip to main content
Open in Gitpod

​
Requirements

  • Node.js v22.22.1 (LTS). The repo requires Node >=22 <23 and pnpm ^11.
  • pnpm 11.x (required - the repo enforces pnpm via preinstall)
  • MongoDB
  • Redis
  • Docker (recommended for running MongoDB, Redis, and LocalStack together)
  • (Optional) LocalStack (required only for S3-related modules)
We recommend having at least 8GB of RAM to run Novu on a local machine as Novu has multiple services running together with external services like Redis, MongoDB, and more.

​
Setup the project

After installing Node.js and pnpm, clone and set up your forked version of the project:
1

Clone the repository

2

Install all dependencies

This installs dependencies with pnpm, creates default .env files from .example.env, and builds the monorepo.
3

Start infrastructure services

Start MongoDB, Redis, and LocalStack with Docker Compose:
4

Run the project

Recommended: use the mprocs dev runner (API, Dashboard, and shared packages):
Alternative: use the Jarvis CLI menu:
On first run, Jarvis can also install OS dependencies via Development environment setup.
The recommended pnpm dev:portless command starts the Dashboard, API, Worker, and shared packages through Portless proxies. If you only want to run parts of the platform, use these commands from the repo root:
  • start / jarvis - Interactive CLI to run the full stack or test suites
  • dev:portless - Recommended local dev runner (Dashboard, API, Worker, shared packages)
  • start:dashboard - Dashboard only (Vite on port 4201 by default)
  • start:api:dev - API in watch mode
  • start:ws - WebSocket service for real-time Inbox updates
  • start:worker - Worker application
  • start:webhook - Webhook service
  • start:dal - Data Access Layer package in watch mode
  • start:shared - Shared client and API library in watch mode
The legacy Widget and @novu/notification-center apps have been removed. Use the Inbox component (@novu/react) instead.

​
Set up your environment variables

If you used npm run setup:project or Jarvis, default .env files are created automatically. To test certain parts of Novu or run it in production mode, you may need to change some values. These are the main environment variables:
  • NODE_ENV (default: local) - The environment of the app. Possible values are: dev, test, production, ci, local
  • PORT - The port on which the API backend listens (default: 3000)
  • API_ROOT_URL - Public base URL for the API
  • FRONT_BASE_URL / DASHBOARD_URL - Dashboard URL (default local dev: http://127.0.0.1:4201)
  • DISABLE_USER_REGISTRATION (default: false) - If users should not be able to create new accounts
  • MONGO_URL - MongoDB connection string
  • REDIS_HOST, REDIS_PORT, REDIS_PASSWORD, REDIS_DB_INDEX - Redis queue connection
  • REDIS_CACHE_SERVICE_HOST, REDIS_CACHE_SERVICE_PORT - Optional Redis cache instance
  • IS_IN_MEMORY_CLUSTER_MODE_ENABLED - Enables Redis or ElastiCache cluster mode
  • JWT_SECRET - Secret used to sign authentication tokens
  • STORE_ENCRYPTION_KEY - Encrypts provider credentials (must be 32 characters)
  • NOVU_SECRET_KEY - Server-side API secret key
  • S3_LOCAL_STACK, S3_BUCKET_NAME, S3_REGION - LocalStack/S3 storage settings
  • SENTRY_DSN - Optional Sentry DSN for error reporting
  • NODE_ENV (default: local)
  • PORT - Worker health-check port (default: 3004)
  • STORE_ENCRYPTION_KEY - Must match the API value
  • MONGO_URL, REDIS_HOST, REDIS_PORT - Same infrastructure as the API
  • STORAGE_SERVICE - Storage backend: AWS, GCS, or AZURE
  • S3_LOCAL_STACK, S3_BUCKET_NAME, S3_REGION - Object storage settings
  • NEW_RELIC_ENABLED, NEW_RELIC_APP_NAME, NEW_RELIC_LICENSE_KEY - Optional New Relic settings
  • VITE_API_HOSTNAME - API base URL (default: http://localhost:3000)
  • VITE_WEBSOCKET_HOSTNAME - WebSocket base URL (default: http://localhost:3002)
  • VITE_DASHBOARD_URL - Dashboard URL (default local dev: http://localhost:4201)
  • VITE_SELF_HOSTED - Set when running a self-hosted deployment
  • VITE_SENTRY_DSN, VITE_LAUNCH_DARKLY_CLIENT_SIDE_ID - Optional telemetry and feature-flag settings
When using pnpm dev:portless, scripts/portless-dev-env.mjs resolves API, WebSocket, and Dashboard URLs at runtime. Run PORTLESS=0 pnpm start:dashboard to bypass Portless and use the values in your .env file directly.
  • NODE_ENV (default: local)
  • PORT - WebSocket service port (default: 3002)
  • JWT_SECRET - Must match the API value
  • REDIS_HOST, REDIS_PORT, REDIS_DB_INDEX, REDIS_PASSWORD
  • MONGO_URL
  • SENTRY_DSN - Optional Sentry DSN

​
Running tests

After making changes, run tests for the respective package using the appropriate commands.

​
API

To run API E2E tests through Jarvis, choose Test the project → API tests → API E2E tests. You can also run them directly:
The tests create a new instance of Novu and a test database, then remove the test database when finished.

​
Dashboard

Dashboard E2E tests use Playwright. Start the API, Worker, and WebSocket services in test mode, then run Playwright:
To open the Playwright UI for debugging:

​
Different ports used by the services

The community Docker self-hosted Dashboard runs on port 4000. That is different from the local Vite dev server on 4201.

​
Testing providers

To run tests against the providers folder:

​
Local environment setup script (beta)

Jarvis includes a Development environment setup option that runs this script. It tries to install OS dependencies needed to run Novu locally before npm run setup:project. You still need git and Node.js installed beforehand. The script can also be run directly:
On supported platforms it can:
  • Detect macOS or GNU/Linux
  • Install or update common OS dependencies (macOS only for some steps)
  • Install NVM, Node.js v22.22.1, pnpm, and Docker
  • Install MongoDB and Redis (macOS via Homebrew)
  • Optionally clone the Novu repository
This script has been tested most thoroughly on macOS. Linux support is limited.
This script is not bullet-proof. Some tasks have intertwined dependencies. Report problems on GitHub and we will try to help, but we cannot guarantee idempotency on every system.