> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novu.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Novu in local machine

> Prerequisites and steps to run Novu in local machine. Learn how to set up Novu on your local environment for testing and development.

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/novuhq/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 theme={null}
        git clone https://github.com/novuhq/novu.git
        cd novu
        ```
      </Tab>

      <Tab title="Forked Repo">
        ```shell theme={null}
        git clone https://github.com/{YOUR_GITHUB_USER_NAME}/novu.git
        cd novu
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install all dependencies">
    ```shell theme={null}
    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 theme={null}
    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 theme={null}
    pnpm dev:portless
    ```

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

    ```shell theme={null}
    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](https://github.com/vercel-labs/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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
npm run test:providers
```

## Local environment setup script (beta)

Jarvis includes a **Development environment setup** option that runs [this script](https://github.com/novuhq/novu/blob/next/scripts/dev-environment-setup.sh). 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 theme={null}
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>