@jxa13/pm2ui 1.17.0

package/user_manual.md

@@ -0,0 +1,458 @@
+# Node WebUI User Manual
+
+Node WebUI is a local web dashboard for monitoring and managing Node.js services that are already managed by PM2. It is intended for local operations work: checking service health, controlling processes, viewing logs, creating PM2 apps, and saving PM2 state without switching back to the terminal.
+
+## Screenshots
+
+### React Operations Dashboard
+
+![React dashboard](docs/images/react-dashboard.png)
+
+### Logs Workspace
+
+![React logs workspace](docs/images/react-logs.png)
+
+### Mobile Layout
+
+![Mobile layout](docs/images/react-mobile.png)
+
+## Requirements
+
+- macOS
+- Node.js 18 or newer
+- npm
+- PM2 installed and available on your shell path
+- One or more PM2-managed processes, unless you only want to create a process from the UI
+
+Install PM2 globally if it is not installed:
+
+```bash
+npm install -g pm2
+```
+
+Check PM2:
+
+```bash
+pm2 -v
+pm2 list
+```
+
+## Installation
+
+Clone the repository:
+
+```bash
+git clone <repo-url>
+cd Node-WebUI
+```
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start Node WebUI:
+
+```bash
+npm start
+```
+
+The server binds to localhost by default:
+
+```text
+http://127.0.0.1:3000
+```
+
+## Opening The App
+
+Node WebUI serves the React operations console as the default UI:
+
+```text
+http://127.0.0.1:3000
+```
+
+`npm start` builds the React frontend before starting Express. The compatibility path `http://127.0.0.1:3000/react` also loads the same React UI.
+
+## Optional Environment Variables
+
+### Port
+
+Use a different local port:
+
+```bash
+PORT=3100 npm start
+```
+
+Then open:
+
+```text
+http://127.0.0.1:3100
+```
+
+### Server-Enforced Protected Processes
+
+The settings page can locally protect process names in the UI, but server-side protection is configured with an environment variable. Use this if you want the API itself to reject stop, restart, and delete actions for specific process names:
+
+```bash
+PROTECTED_PM2_PROCESSES=node-webui,server npm start
+```
+
+Names are matched case-insensitively. The default server-side protected process name is:
+
+```text
+node-webui
+```
+
+### PM2 Home
+
+If your PM2 data is stored outside the default `~/.pm2`, set `PM2_HOME`:
+
+```bash
+PM2_HOME=/path/to/.pm2 npm start
+```
+
+## Creating Or Preparing PM2 Apps
+
+You can use existing PM2 processes:
+
+```bash
+pm2 start app.js --name my-app
+pm2 list
+```
+
+Save PM2 state:
+
+```bash
+pm2 save
+```
+
+Configure PM2 startup if desired:
+
+```bash
+pm2 startup
+```
+
+You can also create a PM2 app from Node WebUI by using the `Create PM2 App` button.
+
+## Dashboard Overview
+
+The React dashboard has three main regions:
+
+- Left sidebar: navigation, connection status, host CPU/RAM, PM2 runtime summary, quick theme controls.
+- Main dashboard: metrics, charts, filters, process table, bulk actions.
+- Right inspector: selected process details, actions, config, files, and optional logs.
+
+Use the top toolbar to:
+
+- Refresh dashboard data immediately.
+- Pause or resume live updates.
+- Save PM2 state.
+- Create a new PM2 app.
+
+## Summary Metrics
+
+The summary row shows:
+
+- Total Services
+- Online
+- Stopped
+- Errored
+- Restart Count
+- PM2 CPU
+- PM2 RAM
+
+PM2 CPU and PM2 RAM are based on PM2-managed processes, not total host usage. Host CPU/RAM appears in the sidebar as secondary context.
+
+## Metric History
+
+The metric history section tracks local browser history for:
+
+- PM2 CPU
+- PM2 RAM
+- Restarts
+- Status counts
+
+Use the `Window` selector to switch between 15, 30, and 60 minute views. This history is stored locally in your browser.
+
+## Process Table
+
+The process table is the main workflow area. It supports:
+
+- Search by process name.
+- Filter by status.
+- Sort by status, name, CPU, RAM, restarts, uptime, and started time.
+- Show or hide columns from the `Columns` menu.
+- Switch between compact and comfortable density.
+- Select rows for bulk actions.
+- Highlight the selected process.
+
+Each process row shows:
+
+- Status
+- PM2 ID
+- Name
+- CPU
+- RAM
+- Restart count
+- Uptime
+- Started time
+- Actions
+
+## Process Actions
+
+Per-process action buttons:
+
+- Start: start the selected PM2 process.
+- Stop: stop the selected PM2 process.
+- Restart: restart the selected PM2 process.
+- Logs: open logs for that process.
+- Open folder: open the process folder in Finder.
+- Delete: remove the process from PM2.
+
+Some actions require confirmation before they run.
+
+## Bulk Actions
+
+Select one or more rows using the table checkboxes. The bulk action bar supports:
+
+- Start selected
+- Stop selected
+- Restart selected
+- Clear selection
+
+Protected processes are excluded from bulk stop and restart actions.
+
+## Process Inspector
+
+The inspector on the right shows information for the selected process.
+
+Tabs:
+
+- Overview: runtime, CPU, RAM, uptime, started time, restarts, PID, PM2 ID.
+- Config: interpreter, exec mode, namespace, version, environment, instances, watch, autorestart, args, Node args, max memory restart.
+- Files: script path, working directory, output log, error log, PID file, PM2 home.
+- Logs: compact log viewer for the selected process.
+
+Use the collapse button in the inspector header to reduce the inspector to a narrow rail. The choice is remembered locally.
+
+## Logs
+
+Use the sidebar `Logs` item to open the central logs workspace. This shows logs in the main section only, avoiding a duplicate log viewer in the inspector.
+
+The logs workspace supports:
+
+- Selecting a process.
+- Viewing stdout and stderr lines.
+- Searching visible logs.
+- Choosing log line count.
+- Refreshing logs.
+- Copying logs.
+- Downloading logs.
+- Clearing logs.
+- Auto-refreshing logs.
+- Wrapping or truncating long lines.
+
+The row-level log action opens logs for that specific process.
+
+## Create PM2 App
+
+Click `Create PM2 App` to register a new PM2 process.
+
+Required fields:
+
+- Script path
+- Process name
+- Working directory
+
+Optional fields:
+
+- Arguments
+- Interpreter
+- Node args
+- `NODE_ENV`
+- Instances
+- Watch mode
+- Max memory restart
+- Output log path
+- Error log path
+
+After a successful create, Node WebUI saves PM2 state.
+
+## Settings
+
+The settings page includes:
+
+- Theme family
+- Theme mode: System, Light, Dark
+- Protected process names
+- Local storage reset
+
+### Themes
+
+Theme preferences are saved locally in the browser. Quick theme controls are also available in the sidebar.
+
+### Protected Process Names
+
+Protected process names prevent accidental UI actions against important services. Enter one name per line, or separate names with commas:
+
+```text
+node-webui
+server
+api-worker
+```
+
+Click `Save Protected Names`.
+
+Important: this UI setting is local to your browser. For server-side API enforcement, also start the app with `PROTECTED_PM2_PROCESSES`, for example:
+
+```bash
+PROTECTED_PM2_PROCESSES=node-webui,server npm start
+```
+
+### Reset Local Storage
+
+Click `Reset Local Storage` to clear saved browser preferences, including:
+
+- Theme settings
+- Filters
+- Table columns
+- Metric history
+- Selected process
+- Sidebar and inspector collapse state
+- Protected process names
+- Log settings
+
+The app asks for confirmation before clearing local storage.
+
+## Keyboard Shortcuts
+
+- `/`: focus process search.
+- `r`: refresh the dashboard.
+- `l`: open logs for the selected process.
+- Arrow Up / Arrow Down: move process selection.
+- `Esc`: clear selected table rows.
+
+Shortcuts are ignored while typing in an input, textarea, or select.
+
+## Tooltips
+
+Buttons include brief tooltips. Hover over a button to see what it does. When the left sidebar is collapsed, navigation buttons show a compact popover tooltip.
+
+## Running In Development
+
+Run the Express server:
+
+```bash
+npm run dev
+```
+
+Run the React Vite dev server:
+
+```bash
+npm run react:dev
+```
+
+The Vite dev server is useful while editing the React frontend. The production Express root route uses the built files from:
+
+```text
+frontend/dist
+```
+
+Rebuild after React changes:
+
+```bash
+npm run react:build
+```
+
+## Validation
+
+Run the React build:
+
+```bash
+npm run react:build
+```
+
+Run smoke checks:
+
+```bash
+npm run react:smoke
+```
+
+## Troubleshooting
+
+### PM2 processes do not appear
+
+Check PM2 from the same shell/user that starts Node WebUI:
+
+```bash
+pm2 list
+```
+
+If needed, set `PM2_HOME` before starting Node WebUI.
+
+### React UI is not available at `/`
+
+Build the React frontend:
+
+```bash
+npm run react:build
+```
+
+Restart Node WebUI:
+
+```bash
+npm start
+```
+
+### Process actions fail
+
+Check that PM2 is installed and available:
+
+```bash
+pm2 -v
+```
+
+Check that the process exists:
+
+```bash
+pm2 list
+```
+
+If the process is protected, remove it from the protected list or adjust `PROTECTED_PM2_PROCESSES`.
+
+### Open folder does not work
+
+Open folder is designed for macOS Finder. It requires the process to have a valid script path or working directory.
+
+### Logs show repeated PM2 or socket errors
+
+Check PM2 log output directly:
+
+```bash
+pm2 logs <process-name>
+```
+
+If the Node WebUI process itself is logging errors, restart it:
+
+```bash
+pm2 restart node-webui
+```
+
+### Port is already in use
+
+Start Node WebUI on another port:
+
+```bash
+PORT=3100 npm start
+```
+
+## Security Notes
+
+Node WebUI is designed for local use. The server binds to:
+
+```text
+127.0.0.1
+```
+
+Do not expose it directly to the public internet. If you need remote access, put it behind authentication and a reverse proxy.