Running NodeBoot Application with Platformatic Watt Runtime

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

📋 Overview

This NodeBoot application is configured with Platformatic Watt runtime integration through the watt.json configuration file. The runtime provides:

• Enhanced Development Experience: Hot reload and development tools
• Production Management: Process management and monitoring
• Environment Configuration: Flexible environment variable management
• Management API: Runtime monitoring and control endpoints

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 Platformatic Watt. 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 Platformatic Watt, 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)
• Platformatic Watt CLI installed globally or use via npx

Migrating a NodeBoot Application to Platformatic Watt

The goal of this guide is to help you migrate an existing NodeBoot application to run with Platformatic Watt 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 Platformatic Watt. You can skip to the 🏃 Running the Application section if you want to run it directly.

Install dependencies and run wattpm create

1. Install PNPM globally if not already installed

   npm install -g pnpm

2. Install project dependencies

   pnpm install

3. Run Platformatic Watt CLI to setup necessary configuration

   npx wattpm create

 npx wattpm create

Need to install the following packages:
wattpm@2.75.2
Ok to proceed? (y) y

Hello manusant, welcome to Watt 2.75.2!
? This folder seems to already contain a Node.js application. Do you want to wrap into Watt? yes
? What port do you want to use? 30000
[11:37:38.787] INFO (92184): /Users/santoman/OpenSource/NodeBoot/samples/sample-nodeboot-platformatic/.env written!
[11:37:38.793] INFO (92184): /Users/santoman/OpenSource/NodeBoot/samples/sample-nodeboot-platformatic/.env.sample written!
[11:37:38.795] INFO (92184): /Users/santoman/OpenSource/NodeBoot/samples/sample-nodeboot-platformatic/package.json written!
[11:37:38.800] INFO (92184): /Users/santoman/OpenSource/NodeBoot/samples/sample-nodeboot-platformatic/watt.json written!
[11:37:38.800] INFO (92184): Installing dependencies for the application using pnpm ...
...

The Watt create command generates the watt.json configuration file, sample .env files for environment variables and updates package.json with necessary dependencies. Proceed with the required adaptations below to properly integrate it with the NodeBoot App.

Adapt watt.json configuration

Open the generated watt.json file and ensure it matches the following structure, adapting commands as necessary for your application:

{
  "$schema": "https://schemas.platformatic.dev/@platformatic/node/2.75.2.json",
  "application": {
    "commands": {
      "development": "pnpm start",
      "build": "pnpm build",
      "production": "pnpm start:prod"
    }
  },
  "runtime": {
    "logger": {
      "level": "{PLT_SERVER_LOGGER_LEVEL}"
    },
    "server": {
      "hostname": "{PLT_SERVER_HOSTNAME}",
      "port": "{PORT}"
    },
    "managementApi": "{PLT_MANAGEMENT_API}"
  }
}

The application.commands section should reflect the scripts defined in your package.json for starting and building the NodeBoot application.

Set-up Platformatic Environment Variables

The application supports the following environment variables for Platformatic Watt runtime:

Variable	Description	Default
PORT	Application server port	3000
PLT_SERVER_HOSTNAME	Server hostname	localhost
PLT_SERVER_LOGGER_LEVEL	Logging level (trace, debug, info, warn, error, fatal)	info
PLT_MANAGEMENT_API	Enable management API	true
NODE_ENV	Node environment	development

Create a .env file in the project root to customize these values:

# .env
PORT=3000
PLT_SERVER_HOSTNAME=localhost
PLT_SERVER_LOGGER_LEVEL=debug
PLT_MANAGEMENT_API=true
NODE_ENV=development

Update Node-Boot app-config.yaml to inject port from Platformatic environment variable:

This will ensure platformatic and NodeBoot use the same port configuration.

🏃 Running the Application

Development Mode wrapped with Platformatic Watt

For development with hot reload and enhanced debugging:

# Start with Platformatic Watt in development mode
watt start

This will:

1. Build the TypeScript application
2. Run Node-Boot AOT compilation
3. Start the Platformatic Watt runtime
4. Launch the NodeBoot application
5. Enable hot reload for development

