Run Novu in local machine - Novu

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)

<Note> 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. </Note>

Setup the project

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

<Steps> <Step title="Clone the repository"> <Tabs> <Tab title="Novu Org"> ```shell git clone https://github.com/novuhq/novu.git cd novu ``` </Tab> <Tab title="Forked Repo"> ```shell git clone https://github.com/{YOUR_GITHUB_USER_NAME}/novu.git cd novu ``` </Tab> </Tabs> </Step> <Step title="Install all dependencies"> ```shell npm run setup:project ```

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

</Step> <Step title="Start infrastructure services"> Start MongoDB, Redis, and LocalStack with Docker Compose:

```shell
docker compose -f docker/local/docker-compose.yml up -d
```

</Step> <Step title="Run the project"> **Recommended:** use the mprocs dev runner (API, Dashboard, and shared packages):

```shell
pnpm dev:portless
```

**Alternative:** use the Jarvis CLI menu:

```shell
npm run start
```

On first run, Jarvis can also install OS dependencies via **Development environment setup**.

</Step> </Steps>

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

<Note> The legacy Widget and `@novu/notification-center` apps have been removed. Use the [Inbox component](/platform/inbox) (`@novu/react`) instead. </Note>

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:

<AccordionGroup> <Accordion title="API Backend"> - `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 </Accordion> <Accordion title="Worker"> - `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 </Accordion> <Accordion title="Dashboard"> - `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

<Note>
  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.
</Note>

</Accordion> <Accordion title="WebSocket"> - `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 </Accordion> </AccordionGroup>

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:

shell

npm run start:worker:test
pnpm --filter @novu/api-service test:e2e:novu-v2

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:

shell

npm run start:api:test
npm run start:worker:test
npm run start:ws:test
cd apps/dashboard && pnpm test:e2e

To open the Playwright UI for debugging:

shell

cd apps/dashboard && pnpm test:e2e:ui

Different ports used by the services

Port	Service
3000	API
3002	WebSocket
3003	Webhook
3004	Worker
4201	Dashboard (local Vite dev server)
4566	LocalStack (S3)

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

Testing providers

To run tests against the providers folder:

shell

npm run test:providers

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:

shell

npm run dev-environment-setup

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

<Warning> This script has been tested most thoroughly on macOS. Linux support is limited. </Warning> <Note> 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. </Note>