# NodeBB: A Node.js Forum With WebSockets, Three Database Choices, and a CLI Installer

> NodeBB is a GPL-3.0 forum platform for Node.js 22 or newer that stores its data in MongoDB, Redis, or PostgreSQL. Here is how the setup flow works, what the Docker compose file actually starts, and where the project's own documentation stops short.

**NodeBB/NodeBB** — Node.js based forum software built for the modern web. NodeBB Forum Software** is powered by Node.js and supports either Redis, MongoDB, or a PostgreSQL database.

- Repository: https://github.com/NodeBB/NodeBB
- Website: https://nodebb.org
- Stars: 15,227 · Forks: 2,999
- Language: JavaScript
- License: GPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/nodebb-nodebb

## What NodeBB Solves and Who Ends Up Running It

NodeBB is forum software for people who want the older bulletin-board shape (categories, threads, local user accounts, asynchronous replies) without giving up the behaviours users now expect from a modern web app. The README puts it plainly: the project keeps "categorical hierarchies, local user accounts, and asynchronous messaging" while adding real-time streaming discussions, mobile responsiveness and RESTful read and write APIs. The real-time part is not decoration. NodeBB uses web sockets for instant interactions and notifications, which means a reply can appear in a thread without a page reload.

The audience is narrower than the feature list suggests. You need a Node.js runtime at version 22 or greater, plus MongoDB 5 or greater, or Redis 7.2 or greater. If you plan to run NodeBB clustered, the requirements section says Redis must be installed and configured, so a MongoDB-only deployment is implicitly a single-process one unless you add Redis anyway. nginx 1.3.13 or greater is listed as a requirement only when you intend to proxy requests through it. This is software for someone who is willing to operate a Node.js process and a database, not a drop-in hosted product.

The README also frames the architecture in a way worth reading carefully: NodeBB "by itself contains a 'common core' of basic functionality, while additional functionality and integrations are enabled through the use of third-party plugins." That is a statement about scope. Features you might assume are built in may live in the plugin directory instead, and the repository points contributors at that plugin category as a starting point for learning the codebase.

## How the Core, the Database Layer, and the WebSocket Layer Fit Together

The repository layout tells you more about the runtime than the README does. There is app.js at the top level, plus loader.js, require-main.js and nodebb-global.js. A nodebb executable script sits alongside nodebb.bat for Windows. The build directory is a build artefact, and the Dockerfile treats it that way by declaring a volume for /usr/src/app/build in the compose file. The src/ directory holds the application code, and install/ holds installer assets, including install/docker/setup.json and install/docker/mongodb-user-init.js referenced by the compose file.

The database choice is a configuration decision rather than a code fork. The README lists Redis, MongoDB, or PostgreSQL, and the compose file ships service definitions for all three, but they are not all active at once. The mongo service has no profile and starts by default; redis and postgres are each placed behind a Compose profile named redis and postgres respectively. So the default docker-compose up brings up NodeBB plus MongoDB, and switching databases means selecting a profile or using one of the alternate compose files in the repository root: docker-compose-redis.yml and docker-compose-pgsql.yml.

The web socket layer is the part with the most operational consequences and the least documentation in the README. Instant notifications mean persistent connections held open per user, which is why clustering requires Redis: multiple NodeBB processes need a shared bus for those events. The README states the dependency but does not describe the mechanism, and the scaling page at docs.nodebb.org/configuring/scaling is where the project sends you. If you are sizing a deployment, that page is the one to read before you pick a database, because a single MongoDB instance is a simpler story than MongoDB plus Redis.

## Installing NodeBB With the CLI Installer

The README is explicit that NodeBB does not start the way most Node.js projects do. In its own words, NodeBB "uses a CLI-based setup and does not run via standard npm start." The native path is three steps: clone, run the setup script, start the application. Cloning looks like this.

```bash
git clone https://github.com/NodeBB/NodeBB.git
cd NodeBB
```

