Community
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.
Requirements
- Node.js version v20.8.1
- MongoDB
- Redis
- (Optional) pnpm - Needed if you want to install new packages
- (Optional) localstack (required only in 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 etc.
Setup the project
After installing the required services on your machine, you can clone and set up your forked version of the project:- Clone the repository
- Install all dependencies
- Run the project
npm run start will start the Jarvis CLI tool which allows you to run the whole project with 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/nodepackage 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 commandnpm 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
API Backend
NODE_ENV(default: local)The environment of the app. Possible values are: dev, test, production, ci, localS3_LOCAL_STACKThe AWS endpoint for the S3 Bucket required for storing various mediaS3_BUCKET_NAMEThe name of the S3 BucketS3_REGIONThe AWS region of the S3 BucketPORTThe port on which the API backend should listen onFRONT_BASE_URLThe 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, falseREDIS_HOSTThe domain / IP of your redis instanceREDIS_PORTThe port of your redis instanceREDIS_PASSWORDOptional password of your redis instanceREDIS_DB_INDEXThe Redis database indexREDIS_CACHE_SERVICE_HOSTThe domain / IP of your redis instance for cachingREDIS_CACHE_SERVICE_PORTThe port of your redis instance for cachingREDIS_CACHE_DB_INDEXThe Redis cache database indexREDIS_CACHE_TTLThe Redis cache ttlREDIS_CACHE_PASSWORDThe Redis cache passwordREDIS_CACHE_CONNECTION_TIMEOUTThe Redis cache connection timeoutREDIS_CACHE_KEEP_ALIVEThe Redis cache TCP keep alive on the socket timeoutREDIS_CACHE_FAMILYThe Redis cache IP stack versionREDIS_CACHE_KEY_PREFIXThe Redis cache prefix prepend to all keysREDIS_CACHE_SERVICE_TLSThe Redis cache TLS connection supportIN_MEMORY_CLUSTER_MODE_ENABLEDThe 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_HOSTElastiCache cluster hostELASTICACHE_CLUSTER_SERVICE_PORTElastiCache cluster portREDIS_CLUSTER_SERVICE_HOSTRedis cluster hostREDIS_CLUSTER_SERVICE_PORTSRedis cluster portsREDIS_CLUSTER_DB_INDEXRedis cluster database indexREDIS_CLUSTER_TTLRedis cluster ttlREDIS_CLUSTER_PASSWORDRedis cluster passwordREDIS_CLUSTER_CONNECTION_TIMEOUTRedis cluster connection timeoutREDIS_CLUSTER_KEEP_ALIVERedis cluster TCP keep alive on the socket timeoutREDIS_CLUSTER_FAMILYRedis cluster IP stack versionREDIS_CLUSTER_KEY_PREFIXRedis cluster prefix prepend to all keysJWT_SECRETThe secret keybase which is used to encrypt / verify the tokens issued for authenticationSENDGRID_API_KEYThe api key of the Sendgrid account used to send various emailsMONGO_URLThe URL of your MongoDB instanceMONGO_MAX_POOL_SIZEThe max pool size of the MongoDB connectionNOVU_API_KEYThe api key of web.novu.co used to send various emailsSENTRY_DSNThe DSN of sentry.io used to report errors happening in production
Worker
Worker
NODE_ENV(default: local)The environment of the app. Possible values are: dev, test, production, ci, localPORTThe port on which the Worker app should listen onSTORE_ENCRYPTION_KEYThe encryption key used to encrypt/decrypt provider credentialsMAX_NOVU_INTEGRATION_MAIL_REQUESTSThe number of free emails that can be sent with the Novu email providerNOVU_EMAIL_INTEGRATION_API_KEYThe Novu email provider Sentry API keySTORAGE_SERVICEThe storage service name: AWS, GCS, or AZURES3_LOCAL_STACKThe LocalStack service URLS3_BUCKET_NAMEThe name of the S3 BucketS3_REGIONThe AWS region of the S3 BucketGCS_BUCKET_NAMEThe name of the GCS BucketAZURE_ACCOUNT_NAMEThe name of the Azure accountAZURE_ACCOUNT_KEYThe Azure account keyAZURE_HOST_NAMEThe Azure host nameAZURE_CONTAINER_NAMEThe Azure container nameAWS_ACCESS_KEY_IDThe AWS access keyAWS_SECRET_ACCESS_KEYThe AWS secret access keyREDIS_HOSTThe domain / IP of your redis instanceREDIS_PORTThe port of your redis instanceREDIS_PASSWORDOptional password of your redis instanceREDIS_DB_INDEXThe Redis database indexREDIS_CACHE_SERVICE_HOSTThe domain / IP of your redis instance for cachingREDIS_CACHE_SERVICE_PORTThe port of your redis instance for cachingREDIS_DB_INDEXThe Redis cache database indexREDIS_CACHE_TTLThe Redis cache ttlREDIS_CACHE_PASSWORDThe Redis cache passwordREDIS_CACHE_CONNECTION_TIMEOUTThe Redis cache connection timeoutREDIS_CACHE_KEEP_ALIVEThe Redis cache TCP keep alive on the socket timeoutREDIS_CACHE_FAMILYThe Redis cache IP stack versionREDIS_CACHE_KEY_PREFIXThe Redis cache prefix prepend to all keysREDIS_CACHE_SERVICE_TLSThe Redis cache TLS connection supportIN_MEMORY_CLUSTER_MODE_ENABLEDThe 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_HOSTElastiCache cluster hostELASTICACHE_CLUSTER_SERVICE_PORTElastiCache cluster portREDIS_CLUSTER_SERVICE_HOSTRedis cluster hostREDIS_CLUSTER_SERVICE_PORTSRedis cluster portsREDIS_CLUSTER_DB_INDEXRedis cluster database indexREDIS_CLUSTER_TTLRedis cluster ttlREDIS_CLUSTER_PASSWORDRedis cluster passwordREDIS_CLUSTER_CONNECTION_TIMEOUTRedis cluster connection timeoutREDIS_CLUSTER_KEEP_ALIVERedis cluster TCP keep alive on the socket timeoutREDIS_CLUSTER_FAMILYRedis cluster IP stack versionREDIS_CLUSTER_KEY_PREFIXRedis cluster prefix prepend to all keysMONGO_URLThe URL of your MongoDB instanceMONGO_MAX_POOL_SIZEThe max pool size of the MongoDB connectionNEW_RELIC_APP_NAMEThe New Relic app nameNEW_RELIC_LICENSE_KEYThe New Relic license keySEGMENT_TOKENThe Segment Analytics token
Web Client
Web Client
REACT_APP_ENVIRONMENTThe environment of the app. Possible values are: dev, test, production, ci, localREACT_APP_API_URLThe base url on which your API backend would be accessibleREACT_APP_WS_URLThe base url on which your WebSocket service would be accessibleSKIP_PREFLIGHT_CHECK(default: true)Solves a problem with React App dependency tree.
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.Web Socket
Web Socket
NODE_ENV(default: local)The environment of the app. Possible values are: dev, test, production, ci, localSENTRY_DSNThe DSN of sentry.io used to report errors happening in productionREDIS_HOSTThe domain / IP of your redis instanceREDIS_PORTThe port of your redis instanceREDIS_DB_INDEXThe database index of your redis instanceREDIS_PASSWORDOptional password of your redis instanceJWT_SECRETThe secret keybase which is used to encrypt / verify the tokens issued for authenticationMONGO_URLThe URL of your MongoDB instanceMONGO_MAX_POOL_SIZEThe max pool size of the MongoDB connectionPORTThe 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: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:Different ports used by the services
- 3000 - API
- 3002 - WebSocket Service
- 3003 - Webhook Service
- 3004 - Worker Service
- 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 thenpm run test:providers command.
Local environment setup script (beta)
As an option in our script runnerJarvis 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 the 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 previous dependency installed, as it is prepared to execute the following tasks:
- Check the running OS in the local machine (currently only MacOSx and GNU Linuxsupported)
- 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](https://git-scm.com/)that is a required dependency for later) --- Will install Rosetta for Apple CPUs --- Will set up some opinionated OS settings - Will check if
[git](https://git-scm.com/)is installed and if not will abort the operation - Will make ZSH 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 a Node.js version manager
- Will install the required Node.js version to be able to run Novu
- Will install PNPM as a 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 maintainer used tool)
- Will create a local development domain
local.novu.coin your local machine - Will clone the Novu repository in your local machine (skippable step) to a selected folder
$HOME/Dev
This script has only been thoroughly tested in MacOSx. Little testing has been
run in GNU Linux.
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 because of conflicts between
versions of the different dependencies. Please report to us any problem found
and we will try to fix or assist though we do not have the resources to make
it idempotent in every potential system and potential combinations