Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/binary-person/rammerhead/llms.txt

Use this file to discover all available pages before exploring further.

Rammerhead can run as a standalone Node.js process with no additional infrastructure. This guide walks through cloning the repository, configuring the server, enabling SSL, and keeping the process alive with a process manager.

​
Prerequisites

  • Node.js v16 or higher
  • git

​
Installation

1

Clone the repository

git clone https://github.com/binary-person/rammerhead.git
cd rammerhead
2

Install dependencies

npm install
3

Build the client scripts

Rammerhead ships unbuilt client-side JavaScript. Run the build step before starting the server:
npm run build
4

Start the server

npm run start
This runs node src/server.js. You can also invoke it directly:
node src/server.js

​
Configuration

All configuration lives in src/config.js. To override settings without touching the source file — which makes pulling future updates easier — create a config.js file in the repository root. Rammerhead merges it over the defaults at the end of src/config.js: 
// At the bottom of src/config.js:
if (fs.existsSync(path.join(__dirname, '../config.js')))
  Object.assign(module.exports, require('../config'));

​
Binding address and port

By default, Rammerhead binds to 127.0.0.1:8080 and opens a second cross-domain port at 8081. Change these in your root config.js: 
// config.js (root of repository)
module.exports = {
  bindingAddress: '0.0.0.0', // listen on all interfaces
  port: 8080,
  crossDomainPort: 8081,
};
Binding to 0.0.0.0 exposes Rammerhead on every network interface. Only do this if you intend to receive traffic directly, or if a firewall protects the port.

​
SSL configuration

Set ssl to an object with the PEM-encoded key and certificate. Rammerhead passes this directly to Node.js’s https.createServer: 
// config.js
const fs = require('fs');

module.exports = {
  ssl: {
    key: fs.readFileSync('/etc/ssl/private/rammerhead.key'),
    cert: fs.readFileSync('/etc/ssl/certs/rammerhead.crt'),
  },
};
When ssl is null (the default), the server uses plain HTTP.
If you are terminating TLS at a reverse proxy such as nginx, keep ssl: null in Rammerhead and let the proxy handle certificates. See the reverse proxy guide for details.

​
Development mode

Set the DEVELOPMENT environment variable to enable debug logging and serve unminified client scripts: 
DEVELOPMENT=true node src/server.js
When DEVELOPMENT is falsy, logLevel defaults to 'info'; with it set, logLevel switches to 'debug'.

​
Using a .env file

Rammerhead uses dotenv-flow (loaded in the master process before workers start). Create a .env file in the repository root: 
# .env
DEVELOPMENT=true
dotenv-flow also supports environment-specific files such as .env.production and .env.local.

​
Process management

Rammerhead does not daemonize itself. Use a process manager to keep it running after you close your terminal session.
Install pm2 globally and start Rammerhead:
npm install -g pm2
pm2 start src/server.js --name rammerhead
pm2 save
pm2 startup
pm2 startup prints a command you run once to register pm2 with your init system so Rammerhead restarts on reboot.

​
Verifying the server is running

Rammerhead exposes two lightweight endpoints you can curl to confirm the server is up. Check whether a session password is required: 
curl http://localhost:8080/needpassword
# returns: true
Create a new session and receive its ID: 
curl "http://localhost:8080/newsession?pwd=sharkie4life"
# returns: <session-id>
The default password is sharkie4life, set via the password field in config.js. Set password: null to disable authentication entirely.

Build docs developers (and LLMs) love

Get started for freeTalk to us