Run Novu locally

⚡ Immediate working space with Gitpod

Requirements

• Node.js version v16.15.1
• MongoDB
• Redis
• (Optional) pnpm - Needed if you want to install new packages
• (Optional) localstack (required only in S3 related modules)

Need help installing the requirements? Read more here.

Setup the project

After installing the required services on your machine, you can clone and set up your forked version of the project:

• Fork Novu's repository. Clone or download your fork to your local machine.
• Run the project locally using npm run start.

The npm run start will start the Jarvis CLI tool which allows you to run the whole project with an ease. If you only want to run parts of the platform, you can use the following run commands from the root project:

• start:dev - Synonym to npm run start
• start:web - Only starts the web management platform
• start:ws - Only starts the WebSocket service for notification center updates
• start:widget - Starts the widget wrapper project that hosts the notification center inside an iframe
• start:api - Runs the API in watch mode
• start:worker - Runs the worker application in watch mode
• start:dal - Runs the Data Access Layer package in watch mode
• start:shared - Starts the watch mode for the shared client and API library
• start:node - Runs the @novu/node package in watch mode
• start:notification-center - Runs and builds the React package for the Novu notification center

Set up your environment variables

If you have used Jarvis CLI tool from the previous step you don't need to setup the env variables as Jarvis will do that on the first run if setup wasn't done before.

The command npm run setup:project creates default environment variables that are required to run Novu in a development environment. However, if you want to test certain parts of Novu or run it in production mode, you need to change some of them. These are all the available environment variables:

API Backend

• NODE_ENV (default: local)
  The environment of the app. Possible values are: dev, test, prod, ci, local
• S3_LOCAL_STACK
  The AWS endpoint for the S3 Bucket required for storing various media
• S3_BUCKET_NAME
  The name of the S3 Bucket
• S3_REGION
  The AWS region of the S3 Bucket
• PORT
  The port on which the API backend should listen on
• FRONT_BASE_URL
  The base url on which your frontend is accessible for the user. (e.g. web.novu.co)
• DISABLE_USER_REGISTRATION (default: false)
  If users should not be able to create new accounts. Possible values are: true, false
• REDIS_HOST
  The domain / IP of your redis instance
• REDIS_PORT
  The port of your redis instance
• REDIS_PASSWORD
  Optional password of your redis instance
• REDIS_DB_INDEX
  The Redis database index
• REDIS_CACHE_SERVICE_HOST
  The domain / IP of your redis instance for caching
• REDIS_CACHE_SERVICE_PORT
  The port of your redis instance for caching
• REDIS_DB_INDEX
  The Redis cache database index
• REDIS_CACHE_TTL
  The Redis cache ttl
• REDIS_CACHE_PASSWORD
  The Redis cache password
• REDIS_CACHE_CONNECTION_TIMEOUT
  The Redis cache connection timeout
• REDIS_CACHE_KEEP_ALIVE
  The Redis cache TCP keep alive on the socket timeout
• REDIS_CACHE_FAMILY
  The Redis cache IP stack version
• REDIS_CACHE_KEY_PREFIX
  The Redis cache prefix prepend to all keys
• REDIS_CACHE_SERVICE_TLS
  The Redis cache TLS connection support
• IN_MEMORY_CLUSTER_MODE_ENABLED
  The flag that enables the cluster mode. It might be Redis or ElastiCache cluster, depending on the env variables set for either service.
• ELASTICACHE_CLUSTER_SERVICE_HOST
  ElastiCache cluster host
• ELASTICACHE_CLUSTER_SERVICE_PORT
  ElastiCache cluster port
• REDIS_CLUSTER_SERVICE_HOST
  Redis cluster host
• REDIS_CLUSTER_SERVICE_PORTS
  Redis cluster ports
• REDIS_CLUSTER_DB_INDEX
  Redis cluster database index
• REDIS_CLUSTER_TTL
  Redis cluster ttl
• REDIS_CLUSTER_PASSWORD
  Redis cluster password
• REDIS_CLUSTER_CONNECTION_TIMEOUT
  Redis cluster connection timeout
• REDIS_CLUSTER_KEEP_ALIVE
  Redis cluster TCP keep alive on the socket timeout
• REDIS_CLUSTER_FAMILY
  Redis cluster IP stack version
