{"id":17316,"library":"on-http","title":"RackHD HTTP Server (on-http)","description":"on-http serves as the primary HTTP server component for the RackHD infrastructure management system, providing the web user interface and RESTful API endpoints essential for managing bare-metal hardware. Currently at its stable version 2.60.7, the project exhibits a consistent release cadence with frequent patch updates, indicating active development and maintenance. It is deployed as a standalone application, mandating the presence and correct configuration of external MongoDB and RabbitMQ instances for its operation. Its key differentiators lie in its deep integration with RackHD's capabilities for automated hardware provisioning, discovery, and orchestration, offering a structured API that defaults to version 2.0, with version 1.1 explicitly deprecated. The package also includes built-in tools for generating API documentation, task documentation, and client libraries for various programming languages, facilitating ecosystem integration.","status":"active","version":"2.60.7","language":"javascript","source_language":"en","source_url":"https://github.com/RackHD/on-http","tags":["javascript"],"install":[{"cmd":"npm install on-http","lang":"bash","label":"npm"},{"cmd":"yarn add on-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add on-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the primary data store for RackHD operations.","package":"mongodb","optional":false},{"reason":"Required for inter-service communication and task queuing within RackHD.","package":"rabbitmq","optional":false}],"imports":[{"note":"Imports the Express application instance. This package primarily uses CommonJS modules. Direct import from 'on-http' will not expose named symbols; subpath imports are needed for internal modules.","wrong":"import { app } from 'on-http/lib/app';\nconst app = require('on-http');","symbol":"app","correct":"const { app } = require('on-http/lib/app');"},{"note":"Imports the Node.js HTTP server instance. This package primarily uses CommonJS modules. Direct import from 'on-http' will not expose named symbols; subpath imports are needed for internal modules.","wrong":"import { server } from 'on-http/lib/app';\nconst { Server } = require('on-http');","symbol":"server","correct":"const { server } = require('on-http/lib/app');"},{"note":"Imports the configured nconf instance for programmatic access to runtime settings. This is an advanced use case for deep integration or testing within the CommonJS module system.","wrong":"import nconf from 'on-http/lib/config';","symbol":"nconf","correct":"const nconf = require('on-http/lib/config');"}],"quickstart":{"code":"#!/bin/bash\n\n# NOTE: This quickstart assumes MongoDB and RabbitMQ are already running and accessible\n# on their default ports (localhost:27017 for Mongo, localhost:5672 for RabbitMQ).\n\n# Clean existing node_modules and install dependencies\nrm -rf node_modules\nnpm install\n\n# Generate API and task documentation (optional, but good for setup and local access)\nnpm run apidoc\nnpm run taskdoc\n\n# Start the on-http server in the background.\n# The README shows 'sudo node index.js', which is typically required for system ports or permissions.\n# For development, you might adjust permissions or run on a higher port.\nsudo node index.js &\nSERVER_PID=$!\n\necho \"on-http server started (PID: $SERVER_PID). Waiting for it to become ready...\"\nsleep 10 # Give the server some time to initialize and connect to dependencies\n\n# Perform basic health checks and access documentation\necho \"Accessing RackHD UI and API endpoints:\"\n\n# Check the Web UI\ncurl -s -o /dev/null -w \"HTTP Status: %{http_code}\\n\" http://127.0.0.1/ui\necho \"- UI expected at http://127.0.0.1/ui\"\n\n# Check the API documentation\ncurl -s -o /dev/null -w \"HTTP Status: %{http_code}\\n\" http://127.0.0.1/docs\necho \"- API Docs expected at http://127.0.0.1/docs\"\n\n# Example: Try to fetch a list of nodes (requires RackHD to have discovered nodes)\ncurl -s -o /dev/null -w \"HTTP Status: %{http_code}\\n\" http://127.0.0.1/api/current/nodes\necho \"- API endpoint /api/current/nodes (status 200 means success, data depends on setup)\"\n\n# Clean up: Kill the background server process\nkill $SERVER_PID\nwait $SERVER_PID 2>/dev/null\necho \"on-http server (PID: $SERVER_PID) stopped.\"","lang":"bash","description":"This script demonstrates how to install `on-http`, generate its documentation, start the server in the background, perform basic `curl` requests to its UI and API endpoints, and then gracefully shut it down. It highlights the prerequisite external services (MongoDB, RabbitMQ) and the common practice of using `sudo` to run the server."},"warnings":[{"fix":"Ensure MongoDB and RabbitMQ services are installed, started, and configured to be reachable from the `on-http` server. Check logs for connection errors during startup.","message":"The `on-http` server requires external MongoDB and RabbitMQ instances to be running and accessible for correct operation. Failure to connect to these services will prevent the server from starting or functioning properly.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Update all API calls to utilize the 2.0 API, typically by prefixing endpoints with `/api/2.0/` or `/api/current/`. Refer to RackHD's readthedocs for functional differences and migration guides.","message":"The 1.1 API for RackHD is officially deprecated. While it may still function, new development and integrations should exclusively target the 2.0 API.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Prefer running the application under a dedicated, unprivileged user account. If port 80/443 access is required, use a reverse proxy (e.g., Nginx, Apache) or grant specific port permissions (e.g., using `authbind` or `setcap`).","message":"The official documentation often shows running `node index.js` with `sudo`. Running Node.js applications as root is generally a security risk and can lead to permission issues with files created by the application. Consider alternative deployment strategies.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Install `node-inspector` globally (`npm install node-inspector -g`), start it in the background (`node-inspector --preload=false &`), and then launch `on-http` with debugging enabled (`sudo DEBUG=express:* node --debug-brk index.js`).","message":"When debugging Node.js applications, the `node-debug` command is noted to not work well with `on-http`. Instead, `node-inspector` is recommended for GUI-based debugging.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify that MongoDB is running and listening on the expected port (default 27017). Check network connectivity and MongoDB configuration settings.","cause":"The MongoDB database server is not running or is inaccessible from the on-http server.","error":"Error: failed to connect to [localhost:27017]"},{"fix":"Ensure the RabbitMQ service is active and listening on its configured port (default 5672). Review RabbitMQ logs for startup issues.","cause":"The RabbitMQ message broker is not running or is inaccessible from the on-http server.","error":"Failed to connect to RabbitMQ broker: amqp://localhost"},{"fix":"Inspect the configuration files (e.g., `./config/default.json` or environment variables) to ensure the `fileService` object exists and contains a `defaultBackend` key with a valid backend string, as well as configurations for all defined backends.","cause":"The `fileService` configuration key, or its sub-keys like `defaultBackend`, are missing or incorrectly defined in the application's configuration files.","error":"TypeError: Cannot read property 'defaultBackend' of undefined"}],"ecosystem":"npm","meta_description":null}