Running NodeBoot Application with PM2 Runtime

This documentation explains how to run a Node-Boot application using PM2 runtime, which provides enhanced deployment capabilities, monitoring, and management features.

📋 Overview

PM2 is a popular process manager for Node.js applications that enables you to keep your applications alive forever, reload them without downtime, and facilitate common system admin tasks. By integrating PM2 with Node-Boot, you can leverage these features to improve the reliability and scalability of your Node-Boot applications.

Wile Node-Boot provides the developer experience to build enterprise-grade applications, PM2 complements it by offering robust process management and monitoring capabilities.

About the sample application

• This repo contains a sample NodeBoot application using node:http server as the underlying backend runtime framework. You can choose other server frameworks supported by NodeBoot such as Fastify, Express or Koa by selecting the other sample project and following the same instructions described in this guide.

Server	Sample Repo	Description
Native HTTP	sample-native-http	NodeBoot application using Node.js native HTTP server
Fastify	sample-fastify	NodeBoot application using Fastify server
Express	sample-express	NodeBoot application using Express.js server

• For fast setup, the current sample project already includes the necessary configuration files to run with PM2. To start fresh, consider cloning one of the sample projects above and following the migration steps below. Otherwise, just jump to step 🏃 Running the Application.

• For details about the Node-Boot features baked in the sample application and project structure, refer to Sample Features

🚀 Prerequisites

Before running the application with PM2, ensure you have:

• Node.js (LTS version recommended)
• pnpm package manager installed globally (if not, run npm install -g pnpm)
• Node-Boot application set up with latest version of Node-boot (run pnpm nodeboot:update to update)
• PM2 CLI installed globally via npm install pm2 -g

Migrating a NodeBoot Application to PM2

The goal of this guide is to help you migrate an existing NodeBoot application to run with PM2 runtime. Follow these steps:

Select a Node-boot sample project depending on your preferred server framework

Please refer to the table in the About the sample application section above to choose a sample project that matches your preferred server framework.

The current sample project already includes the necessary configuration files to run with PM2. You can skip to the 🏃 Running the Application section if you want to run it directly.

Install dependencies and configure PM2

1. Install PNPM globally if not already installed

   npm install -g pnpm

2. Install project dependencies

   pnpm install

3. Install PM2 globally

   npm install pm2 -g

4. Create ecosystem.config.js file to setup PM2 runtime

   module.exports = {
        apps : [{
            name: "sample-nodeboot-http-app",
            script: 'dist/server.js',
             watch: '.'
        }]
    };

This configuration file tells PM2 how to run your NodeBoot application. For more configuration options, refer to the PM2 Documentation.

🏃 Running the Application

Start application wrapped with PM2

# Start with PM2 in development mode
pm2 start

This will:

1. Build the TypeScript application
2. Run Node-Boot AOT compilation
3. Start the PM2 runtime
4. Launch the NodeBoot application

pm2 start
1|sample-n | 2025-10-23T16:12:41.249Z native-http-service info Binding persistence repositories platform=node-boot
1|sample-n | 2025-10-23T16:12:41.249Z native-http-service info Registering a 'sql' repository 'UserRepository' for entity 'User' platform=node-boot
1|sample-n | 2025-10-23T16:12:41.249Z native-http-service info Registering a 'sql' repository 'PagingUserRepository' for entity 'User' platform=node-boot
1|sample-n | 2025-10-23T16:12:41.249Z native-http-service info Running migrations platform=node-boot
1|sample-n | 2025-10-23T16:12:41.252Z native-http-service info Binding 3 persistence.started Node-Boot Application Features platform=node-boot
1|sample-n | 2025-10-23T16:12:41.253Z native-http-service info ⏰ Registering scheduler SchedulersComponent:::fastTask() with cron '*/1 * * * *' platform=node-boot
1|sample-n | 2025-10-23T16:12:41.253Z native-http-service info ⏰ Registering scheduler SchedulersComponent:::cleanUp() with cron '*/5 * * * *' platform=node-boot
1|sample-n | 2025-10-23T16:12:41.254Z native-http-service info ⏰ Registering scheduler SchedulersComponent:::morningRoutine() with cron '0 9 * * *' platform=node-boot
1|sample-n | 2025-10-23T16:12:41.267Z native-http-service info BEFORE TRANSACTION STARTED platform=node-boot
1|sample-n | 2025-10-23T16:12:41.267Z native-http-service info AFTER TRANSACTION STARTED platform=node-boot
1|sample-n | 2025-10-23T16:12:41.271Z native-http-service info BEFORE TRANSACTION COMMITTED platform=node-boot
1|sample-n | 2025-10-23T16:12:41.275Z native-http-service info AFTER TRANSACTION COMMITTED platform=node-boot
1|sample-n | 2025-10-23T16:12:41.275Z native-http-service info 2 migration was successfully executed platform=node-boot
1|sample-n | 2025-10-23T16:12:41.276Z native-http-service info Database validation: Running consistency validation for 3-tables/1-entities. platform=node-boot
1|sample-n | 2025-10-23T16:12:41.277Z native-http-service info Basic database consistency validation passed platform=node-boot

