So you are interested in using NodeBB?

[Tracy]

This guide will go over the basics of installing NodeBB on an Ubuntu LTS based VPS/dedicated server. I strongly suggest using Ubuntu 24.04LTS as one install I attempted on 22.40LTS had some dependency issues.
It will not cover actual Linux OS setup, as I assume if you have wanting to install NodeBB you will already be familiar with the process of setting up your VPS/dedicated server and configuring it.
Again, I suggest using Ubuntu 24.04LTS because the documentation relating to installing NodeBB on Ubuntu is more detailed than for CentoOS/AlmaLinux/Rocky Linux.

NOTE! You will see me using sudo in some of the commands even after I said to change over to the root user. This is just a safety precaution in case you forget.

If you are not comfortable setting up your VPS or operating in a shell and using CLI, then I would actively encourage you to engage someone that does this for living to assist you.

You should have a minimum of 1GB RAM for your system. If you are using it on a low memory VPS it is assumed you have also already set up a swap for it. If not, you need to do so.

Installing Node.js

Since NodeBB usesNode.js instead of PHP, you will need to install node.js onto your server.
The installation of the current LTS version of Node.js is strongly suggested as it causes less problems for future updates.

You will be downloading a script during this setup using curl. These instructions assume you know how to run the script from the CLI.

Enter the following commands on the CLI of your terminal shell.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh

When you run the above script it should install the repository information for Node.js along with a few other items of importance that may not have been installed.
Use the following commands to now install it.

sudo -E bash nodesource_setup.sh
sudo apt-get install -y nodejs

Verify installation of Node.js and npm. You should have version 22.13.0 of Node.js installed (as of January 10, 2025), and version 10 of npm installed:

node -v
npm -v

npm should put out output "10.9.2" or similar.
I suggest using the MongoDB instead of Redis or PostgreSQL. It is what is recommended by the NodeBB developers and I figure they know beset. Since I did not use Redis or PostgreSQL so I can not comment on them.

Installing MongoDB
MongoDB is the default (and recommended) database for NodeBB. You need to use at least version 8.0 of MongoDB.

This is a quick guide to installing MongoDB v8 on your Ubuntu server.

sudo apt-get install gnupg curl
curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-8.0.gpg \
   --dearmor
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-8.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org

You now need to verify the installation of MongoDB. You should have version 8.0.

mongod --version

This should return the version.

Now you need to start the mongod service and verify service status. MongoDB should be active.

sudo systemctl start mongod
sudo systemctl status mongod

Configuring MongoDB
Administration of MongoDB is done through the MongoDB Shell mongosh. The default installation of MongoDB listens on port 27017 and is accessible locally.
To access the the shell you need to enter the below via the terminal CLI.

mongosh

You now need to switch to the built-in admin database

use admin

You will now need to create an administrative user for MondoDB (this is different from the nodebb user that you will create later). Replace the placeholder Enter a secure password here with your own selected password.

db.createUser( { user: "admin", pwd: "ENTER A SECURE PASSWORD HERE>", roles: [ { role: "root", db: "admin" } ] } )

Once you have done this and hit ENTER key you should see the output of ok: 1. This user can now be used to the access/control the admin database to manage MongoDB once authorization has been enabled.

Now you need to create the NodeBB database for use. While still in mongoosh shell you need to enter

use YOUR_DATABASE_NAME

The database will be created using the name you input in the YOUR_DATBASE_NAME and you will then be switched to that newly created database. Now you need to create the user for the nodeBB database and assign it the appropriate privileges.

db.createUser( { user: "YOUR_DB_USER_NAME_TO_USE", pwd: "ENTER_A_SECURE_PASSWORD", roles: [ { role: "readWrite", db: "YOUR_DATABASE_NAME" }, { role: "clusterMonitor", db: "admin" } ] } )

The readWrite permission allows NodeBB to store and retrieve data from the database you assigned to be used for NodeBB.

You now should exit the Mongo Shell

quit()

Now it is time to enable database authorization in the MongoDB configuration file /etc/mongod.conf. You need to add the following lines.

security:
  authorization: enabled

Now it is time to restart MongoDB and confirm that the administrative user you created earlier can connect (this is NOT the user you created to use NodeBB with).

