Status

Overview

Key Sections

Instances Table

This table displays detailed insights about individual application instances. An application instance is an independent copy of the application running on a unique port.

Columns

• #number: Application Instance number.

• Port: The port number associated with the application instance process.

• Status: online or errored with the instance uptime. Status errored indicates that the instance is not running.

• Restarts: Number of times ClusterWare attempted to restart the application to recover from error.

• CPU: The current CPU utilization by this application instance

• Memory: The current memory utilization by this application instance

Main Script

Displays the full path to the main script as defined in package.json. The main script is an entry point to your application. It is executed when ClusterWare starts the application instance. Read more about package.json main.

Main Script Statuses

• Exists (green checkmark): The main script file exists on the server.

• Doesn't exist (red cross): The main script file doesn't exist on the server.

Node Modules

This section includes a button to install NodeJS dependencies. You can choose one of the following options to install your dependencies:

• NPM Install: Install dependencies, an already installed module with fuzzy versioning gets ignored by this command.

• NPM Update: Update dependencies, an already installed module with fuzzy versioning gets updated by this command.

• NPM CI: This command got introduced in npm 5.7.0 as additional way to achieve fast and reproducible builds in the CI context. See the documentation and npm blog for further information.

Node Modules Statuses

• Exists (green checkmark): Node modules folder exists on the server.

• Doesn't exist (red cross): Node modules folder doesn't exist on the server.

Read more

• key differences between NPM Install and NPM Update.

• key differences between NPM Install and NPM CI.

• NPM documentation about node_modules folder.

Branch Running

The Git branch and commit hash currently deployed, along with the latest commit message.

Sync Actions

• Status: Syncs information displayed in all sections of this tab.

Starting, Stopping, Restarting an Application

ClusterWare provides controls for managing your applications through the PM2 process manager. The actions of starting, stopping, and restarting an application are crucial for maintaining and updating your services.

• Starting an Application: Initiates the application process using PM2, bringing it online and making it accessible as per the defined configuration.

• Stopping an Application: Terminates the application process via PM2, freeing up system resources and ensuring that the application is no longer running.

• Restarting an Application: Performs both Stop and Start action through PM2, which is often necessary after updates or configuration changes to ensure the application runs with the latest code and settings.

These controls are accessible through the ClusterWare Console, providing an intuitive way to manage your application's lifecycle without needing to directly interact with the command line.

Application Stopped

When the application is stopped the Instances Table indicates there are No instances running and displays number of instances pending to start as per your configuration.

Application Started

When the application is started the Instances Table displays all application instances currently running.

If there's a discrepancy between number of instances currently running and the application configuration, ClusterWare Console will display information about the instances waiting for startup. Triggering an application restart will incorporate the application configuration changes, ensuring that the application runs with the updated settings.

Deploying Application

The deployment action in ClusterWare is a process designed to efficiently update your application with new code. This process involves a single action that seamlessly replaces the old code with the new one, ensuring minimal downtime and maximum consistency.

Deploying an application in ClusterWare triggers three sequential actions:

1. Git Pull

   • The deployment process begins with a Git Pull. This action retrieves the latest code from the current branch in your Git repository. It ensures that the deployment includes all recent changes and updates committed to the source control.

   • Purpose: To synchronize the local codebase with the latest version from the remote repository.

2. NPM CI (Continuous Integration Reproducible Install)

   • After the Git Pull, ClusterWare executes the npm ci command. This step installs the exact dependencies specified in the package-lock.json file, ensuring a clean and reproducible environment. Unlike npm install, npm ci guarantees that the dependencies are consistent with the lock file, which is critical for avoiding discrepancies and potential issues.

   • Purpose: To install project dependencies in a clean and reproducible manner, ensuring consistency across different environments.

3. PM2 Restart

   • The final step is to restart the application using PM2, a process manager for Node.js applications. This action stops the current instance of the application and starts it again with the newly pulled code and installed dependencies. PM2 ensures that the application restarts gracefully, minimizing downtime and maintaining service availability.

   • Purpose: To apply the new code changes and ensure the application runs with the latest updates and dependencies.

Outcome: The old code is replaced with the new code, dependencies are installed cleanly, and the application is restarted to reflect the latest changes.

Automatic Application Restart

In case the application instance unexpectedly exits with an error, the PM2 process manager is configured to automatically restart the application instance. The number of times the process manager attempted to restart the application is indicated in the Instances Table.

What's happening if the application instance doesn't recover to normal operation

1. After 15 failed restarts the process manager stops attempting new restarts and the instance status is set to errored.

2. Consequently the number of instances online drops which is reflected in the Instances Online metric.

3. If you set the Application settings to send a notification if any application instance is not online, then a new alert is generated in the Application Alerts tab.

4. If you configured the Cluster Notification Subscriptions, the alert is delivered to all subscribers.

5. To investigate the root cause of the error inspect the Application Logs.

Application Environment Variables

ClusterWare passes the following environment variables at the application startup.

• PORT: The port number on which the application instance is expected to listen for incoming requests. Use this value in the code to start your application server. Example.

• INSTANCE_ID: The application instance # displayed in the Instances Table.

• CLUSTERWARE_ENDPOINT_CERTIFICATE: ClusterWare provided certificate to encrypt the application traffic.

• CLUSTERWARE_ENDPOINT_CERTIFICATE_FINGERPRINT: The fingerprint of the ClusterWare provided certificate to encrypt the application traffic.

• CLUSTERWARE_ENDPOINT_CERTIFICATE_KEY: The private key of the ClusterWare provided certificate to encrypt the application traffic.