# NodeBB

NodeBB is a modern forum platform with real-time discussions and a plugin ecosystem

[NodeBB](https://github.com/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.