RackHD HTTP Server (on-http)

Common errors

• Error: failed to connect to [localhost:27017]

  cause The MongoDB database server is not running or is inaccessible from the on-http server.
  fix Verify that MongoDB is running and listening on the expected port (default 27017). Check network connectivity and MongoDB configuration settings.

• Failed to connect to RabbitMQ broker: amqp://localhost

  cause The RabbitMQ message broker is not running or is inaccessible from the on-http server.
  fix Ensure the RabbitMQ service is active and listening on its configured port (default 5672). Review RabbitMQ logs for startup issues.

• TypeError: Cannot read property 'defaultBackend' of undefined

  cause The `fileService` configuration key, or its sub-keys like `defaultBackend`, are missing or incorrectly defined in the application's configuration files.
  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.

Warnings

• gotcha 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.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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`).
• gotcha 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.
  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`).

Install

• npm install on-http npm
• yarn add on-http yarn
• pnpm add on-http pnpm

Imports

• app
  wrong:

  import { app } from 'on-http/lib/app';
  const app = require('on-http');

  correct:

  const { app } = require('on-http/lib/app');

  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.
• server
  wrong:

  import { server } from 'on-http/lib/app';
  const { Server } = require('on-http');

  correct:

  const { server } = require('on-http/lib/app');

  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.
• nconf
  wrong:

  import nconf from 'on-http/lib/config';

  correct:

  const nconf = require('on-http/lib/config');

  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.

Quickstart

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.

#!/bin/bash

# NOTE: This quickstart assumes MongoDB and RabbitMQ are already running and accessible
# on their default ports (localhost:27017 for Mongo, localhost:5672 for RabbitMQ).

# Clean existing node_modules and install dependencies
rm -rf node_modules
npm install

# Generate API and task documentation (optional, but good for setup and local access)
npm run apidoc
npm run taskdoc

# Start the on-http server in the background.
# The README shows 'sudo node index.js', which is typically required for system ports or permissions.
# For development, you might adjust permissions or run on a higher port.
sudo node index.js &
SERVER_PID=$!

echo "on-http server started (PID: $SERVER_PID). Waiting for it to become ready..."
sleep 10 # Give the server some time to initialize and connect to dependencies

# Perform basic health checks and access documentation
echo "Accessing RackHD UI and API endpoints:"

# Check the Web UI
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" http://127.0.0.1/ui
echo "- UI expected at http://127.0.0.1/ui"

# Check the API documentation
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" http://127.0.0.1/docs
echo "- API Docs expected at http://127.0.0.1/docs"

# Example: Try to fetch a list of nodes (requires RackHD to have discovered nodes)
curl -s -o /dev/null -w "HTTP Status: %{http_code}\n" http://127.0.0.1/api/current/nodes
echo "- API endpoint /api/current/nodes (status 200 means success, data depends on setup)"

# Clean up: Kill the background server process
kill $SERVER_PID
wait $SERVER_PID 2>/dev/null
echo "on-http server (PID: $SERVER_PID) stopped."