Then run the interactive setup. The README lists it as ./nodebb setup, and notes that during setup you configure the database (MongoDB or Redis), an admin account, and the port, whose default is 4567.

```bash
./nodebb setup
./nodebb start
```

After ./nodebb start, the process runs as a daemon and the forum answers on port 4567 unless you changed it during setup. The README also points at platform-specific instructions at docs.nodebb.org/installing/os because, as it says, installation steps vary by operating system. Treat the three commands above as the shape of the flow, not a complete recipe for every distribution.

The Docker path skips the interactive installer. The README gives a single command, docker-compose up, and states that this starts NodeBB along with the required services at http://localhost:4567. The compose file maps '4567:4567' and persists four volumes, including nodebb-config mounted at /opt/config and nodebb-uploads at /usr/src/app/public/uploads. It also bind-mounts ./install/docker/setup.json into the container, which is how the container answers the setup questions the interactive CLI would otherwise ask. If you want the published image instead of a local build, the compose file carries a commented line: image: ghcr.io/nodebb/nodebb:latest.

## The Security Defaults You Have to Fix Yourself

The README's securing section is the most direct piece of writing in the document, and it is worth quoting the premise: Redis by default listens to all interfaces, "which is especially dangerous when a server is open to the public." The suggested fixes are to set bind_address to 127.0.0.1 and to use requirepass to put a password in front of Redis. Neither is presented as something the installer does for you.

This matters more in the Docker path than the native one. The compose file publishes MongoDB on '27017:27017' and sets MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD both to the literal value nodebb. Those credentials are visible in the repository. If you run the default compose file on a host with a public interface, you have published a database port with a guessable password. The README's iptables guidance applies here: it suggests that if NodeBB is proxied, no ports should be open except 80, and possibly 22 for SSH. The compose file's own comment on the NodeBB port says you can comment the mapping out or change the first number, which is the intended escape hatch.

The Redis and PostgreSQL service definitions do not publish ports at all, so profile-based deployments expose less by default. That is an argument for choosing the redis or postgres profile over the default mongo setup if you are deploying to a machine with a routable address and you do not want to edit the compose file.

## Where NodeBB Is the Wrong Choice

The README does not document rollback. The upgrading section is a single sentence pointing to docs.nodebb.org/configuring/upgrade, and the repository carries a CHANGELOG.md but nothing in the README explains how to reverse a version bump or what happens to the database schema when you move between releases. For a project whose recent releases are dated within days of each other (v4.14.10, v4.15.0, v4.15.1), that is a real operational gap. If your organisation requires a tested downgrade path before any upgrade, you will be building that practice yourself from the changelog and the upgrade documentation.

The licensing is the second boundary. NodeBB is GPL-3.0. The README notes that a sublicense agreement is available for "use of NodeBB in a non-free/restrictive environment" and gives sales@nodebb.org as the contact. If you intend to embed a forum inside a proprietary product, that clause is the one to resolve before you write code, not after.

Third, the plugin architecture cuts both ways. The README describes a common core with third-party plugins supplying additional functionality and integrations. That means the quality and maintenance of a feature you depend on may sit outside the repository you are evaluating. There is no plugin compatibility matrix in the README, and nothing states which plugin versions track which NodeBB releases.

Finally, the requirements are not modest. Node.js 22 or greater, MongoDB 5 or greater or Redis 7.2 or greater, and Redis as well if you cluster. On a shared host with an older runtime, NodeBB is simply not an option until the runtime is upgraded.

## How NodeBB Differs From Discourse and Flarum

The comparison people actually search for is NodeBB against Discourse, and the architectural difference is worth stating precisely. Both are Node.js forum platforms built around real-time interaction, but NodeBB supports MongoDB, Redis, or PostgreSQL, whereas the NodeBB README describes no such choice for its neighbour. If your infrastructure team already runs PostgreSQL and refuses to add another datastore, NodeBB's postgres profile and docker-compose-pgsql.yml give you a path that a MongoDB-only platform does not.