To restart MongoDB use

sudo systemctl restart mongod

To connect to a MongoDB deployment that requires authentication, use the --username and --authenticationDatabase options. mongosh will prompt you for the password that you created for the administrative user.

mongosh "mongodb://localhost:27017" --username admin --authenticationDatabase admin

If everything is configured the Mongo Shell will connect. Exit the shell with quit().

Installing NodeBB
nodeBB requires the use of git, so you must install as it is used to distribute NodeBB:

sudo apt-get install -y git

SPECIAL NOTE!!! Commands like git and ./nodebb should not be used with root access (sudo or elevated privileges). It will cause problems with different ownership of files NodeBB needs access to. Switch to a non-privileged user before running these commands.

Now you need to clone NodeBB into an appropriate location. Since I installed Ubuntu and there was already a /var/www installed I created a new directory in that path.
I then changed into the /var/www directory and issued

git clone -b v3.x https://github.com/NodeBB/NodeBB.git nodebb
cd nodebb

You have now cloned the NodeBB repository from the v3.x branch to the nodebb directory. You can find a list of alternative branches are available in the NodeBB Branches GitHub page if you want to us a different version.

NodeBB ships with a command line utility which allows for several functions. You will use it to setup NodeBB. This installs the modules from npm and then it will enter the setup utilty.

./nodebb setup

You will then be given a series of questions. The default values are in parentheses.
The default settings are based upon a local server listening on the default port 4567 with a MongoDB instance listening on port 27017. When prompted for the mongodb username and password, enter the nodeBB database username you created earlier (not the admin one) and then the password that you set earlier. Once connectivity to the database is confirmed the setup will prompt that initial user setup is running.
If this is a fresh install (which it should be) then you will need to set up aforum administrator. Enter the administrator information you wish to use. This is what you will log into your forum with initially.
Pay special attention when entering your site URL. You need to make sure it is exactly what you plan on accessing your site at. If your site is HTTPS://mysite.org then that is what you need to enter. Do NOT use the IP address of your server instance. Also, I found that I did NOT want to put the port number on the URL in the .JSON file as it caused issues. NodeBB knows the default port it runs on so there is no need to put it here. If you are going to run on other than the default port, you can use the PORT parameter in the JSON file.

A configuration file config.json is then created in the root of the nodebb directory.You can then make changes to it if you need to change the database location or credentials used to access the database.

Now you can use the CLI to start NodeBB.

./nodebb start

To give the best performance and to keep from having to either place the port number after the domain on your browser it is recommended to place a proxy in front of it. I chose to use nginx as it is what I am somewhat familiar with. You can also use Apache if you are more familiar with it, but this guide will not cover that.

So, if you do want to use a proxy (again, which I strongly recommend) you need to install nginx on your Ubuntu server.

Next post will be for the nginx proxy.

 

[Tracy]

Installing nginx