• REDIS_CLUSTER_KEY_PREFIX
  Redis cluster prefix prepend to all keys
• JWT_SECRET
  The secret keybase which is used to encrypt / verify the tokens issued for authentication
• SENDGRID_API_KEY
  The api key of the Sendgrid account used to send various emails
• MONGO_URL
  The URL of your MongoDB instance
• NOVU_API_KEY
  The api key of web.novu.co used to send various emails
• SENTRY_DSN
  The DSN of sentry.io used to report errors happening in production

Worker

• NODE_ENV (default: local)
  The environment of the app. Possible values are: dev, test, prod, ci, local
• PORT
  The port on which the Worker app should listen on
• STORE_ENCRYPTION_KEY
  The encryption key used to encrypt/decrypt provider credentials
• MAX_NOVU_INTEGRATION_MAIL_REQUESTS
  The number of free emails that can be sent with the Novu email provider
• NOVU_EMAIL_INTEGRATION_API_KEY
  The Novu email provider Sentry API key
• STORAGE_SERVICE
  The storage service name: AWS, GCS, or AZURE
• S3_LOCAL_STACK
  The LocalStack service URL
• S3_BUCKET_NAME
  The name of the S3 Bucket
• S3_REGION
  The AWS region of the S3 Bucket
• GCS_BUCKET_NAME
  The name of the GCS Bucket
• AZURE_ACCOUNT_NAME
  The name of the Azure account
• AZURE_ACCOUNT_KEY
  The Azure account key
• AZURE_HOST_NAME
  The Azure host name
• AZURE_CONTAINER_NAME
  The Azure container name
• AWS_ACCESS_KEY_ID
  The AWS access key
• AWS_SECRET_ACCESS_KEY
  The AWS secret access key
• REDIS_HOST
  The domain / IP of your redis instance
• REDIS_PORT
  The port of your redis instance
• REDIS_PASSWORD
  Optional password of your redis instance
• REDIS_DB_INDEX
  The Redis database index
• REDIS_CACHE_SERVICE_HOST
  The domain / IP of your redis instance for caching
• REDIS_CACHE_SERVICE_PORT
  The port of your redis instance for caching
• REDIS_DB_INDEX
  The Redis cache database index
• REDIS_CACHE_TTL
  The Redis cache ttl
• REDIS_CACHE_PASSWORD
  The Redis cache password
• REDIS_CACHE_CONNECTION_TIMEOUT
  The Redis cache connection timeout
• REDIS_CACHE_KEEP_ALIVE
  The Redis cache TCP keep alive on the socket timeout
• REDIS_CACHE_FAMILY
  The Redis cache IP stack version
• REDIS_CACHE_KEY_PREFIX
  The Redis cache prefix prepend to all keys
• REDIS_CACHE_SERVICE_TLS
  The Redis cache TLS connection support
• IN_MEMORY_CLUSTER_MODE_ENABLED
  The flag that enables the cluster mode. It might be Redis or ElastiCache cluster, depending on the env variables set for either service.
• ELASTICACHE_CLUSTER_SERVICE_HOST
  ElastiCache cluster host
• ELASTICACHE_CLUSTER_SERVICE_PORT
  ElastiCache cluster port
• REDIS_CLUSTER_SERVICE_HOST
  Redis cluster host
• REDIS_CLUSTER_SERVICE_PORTS
  Redis cluster ports
• REDIS_CLUSTER_DB_INDEX
  Redis cluster database index
• REDIS_CLUSTER_TTL
  Redis cluster ttl
• REDIS_CLUSTER_PASSWORD
  Redis cluster password
• REDIS_CLUSTER_CONNECTION_TIMEOUT
  Redis cluster connection timeout
• REDIS_CLUSTER_KEEP_ALIVE
  Redis cluster TCP keep alive on the socket timeout
• REDIS_CLUSTER_FAMILY
  Redis cluster IP stack version
• REDIS_CLUSTER_KEY_PREFIX
  Redis cluster prefix prepend to all keys
• MONGO_URL
  The URL of your MongoDB instance
• NEW_RELIC_APP_NAME
  The New Relic app name
• NEW_RELIC_LICENSE_KEY
  The New Relic license key
• SEGMENT_TOKEN
  The Segment Analytics token

Web client

• REACT_APP_ENVIRONMENT
  The environment of the app. Possible values are: dev, test, prod, ci, local