Flarum is a different kind of difference. It is a PHP application, so the operational story is a PHP-FPM process behind a web server rather than a Node.js daemon managed by ./nodebb start. If your team's expertise is PHP and your deployment tooling assumes it, Flarum fits an existing pattern and NodeBB asks you to learn a new one.

Where NodeBB's own design shows is the theming engine. The README claims the engine "is highly flexible and does not restrict your design choices," and notes that the base theme uses Bootstrap 5, with extension of base templates plus styling via SCSS or CSS. That is a concrete statement about how far a designer can go without forking. The README also says NodeBB needs themes and links a themes category, which is an admission that the shipped Harmony theme is a starting point rather than a finished look. Whichever platform you pick, budget for theme work.

## Maintenance, Upgrades, and the GPL-3.0 Question

The last push to the default branch was on 2026-08-19, the same date as the v4.15.1 release. Releases in the weeks before it were v4.15.0 on 2026-08-12 and v4.14.10 on 2026-08-11. That cadence tells you the project is moving, and it also tells you the upgrade surface is live: patch releases arrive close together, and the README does not describe how to move between them beyond linking to docs.nodebb.org/configuring/upgrade. A renovate.json file sits in the repository root, which suggests dependency updates are automated, but that says nothing about your own upgrade procedure.

The practical cost of running NodeBB is the cost of three things: a Node.js runtime you keep current, a database you back up, and a plugin set you re-verify after each release. The compose file's volumes make the stateful parts visible. nodebb-uploads holds user files, the database volume holds everything else, and nodebb-config at /opt/config holds configuration. Backing up those three is the whole backup story, and the compose file is the clearest documentation of it in the repository.

On licensing, GPL-3.0 is a copyleft licence. The README states the project is licensed under it and separately offers a sublicense agreement for non-free or restrictive environments via sales@nodebb.org. Whether your use triggers the copyleft obligations is a question for your own counsel; what the repository tells you is that the project itself considers commercial relicensing a separate arrangement, and that the contact for it exists.

## Conclusion

Adopt NodeBB if you want a bulletin-board structure with real-time updates and you are comfortable running Node.js plus a database yourself; the compose file gets you to a working instance on port 4567 without touching the installer. Do not adopt it if you need a fully managed upgrade path or you cannot live with GPL-3.0 in a closed product, since the README points non-free use at a sublicense agreement with sales@nodebb.org. Before committing, verify which Node.js and database versions your host actually ships, and read the upgrade page at docs.nodebb.org/configuring/upgrade because the README delegates that procedure entirely.

## FAQ

### What is NodeBB?

NodeBB is forum software written for Node.js that supports Redis, MongoDB, or PostgreSQL as its database. It keeps the traditional bulletin-board structure of categories, user accounts and threaded replies while using web sockets for instant interactions and notifications.

### how to install nodebb

The README gives two paths. Natively, clone the repository, run ./nodebb setup, then ./nodebb start, and you configure the database, admin account and port during setup. Alternatively, run docker-compose up, which the README says starts NodeBB with the required services at http://localhost:4567.

### is nodebb free

NodeBB is licensed under GPL-3.0, so it can be used without a licence fee. The README notes that a sublicense agreement is available for use in a non-free or restrictive environment, with sales@nodebb.org as the contact.

### is nodebb open source

Yes. The repository is public, the source is on the master branch, and the README states the project is licensed under the GNU General Public License v3 (GPL-3).

### nodebb vs discourse

Both are Node.js forum platforms, but NodeBB supports MongoDB, Redis, or PostgreSQL, giving you a choice of datastore. The NodeBB README does not describe an equivalent database choice for Discourse, so the decision often comes down to which database your infrastructure already runs.

## Sources

- [Official documentation](https://nodebb.org)
- [Official README](https://github.com/NodeBB/NodeBB#readme)
- [Project repository](https://github.com/NodeBB/NodeBB)
- [Release notes](https://github.com/NodeBB/NodeBB/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nodebb-nodebb