HotHost Monitoring Tool

Plugins in HotHost are standalone .js files using ESM format (import/export). CommonJS (require) is not supported.

Requirements:

• Must use ESM syntax.
• Must follow a specific defined structure (see server/src/plugins/slack.js for a reference implementation).
• Plugins should be placed in the server/src/plugins directory.
• If your plugin requires external Node modules, you must bundle them using a tool like Webpack to ensure they are compatible with the ESM output. See server/src/plugins/gmail.src/gmail.src.js for an example of bundling node-mailer into a plugin.

To run HotHost locally for development, you need to start both the backend server and the frontend separately.

Default local credentials:

• Username: admin
• Password: 123456

Steps:

1. Start the backend server:

   cd server
   npm ci
   npm start

2. Start the frontend:

   cd frontend 
   npm ci
   npm run dev

If you are not using Docker Compose, you can run the HotHost Web Server using a single docker run command. Ensure you create a local directory for persistent data storage before running the command.

mkdir -p /www/hothostdata
docker run -d --name=hothost-web \
  -v /www/hothostdata:/var/lib/hothost/data/  \
  --env HOTHOST_WEB_ADMIN_USERNAME=admin  \
  --env HOTHOST_WEB_ADMIN_PASSWORD=!!!CHANGE_ME!!!  \
  --env HOTHOST_WEB_PUBLIC_VIEW_ENABLED=false  \
  --restart=always  \
  --env HOTHOST_WEB_PORT=8007  \
  -p 8007:8007  \
  devforth/hothost-web

To run the HotHost Web Server as part of an existing Docker Compose stack, add the hothost-web service to your docker-compose.yml. You must configure administrative credentials and the listening port via environment variables. Note that you are responsible for setting up HTTPS (e.g., via Nginx, Traefik, or Cloudflare) to proxy traffic to the container's port.

version: '3.5'

services:
  hothost-web:
    image: devforth/hothost-web
    restart: always
    environment:
      - HOTHOST_WEB_ADMIN_USERNAME=admin
      - HOTHOST_WEB_ADMIN_PASSWORD=!!!CHANGE_ME!!!
      - HOTHOST_WEB_PORT=8007
      - HOTHOST_WEB_PUBLIC_VIEW_ENABLED=false
    ports:
      - 8007:8007
    volumes:
      - v-hothost-data:/var/lib/hothost/data/
volumes:
  v-hothost-data:

To update the HotHost Web Server to the latest version, pull the latest image and recreate your container.

docker pull devforth/hothost-web:latest
# Then recreate the container

HotHost supports both internal and third-party plugins.

Plugin Locations

• Internal Plugins: Located in the src/plugins directory of the server.
• Third-party Plugins: Located in the directory defined by the DATA_PATH environment variable, specifically under the plugins subdirectory (e.g., $DATA_PATH/plugins).

Plugin Loading Behavior

When the PluginManager loads plugins, it automatically marks any plugin found in the third-party directory with a thirdParty: true property on its default export.

Plugin Lifecycle

Plugins can implement an optional onPluginEnabled() method, which is called during the initialization phase if the plugin is globally enabled or used within a specific host group.

The Hothost server uses the WEB_PORT environment variable to determine which port to listen on. If WEB_PORT is not provided, the server defaults to port 8007.

# Example: Running Hothost on port 9000
WEB_PORT=9000 node server/src/index.js

Monitoring behavior for RAM, Disk, and Host availability is controlled via getEffectiveSettingsForHost(host). Settings are resolved using a hierarchy:

1. Host Overrides: host.settingsOverrides (highest priority).
2. Global Settings: database.data.settings.
3. Defaults: Hardcoded fallback values.

Available configuration keys:

• RAM_THRESHOLD: Percentage threshold for RAM usage (default: 90).
• RAM_STABILIZATION_LEVEL: Number of readings to stabilize RAM alerts (default: 3).
• DISK_THRESHOLD: Percentage threshold for Disk usage (default: 90).
• DISK_STABILIZATION_LEVEL: Number of readings to stabilize Disk alerts (default: 1).
• HOST_IS_DOWN_CONFIRMATIONS: Number of consecutive failures required to trigger a host_is_offline event (default: 1).
• HOURS_FOR_NEXT_ALERT: Delay in hours before repeating a disk alert (default: 12).

The following environment variables are used to configure the hothost-web container:

The Hothost server exposes two primary API routing surfaces. All requests are protected by authMiddleware and require valid credentials.

• Legacy API: Accessible via the /api/ prefix.
• Next API (v2): Accessible via both /api/v2/ and /v2/ prefixes. This represents the newer version of the API surface.

The parseNestedForm(fields) utility converts flat object keys using bracket notation (e.g., user[name][first]) into a deeply nested JSON object.

Example Transformation: Input:

{
  "user[name][first]": "John",
  "user[name][last]": "Doe",
  "role": "admin"
}

Output:

{
  "user": {
    "name": {
      "first": "John",
      "last": "Doe"
    }
  },
  "role": "admin"
}