Check for running processes

pm2 ls

This command lists all PM2 managed processes, including your Node-Boot application.

[PM2] Applying action deleteProcessId on app [server](ids: [ 0 ])
[PM2] [server](0) ✓
⇆ PM2+ activated | Instance Name: lis-m0119-548c | Dash: https://app.pm2.io/#/r/nnktpkqpd4fc8s6
┌────┬─────────────────────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┬──────────┬──────────┬──────────┬──────────┐
│ id │ name                        │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │ cpu      │ mem      │ user     │ watching │
├────┼─────────────────────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┼──────────┼──────────┼──────────┼──────────┤
│ 1  │ sample-nodeboot-http-app    │ default     │ 1.3.4   │ fork    │ 74049    │ 93m    │ 1956 │ online    │ 0%       │ 78.0mb   │ santoman │ enabled  │
└────┴─────────────────────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┴──────────┴──────────┴──────────┴──────────┘

Troubleshooting (Common issues)

1. Error during Persistence DataSource initialization: Could not locate the bindings file for better-sqlite3

   • Make sure you are using a NodeJs version compatible with the better-sqlite3 package (ex: nvm use 22.20).
   • Re-install dependencies by running pnpm install
   • Rebuild better-sqlite3 bindings by running pnpm rebuild:sqlite

2. Port conflicts (already in use)

   • Make sure the port defined in the application configuration file app-config.yaml (app.port) is free to use.

📊 Monitoring and Management

Node-Boot Application Endpoints

Once running, the application provides these endpoints:

• API Base: http://localhost:30000/api
• Swagger UI Documentation: http://localhost:30000/api-docs
• OpenAPI v3 API spec: http://localhost:30000/api-docs/swagger.json
• Health Check: http://localhost:30000/actuator/health
• Application Info: http://localhost:30000/actuator/info
• Metrics: http://localhost:30000/actuator/metrics
• Prometheus Metrics: http://localhost:30000/actuator/prometheus

PM2 Management Commands

Use the following PM2 commands to manage your Node-Boot application:

• List Processes:

  pm2 ls

• View Logs:

  pm2 logs

• Stop Application:

  pm2 stop sample-nodeboot-http-app

• Restart Application:

  pm2 restart sample-nodeboot-http-app

• Delete Application:

  pm2 delete sample-nodeboot-http-app

For more PM2 commands and options, refer to the PM2 Documentation.

PM2 Monitoring

PM2 provides built-in features to manage and monitor your Node-Boot application processes.

CLI Monitoring

CLI monitoring by using the pm2 monit command:

pm2 monit

This opens an interactive console displaying CPU, memory usage, and other metrics for each managed process.

Web-based Monitoring with PM2 Plus

For advanced monitoring, consider using PM2.io, a web-based dashboard for PM2. Sign up for an account and connect your application by following the instructions on their website.

📚 Additional Resources

• NodeBoot Framework: https://nodeboot.io
• NodeBoot Documentation: https://nodeboot.gitbook.io
• PM2 Docs: https://pm2.keymetrics.io/
• Application Source: Check the src/ directory for implementation details