NodeBB

NodeBB is an open source community forum written in Node.js. It is usually set up with an interactive ./nodebb setup wizard against MongoDB, but it also supports PostgreSQL and Redis as its datastore and can be set up without prompts from environment variables, which is how it runs on Hatchbox.

Requirements

Create a PostgreSQL database on the app's Databases tab. NodeBB does not read DATABASE_URL; you will copy the host, user, password and database name out of it into the variables below. (NodeBB can also run entirely on Redis, with NODEBB_DB=redis, but PostgreSQL is the safer choice.)

NodeBB keeps its package.json in install/ rather than the repository root, so Hatchbox cannot detect Node.js on its own. The fork adds a .tool-versions file to install it.

Repository

Fork the NodeBB repository, add the files below, and point Hatchbox at your fork:

https://github.com/NodeBB/NodeBB.git

Use the v4.x branch, which upstream's install guide recommends. It tracks the latest stable 4.x release; master and develop are not meant for production.

Add .tool-versions with the Node.js version NodeBB's Docker image and CI use:

nodejs 24.21.0

Environment Variables

NODEBB_URL=https://forum.example.com
NODEBB_DB=postgres
NODEBB_DB_HOST=<host from DATABASE_URL>
NODEBB_DB_PORT=5432
NODEBB_DB_USER=<user from DATABASE_URL>
NODEBB_DB_PASSWORD=<password from DATABASE_URL>
NODEBB_DB_NAME=<database from DATABASE_URL>
NODEBB_ADMIN_USERNAME=admin
NODEBB_ADMIN_EMAIL=you@example.com
NODEBB_ADMIN_PASSWORD=<password>

These are read once, by ./nodebb setup on the first deploy, and written to config.json. NODEBB_URL must be exactly the URL users will open. All of them are required: without NODEBB_DB_HOST and NODEBB_DB_PORT setup silently uses 127.0.0.1:5432, and if any of the three NODEBB_ADMIN_ variables is missing, setup logs an error and exits without writing config.json, so the deploy looks successful but the web process starts NodeBB's web installer instead of your forum. You can delete NODEBB_ADMIN_PASSWORD after the first successful deploy. PORT is set by Hatchbox and NodeBB reads it at runtime, overriding the port stored in config.json.

Build Scripts

Each release is a fresh checkout, but NodeBB expects config.json, package.json (where plugins you install from the admin panel are recorded) and public/uploads to persist. The build script keeps all three in shared/ and symlinks them into the release, mirroring what NodeBB's own Docker entrypoint does.

.hatchbox/build

#!/usr/bin/env bash
set -e

mkdir -p "$DIR/shared/nodebb"

# package.json records installed plugins; config.json is written by setup
if [ ! -f "$DIR/shared/nodebb/package.json" ]; then
  cp install/package.json "$DIR/shared/nodebb/package.json"
fi
ln -sfn "$DIR/shared/nodebb/package.json" package.json
ln -sfn "$DIR/shared/nodebb/config.json" config.json

# Uploads: seed shared/uploads from the repository's folder skeleton on the first deploy
if [ ! -d "$DIR/shared/uploads" ]; then
  mv public/uploads "$DIR/shared/uploads"
fi
rm -rf public/uploads
ln -sfn "$DIR/shared/uploads" public/uploads

npm install --omit=dev

if [ "$CRON" = "true" ]; then
  if [ -f config.json ]; then
    # Merge new base dependencies, run schema upgrades and rebuild assets
    ./nodebb upgrade -misb
  else
    # First deploy: non-interactive setup from the NODEBB_* variables
    ./nodebb setup '{"trust_proxy": true}'
  fi
else
  ./nodebb build
fi

./nodebb setup creates the schema, the admin user and config.json, then builds the assets. trust_proxy is passed here because it has no environment variable; it tells Express to trust the X-Forwarded-* headers from Hatchbox's reverse proxy. On later deploys ./nodebb upgrade -misb updates package.json from upstream's defaults, installs dependencies, runs schema upgrades and rebuilds assets, but leaves plugin version upgrades to you.

Processes

Add one process on the Processes tab:

1. web on your web servers: node loader.js --no-daemon --no-silent

This is the same command NodeBB's Docker image runs. --no-daemon keeps it in the foreground for systemd and --no-silent sends logs to stdout instead of logs/output.log.

First Login

Open your domain and sign in with NODEBB_ADMIN_USERNAME and NODEBB_ADMIN_PASSWORD. The admin control panel is at /admin.

Notes

Run NodeBB on a single server, at least for the first deploy. ./nodebb setup runs only on the cron server, and a web-only server that builds before config.json exists starts NodeBB's web installer instead of building.

Plugins installed from the admin panel are recorded in shared/nodebb/package.json and reinstalled on every deploy.

To change the forum URL, database settings or other options later, edit shared/nodebb/config.json and restart the process. To upgrade NodeBB, merge upstream v4.x into your fork and deploy.