Node.js Processes

Git Web Manager

Run and supervise Node.js servers per project - no PM2 required.

Runtime Diagnostics Task Queue

Overview

The Node.js Process Manager lets you run a persistent Node.js server for any project directly from the Git Web Manager UI. Processes are supervised automatically so they restart on crash without any external process manager like PM2.

  • Per-project - each project gets its own process slot, start command, and port.
  • Supervised - a lightweight shell wrapper restarts your process if it exits unexpectedly.
  • Integrated - logs are managed by the built-in log cleanup system; status appears on the dashboard Node.js tab.

Community installations support up to 3 active Node.js processes. Enterprise removes the limit.

Installing Node.js

Before starting any process, a Node.js runtime must be available. Go to System → Plugins to install or manage the Node.js runtime. See the Plugins page for full details.

  • Detected - GWM found an existing Node.js binary on the server PATH.
  • Not found - use the Install Node.js button to download and install Node.js LTS automatically into storage/node-runtime/.
  • Reinstall - replaces the current runtime with the latest LTS release.
  • Remove - uninstalls the GWM-managed runtime. Does not affect system-level Node.js installations.

The runtime is downloaded directly from the official Node.js release archive. No package manager is required on the server.

The Settings page shows the detected version, binary path, and install source (system vs. GWM-managed).

Starting a Process

Open a project and select the Node.js tab. Configure the process settings, then click Start.

  • Start Command - the command run inside the project directory, e.g. node server.js or npm start.
  • Port - optional. Used for reference only; GWM does not bind or proxy the port.
  • Auto-Restart - when enabled, the supervisor script automatically restarts the process on exit. Disable this for one-shot scripts.

Once started, the tab shows the live status badge and PID of the running process.

If the free-tier limit of 3 active processes has been reached, the Start button is replaced with an upgrade prompt. Stop a running process first to free a slot.

Process Lifecycle

Use the control buttons on the Node.js tab to manage the process state:

  • Start - launch the process under the supervisor. Available when the process is stopped or crashed.
  • Stop - send a termination signal to the process group. The supervisor exits cleanly.
  • Restart - stop and immediately start again. Useful after a code change without navigating away.

Status badges reflect the current state:

  • Running - process is active and the PID is alive.
  • Starting - process was launched and GWM is confirming it is alive.
  • Stopped - process is not running and auto-restart is off, or it was manually stopped.
  • Crashed - process exited unexpectedly and auto-restart is disabled, or it has crashed repeatedly.

Auto-Restart Supervision

When Auto-Restart is enabled, GWM wraps the start command in a supervisor loop. If the process exits for any reason - crash, OOM, uncaught exception - the supervisor restarts it automatically.

  • The crash count increments each time the process exits unexpectedly. This is visible on the dashboard Node.js tab.
  • A high crash count with auto-restart enabled usually indicates a code error. Check the process log for the exit reason.
  • To stop a supervised process cleanly, always use the Stop button - killing the PID directly may leave the supervisor running.

The supervisor runs as a background shell script (storage/node-runtime/supervisors/{project-id}.sh). The wrapper PID is stored separately from the Node.js child PID.

Process Logs

Each process writes stdout and stderr to a dedicated log file:

storage/logs/node-processes/{project-id}/out.log
  • Use Show Log on the Node.js tab to view the last lines of output inline.
  • Use Clear Log to truncate the file without stopping the process.

Node.js logs are included in the system log cleanup job. Go to System → Settings → Log Cleanup to configure the retention window. Old log content is truncated, not deleted, so the file path stays stable.

Log files are not rotated automatically mid-session. For high-volume output, lower the cleanup interval or use a stream logger inside your application.

Dashboard Overview

The Node.js tab on the main dashboard shows all projects that have a Node.js process configured. Each card displays:

  • Project name, linking directly to the project's Node.js tab.
  • Current status badge (Running / Starting / Stopped / Crashed).
  • Crash count since last start.

Only projects with a saved start command appear on the dashboard tab. Projects that have never had a Node.js process configured are not listed.

Health Monitoring

GWM runs a background health check command, php artisan node:health-check, every minute via the Laravel scheduler. This command:

  • Checks the PID of every process marked as Running or Starting.
  • Updates the status to Crashed if the PID is no longer alive.
  • Triggers the supervisor restart log for crash counting.

If the scheduler is not running, status badges may not update immediately after a crash. Use the Restart button on the project tab to bring a crashed process back online manually.

The health check runs with a withoutOverlapping(5) lock, so it will not stack if a previous check runs long. See the Scheduler page for lock management.

Process Limits

The number of simultaneously active Node.js processes is tied to your edition:

  • Community - up to 3 active processes at a time (Running or Starting).
  • Enterprise - unlimited active processes.

Stopped and crashed processes do not count against the limit. To free a slot on Community, stop a running process before starting a new one.

The limit is enforced at start time. If you downgrade from Enterprise to Community while more than 3 processes are running, existing processes continue until they are stopped or crash.