t watt start
[13:07:38.761] INFO (9416): Starting the service "native-http-sample"...                                                                                                                                                                                                                                                                                            
[13:07:43.043] INFO (native-http-sample/9416) <STDOUT>: 🎯 NodeBoot shutdown hooks registered for process signals
[13:07:43.197] INFO (native-http-sample/9416) <STDOUT>: ============================= Node-Boot Beans Resolution =============================
[13:07:43.197] INFO (native-http-sample/9416) <STDOUT>: 🔍 Checking for pre-built beans file: /Users/santoman/OpenSource/NodeBoot/samples/sample-nodeboot-platformatic/dist/node-boot-beans.json
[13:07:43.198] INFO (native-http-sample/9416) <STDOUT>: 🚀 Beans file found. Importing beans...
[13:07:43.218] INFO (native-http-sample/9416) <STDOUT>: 19 application beans successfully imported
[13:07:43.238] INFO (native-http-sample/9416) <STDOUT>: Loaded config from app-config.yaml, app-config.local.yaml                                                                                                                                                                                                                                                                                   
[13:07:43.277] INFO (native-http-sample/9416) <STDOUT>:
    stdout: {
      "level": "info",
      "message": "Node-Boot application initialized successfully",
      "platform": "node-boot",
      "service": "native-http-service"
    }
[13:07:43.303] INFO (native-http-sample/9416) <STDOUT>:
    stdout: {
      "level": "info",
      "message": "2 migration was successfully executed",
      "platform": "node-boot",
      "service": "native-http-service"
    }
[13:07:43.304] INFO (native-http-sample/9416) <STDOUT>:
    stdout: {
      "level": "info",
      "message": "Database validation: Running consistency validation for 3-tables/1-entities.",
      "platform": "node-boot",
      "service": "native-http-service"
    }
[13:07:43.304] INFO (native-http-sample/9416) <STDOUT>:
    stdout: {
      "level": "info",
      "message": "Basic database consistency validation passed",
      "platform": "node-boot",
      "service": "native-http-service"
    }
[13:07:43.315] INFO (9416): Started the service "native-http-sample"...

Interact with running process

Now you can interact with the running application using the application endpoints (see 📊 Monitoring and Management section below) or use Platformatic Watt CLI commands:

# List running Watt processes
watt ps  
┌──────┬──────────────────────────────┬─────────┬────────────┬────────────────────────┬───────────────────────────────────────────────────┐
│ PID  │ Name                         │ Version │ Uptime     │ URL                    │ Directory                                         │
├──────┼──────────────────────────────┼─────────┼────────────┼────────────────────────┼───────────────────────────────────────────────────┤
│ 9416 │ @nodeboot/native-http-sample │ 2.75.2  │ 1h 38m 30s │ http://127.0.0.1:30000 │ .../NodeBoot/samples/sample-nodeboot-platformatic │
└──────┴──────────────────────────────┴─────────┴────────────┴────────────────────────┴───────────────────────────────────────────────────┘

# List running Watt services
watt services  
┌────────────────────┬─────────┬────────┬────────────┐
│ Name               │ Workers │ Type   │ Entrypoint │
├────────────────────┼─────────┼────────┼────────────┤
│ native-http-sample │ 1       │ nodejs │ Yes        │
└────────────────────┴─────────┴────────┴────────────┘

# Stop a Watt service
watt stop <service-id>

[14:48:59.940] DONE (24698): Runtime @nodeboot/native-http-sample have been stopped.

# View logs of a Watt service
watt logs <service-id>

{"level":30,"time":1761227641302,"pid":25938,"hostname":"lis-m0119","name":"native-http-sample","caller":"STDOUT","stdout":{"level":"info","message":"Node-Boot application initialized successfully","platform":"node-boot","service":"native-http-service"}}
{"level":30,"time":1761227641307,"pid":25938,"hostname":"lis-m0119","name":"native-http-sample","caller":"STDOUT","stdout":{"level":"info","message":"======= ENV: development =======","platform":"node-boot","service":"native-http-service"}}
{"level":30,"time":1761227641307,"pid":25938,"hostname":"lis-m0119","name":"native-http-sample","caller":"STDOUT","stdout":{"level":"info","message":"🚀 App listening on [object Object]","platform":"node-boot","service":"native-http-service"}}
...

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 .env file is not being used by another application.
   • Change the port in the .env file to an available port.
   • Make sure the ${PORT} variable is properly injected in the app-config.yaml file as shown above.

Production Mode

For production deployment:

# Build the application
pnpm build

# Start with Platformatic Watt in production mode
NODE_ENV=production watt start:prod

📊 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

Platformatic Management API

When PLT_MANAGEMENT_API=true, additional management endpoints are available:

• Runtime Status: Check application and runtime health
• Process Information: View running processes and resource usage
• Configuration: View current runtime configuration
• Logs: Access application and runtime logs

Access the management API at the configured management port (typically different from the main application port).

🔍 Debugging

Enable Debug Logging

Set detailed logging for troubleshooting:

PLT_SERVER_LOGGER_LEVEL=debug watt start

📚 Additional Resources

• NodeBoot Framework: https://nodeboot.io
• NodeBoot Documentation: https://nodeboot.gitbook.io
• Platformatic Watt Docs: https://docs.platformatic.dev/
• Fastify Documentation: https://www.fastify.io/
• Application Source: Check the src/ directory for implementation details