• REACT_APP_API_URL
  The base url on which your API backend would be accessible
• REACT_APP_WS_URL
  The base url on which your WebSocket service would be accessible
• SKIP_PREFLIGHT_CHECK (default: true)
  Solves a problem with React App dependency tree.

danger

When configuring different than default values for the API and WebSocket URLs, in order for the Web app to apply the changes done to the ./env file, it is needed to run the script pnpm envsetup. This will generate a file called env-config.js that will be copied inside of the public folder of the application. Its purpose is to inject in the window._env_ object the chosen environment variables that manage the URLs the Web client will call to access to the API backend and the WebSocket service.

WebSocket Service

• NODE_ENV (default: local)
  The environment of the app. Possible values are: dev, test, prod, ci, local
• SENTRY_DSN
  The DSN of sentry.io used to report errors happening in production
• REDIS_HOST
  The domain / IP of your redis instance
• REDIS_PORT
  The port of your redis instance
• REDIS_DB_INDEX
  The database index of your redis instance
• REDIS_PASSWORD
  Optional password of your redis instance
• JWT_SECRET
  The secret keybase which is used to encrypt / verify the tokens issued for authentication
• MONGO_URL
  The URL of your MongoDB instance
• PORT
  The port on which the WebSocket service should listen on

Running tests

After making changes, you can run the tests for the respective package using the appropriate CLI commands:

API

To run the API tests, run the following command:

npm run start:worker:test
npm run start:e2e:api

The tests create a new instance of Novu and a test db and run the tests against it. The test db is removed after all tests have finished running.

Web

To run the front end tests for the web project using cypress you need to install localstack. The cypress tests perform E2E tests. To be able to perform E2E tests, you need to run the API service in the appropriate test environment.

Run the services in test env with the following commands:

npm run start:web
npm run start:api:test
npm run start:worker:test
npm run start:ws:test

Run the cypress test suite with the following command:

cd apps/web && npm run cypress:run

To open the cypress management window to debug tests, run the following commands:

cd apps/web && npm run cypress:open

Different ports used by the services the project spins up

• 3000 - API
• 3002 - WebSocket Service
• 3004 - Worker application
• 4200 - Web Management UI
• 4701 - Iframe embed for notification center
• 4500 - Widget Service

Testing providers

To run tests against the providers folder, you can use the npm run test:providers command.

Local environment setup script (beta)

As an option in our script runner Jarvis we have made available an option to run this script that will automatically try to install all the dependencies needed to be able to run Novu locally, as previous step of installing the project dependencies through pnpm install. When executing it inside Jarvis, you will need to have previously installed by yourself git and node, as we mentioned earlier on this page.

The script can be run on its own without any previously dependency installed, as it is prepared to execute the following tasks:

• Check of the running OS in the local machine (currently only MacOSx and GNU Linux supported)
• Install of OS dependencies (currently only MacOSx supported) -- MacOSx: It will execute the following tasks --- Will try to install or update XCode (skippable step; though XCode installs git that is a required dependency for later) --- Will install Rosetta for Apple CPUs --- Will set up some opinionated OS settings
• Will check if git is installed and if not will abort operation
• Will make ZSH as the default shell to be able to execute the next task
• Will (opinionatedly) install Oh My Zsh! (skippable task)
• Will (opinionatedly) install the Homebrew package manager and will set up your local environment to execute it besides adding some casks
• Will (opinionatedly) install NVM as Node.js version manager
• Will install the required Node.js version to be able to run Novu
• Will install PNPM as package manager, required dependency for some of the tasks inside Novu's scripts
• Will install Docker as containerized application development tool
• Will install required databases MongoDB (Community version) and Redis through Homebrew
• Will install the AWS CLI tool (not required to run Novu; it is a core maintainers used tool)
• Will create a local development domain local.novu.co in your local machine
• Will clone Novu repository in your local machine (skippable step) to a selected folder $HOME/Dev

danger

This script has only been thoroughly tested in MacOSx. Little testing has been run in GNU Linux.

info

This script is not bullet-proof and some of the tasks have intertwined dependencies with each other. We have tried to make it as idempotent as possible but some loose knots will probably show or because conflicts between versions of the different dependencies. Please report to us any problem found and we will try to fix or assist though we have not the resources to make it idempotent in every potential system and potential combinations.