As I mentioned, NodeBB runs on port 4567 by default. This means that you must access it using a port number in addition to the hostname (e.g. http://example.org:4567)

To prevent this, you place nginx as a proxy in front of the NodeBB install.

To install nginx, you now need to switch back to the root user or do a sudo su and enter the root password.

Now we start the nginx installation.

sudo apt-get install -y nginx

Once the install process is completed you need to verify the installation and make sure that the version of nginx installed is at least 1.3.13, and newer is suggested.
Verify the installation of nginx

nginx -v

Now you need to confirm that nginx will run

sudo systemctl start nginx
sudo systemctl status nginx

We now start the fun of configuring nginx for use as a proxy with NodeBB.
I'm not going to go into great detail as nginx can get very confusing. Basically all you need to do is, after confirming nginx is running, create a VHOST in /etc/nginx/sites-available.
I use the domain-name.conf format for naming the files in /etc/nginx/sites-available.

I also use joe for my editor on almost all my Linux installs. If you are familiar with nano already, then you can use that instead.

To create your vhost definition you need to do the following:

cd /etc/nginx/sites-available
sudo joe YOUR_DOMAIN_NAME

* Replace YOUR_DOMAIN_NAME with the domain the site is running on. *

In this file you need to enter:

server {
    listen 80;

    server_name YOUR_SITE_DOMAIN_NAME;

    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-NginX-Proxy true;

        proxy_pass http://127.0.0.1:4567;
        proxy_redirect off;

        # Socket.IO Support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

This will give you a vhost running on port 80 (non-HTTPS).

If you want to use HTTPS you will need to use a different vhost configaration.

### redirects http requests to https
server {
    listen 80;
    server_name forum.example.org;

    return 302 https://$server_name$request_uri;
}

### the https server
server {
    # listen on ssl, deliver with speedy if possible
    listen 443 ssl spdy;

    server_name forum.example.org;

    # change these paths!
    ssl_certificate /path/to/cert/bundle.crt;
    ssl_certificate_key /path/to/cert/forum.example.org.key;

    # enables all versions of TLS, but not SSLv2 or 3 which are weak and now deprecated.
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

    # disables all weak ciphers
    ssl_ciphers 'AES128+EECDH:AES128+EDH';

    ssl_prefer_server_ciphers on;

    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-NginX-Proxy true;

        proxy_pass http://127.0.0.1:4567;  # no trailing slash
        proxy_redirect off;

        # Socket.IO Support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

You will need to obtain your own SSL certs and make the necessary changes to the related SSL_CERTIFICATE and SSL_CERTIFICATE_KEY parameters in it. Another option is to use LetsEncrypt for your SSL and certbot to install it (this is what I did).

Getting Started

The Let's Encrypt ACME Directory URL is: https://acme-v02.api.letsencrypt.org/directory To enable HTTPS on your website, you need to get a certificate (a type of file) from a Certificate Authority (CA). Let’s Encrypt is a CA. In order to get a certificate for your website’s domain from Let’s...

letsencrypt.org

Be sure to change the YOUR_SITE_DOMAIN_NAME to the domain your site will be running on and what you used in the earlier NodeBB setup.

Save the file (in joe using CTL X)

Now you need to create a link in the /etc/nginx/sites-enabled directory to the vhost you just created. This will allow nginx to recognize it and use it to start the instance.

cd ../sites-enabled
sudo ln -s ../sites-available/forum.example.com

Once you have done this, you then need to reload nginx for changes to take effect:

sudo systemctl reload nginx

You will also want to enable the ability to set up NodeBB to be automatically started on a system reboot .

To do this, I use systemd
You need to create the necessesary config file in /etc/systemd/system. The NodeBB recommendation is to use nodebb.service as the file name. I did mine based upon my domain name as I may do some playing with additional NodeBB sites on my VPS installation and thought it would be easier to keep up with them if they had their own distinctive name.

In this file you need to put

[Unit]
Description=NodeBB
Documentation=https://docs.nodebb.org
After=system.slice multi-user.target mongod.service

[Service]
Type=forking
User=nodebb

WorkingDirectory=/path/to/nodebb
PIDFile=/path/to/nodebb/pidfile
ExecStart=/usr/bin/env node loader.js --no-silent
Restart=always

[Install]
WantedBy=multi-user.target

Be sure to change the User=nodebb to a user you have created on your Ubuntu install with as few privileges as possible.
You also need to edit the path to your NodeBB install.

After saving this file you should now be able to start/stop and check status of nodeBB like you would any other system service.

To automate the starting of NodeBB and MongoDB you need to enter (as root or with sudo privs)

systemctl enable mongod
systemctl enable nodebb

If everything went well, you should have an operational NodeBB system up and running.
Next we will discuss integrating with CloudFlare and the one important thing you MUST enable.

 

[Tracy]

I ran myself ragged trying to figure out why NodeBB did so well when CloudFlare proxy was disabled and then it acted like molasses in winter time with the CF proxy enabled.
It came down to one word.
Websockets
NodeBB makes use of them, CloudFlare did not like them in the default domain setup. The solution was actually very simple. You need to go into your Network settings in CloudFlare and enable Websockets.

Once you do that, it should work fine and you get all the benefits of the CF proxy service.
Everything else is pretty much the same as any other site under CF.
If you are using an SSL, I would suggest using CF to rewrite all your inbound traffic to HTTPS at that level instead of doing it at the server level.