Knowledgebase

NodeBB is a Node.js based forum software. It utilizes web sockets for instant interactions and real-time notifications. The NodeBB source code is publicly hosted on Github. This guide will walk you through NodeBB installation process on a fresh FreeBSD 12 Rcs instance, by using Node.js, MongoDB as a database, Nginx as a reverse proxy, and Acme.sh for SSL certificates.

Requirements

NodeBB requires the following software to be installed:

• Node.js version 6.9.0 or greater
• MongoDB version 2.6 or greater
• Nginx
• Git
• Minimum of 1024MB RAM
• Domain name with A/AAAA records set up

Before you begin

Check the FreeBSD version.

uname -ro
# FreeBSD 12.0-RELEASE

Ensure that your FreeBSD system is up to date.

freebsd-update fetch install
pkg update && pkg upgrade -y

Install necessary packages if they are not present on your system.

pkg install -y sudo vim unzip wget git bash socat gcc8 pkgconf vips

Create a new user account with your preferred username (we will use johndoe).

adduser

# Username: johndoe
# Full name: John Doe
# Uid (Leave empty for default): <Enter>
# Login group [johndoe]: <Enter>
# Login group is johndoe. Invite johndoe into other groups? []: wheel
# Login class [default]: <Enter>
# Shell (sh csh tcsh nologin) [sh]: bash
# Home directory [/home/johndoe]: <Enter>
# Home directory permissions (Leave empty for default): <Enter>
# Use password-based authentication? [yes]: <Enter>
# Use an empty password? (yes/no) [no]: <Enter>
# Use a random password? (yes/no) [no]: <Enter>
# Enter password: your_secure_password
# Enter password again: your_secure_password
# Lock out the account after creation? [no]: <Enter>
# OK? (yes/no): yes
# Add another user? (yes/no): no
# Goodbye!

Run the visudo command and uncomment the %wheel ALL=(ALL) ALL line, to allow members of the wheel group to execute any command.

visudo

# Uncomment by removing hash (#) sign
# %wheel ALL=(ALL) ALL

Now, switch to your newly created user with su.

su - johndoe

NOTE: Replace johndoe with your username.

Set up the timezone.

sudo tzsetup

Install Node.js

NodeBB is driven by Node.js, and so it needs to be installed. The installation of the current LTS version of Node.js is recommended.

Install Node.js and npm.

sudo pkg install -y node10 npm-node10

Check the versions.

node -v && npm -v
# v10.15.3
# 6.9.0

Install and configure MongoDB

MongoDB is the default database for NodeBB.

Install MongoDB.

sudo pkg install -y mongodb40

Check the version.

mongo --version | head -n 1 && mongod --version | head -n 1
# MongoDB shell version v4.0.6
# db version v4.0.6

Enable and start MongoDB.

sudo sysrc mongod_enable=yes
sudo service mongod start

Create a database and user for NodeBB.

Connect to MongoDB first.

mongo

Switch to the built-in admin database.

> use admin

Create an administrative user.

> db.createUser( { user: "admin", pwd: "<Enter a secure password>", roles: [ { role: "readWriteAnyDatabase", db: "admin" }, { role: "userAdminAnyDatabase", db: "admin" } ] } )

NOTE: Replace the placeholder <Enter a secure password> with your own selected password.

Add a new database called nodebb.

> use nodebb

The database will be created and context switched to nodebb. Next create the nodebb user with the appropriate privileges.

> db.createUser( { user: "nodebb", pwd: "<Enter a secure password>", roles: [ { role: "readWrite", db: "nodebb" }, { role: "clusterMonitor", db: "admin" } ] } )

NOTE: Again, replace the placeholder <Enter a secure password> with your own selected password.

Exit the Mongo shell.

> quit()

Restart MongoDB and ensure that the administrative user created earlier can connect.

sudo service mongod restart
mongo -u admin -p your_password --authenticationDatabase=admin

Install and configure Nginx

Install Nginx.

sudo pkg install -y nginx

Check the version.

nginx -v
# nginx version: nginx/1.14.2

Enable and start Nginx.

sudo sysrc nginx_enable=yes
sudo service nginx start

NodeBB by default runs on port 4567. To avoid typing http://example.com:4567, we will configure Nginx as a reverse proxy for the NodeBB application. Every request on port 80 or 443, if SSL is used, will be forwarded to port 4567.

Run sudo vim /usr/local/etc/nginx/nodebb.conf and populate it with the basic reverse proxy configuration below.

server {

  listen [::]:80;
  listen 80;

  server_name forum.example.com;

  root /usr/share/nginx/html;

  client_max_body_size 50M;

  location /.well-known/acme-challenge/ {
    allow all;
  }

  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_hide_header X-Powered-By;
    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";
  }

}

In the above config, update the server_name directive with your domain/hostname.

Save the file and exit with Colon+W+Q.

Now we need to include nodebb.conf in the main nginx.conf file.

Run sudo vim /usr/local/etc/nginx/nginx.conf and add the following line to the http {} block.

include nodebb.conf;

Check the configuration.

sudo nginx -t

Reload Nginx.

sudo service nginx reload

Install Acme.sh client and obtain a Let's Encrypt certificate (optional)

Securing your forum with HTTPS is not necessary, but it will secure your site's traffic. Acme.sh is a pure unix shell software for obtaining SSL certificates from Let's Encrypt with zero dependencies.

Download and install Acme.sh.

sudo mkdir /etc/letsencrypt
git clone https://github.com/Neilpang/acme.sh.git
cd acme.sh
sudo ./acme.sh --install --home /etc/letsencrypt --accountemail your_email@example.com
cd ~

Check the version.

/etc/letsencrypt/acme.sh --version
# v2.8.1

Obtain RSA and ECDSA certificates for forum.example.com.

# RSA 2048
sudo /etc/letsencrypt/acme.sh --issue --home /etc/letsencrypt -d forum.example.com --webroot /usr/share/nginx/html --reloadcmd "sudo service nginx reload" --keylength 2048
# ECDSA/ECC P-256
sudo /etc/letsencrypt/acme.sh --issue --home /etc/letsencrypt -d forum.example.com --webroot /usr/share/nginx/html --reloadcmd "sudo service nginx reload"  --keylength ec-256

After running the above commands, your certificates and keys will be in:

• RSA: /etc/letsencrypt/forum.example.com.
• ECC/ECDSA: /etc/letsencrypt/forum.example.com_ecc.

After obtaining certificates from Let's Encrypt, we need to configure Nginx to use them.

Run sudo vim /usr/local/etc/nginx/nodebb.conf again and configure Nginx as an HTTPS reverse proxy.

server {

  listen [::]:443 ssl http2;
  listen 443 ssl http2;
  listen [::]:80;
  listen 80;

  server_name forum.example.com;

  root /usr/share/nginx/html;

  client_max_body_size 50M;

  location /.well-known/acme-challenge/ {
    allow all;
  }

  # RSA
  ssl_certificate /etc/letsencrypt/forum.example.com/fullchain.cer;
  ssl_certificate_key /etc/letsencrypt/forum.example.com/forum.example.com.key;
  # ECDSA
  ssl_certificate /etc/letsencrypt/forum.example.com_ecc/fullchain.cer;
  ssl_certificate_key /etc/letsencrypt/forum.example.com_ecc/forum.example.com.key;

  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";
  }

}

Check the configuration.

sudo nginx -t

Reload Nginx.

sudo service nginx reload

Install NodeBB

Create a document root directory.

sudo mkdir -p /usr/local/www/nodebb

Change ownership of the /usr/local/www/nodebb directory to johndoe.

sudo chown -R johndoe:johndoe /usr/local/www/nodebb

Navigate to the document root folder.

cd /usr/local/www/nodebb

Clone the latest NodeBB into the document root folder.

git clone -b v1.11.x https://github.com/NodeBB/NodeBB.git .

Run the NodeBB setup command and answer each question when prompted.

./nodebb setup

After NodeBB setup is completed, run ./nodebb start to manually start your NodeBB server.

./nodebb start

After this command, you will be able to access your NodeBB forum instance in a web browser.

Run NodeBB with PM2

When started via ./nodebb start, NodeBB will not automatically start up again when the system reboots. To avoid that, we will need to setup NodeBB as a system service.

If running, stop NodeBB.

./nodebb stop

Install PM2 globally.

sudo npm install pm2 -g

Check the version.

pm2 -v
# 3.5.0

Navigate to the NodeBB document root.

cd /usr/local/www/nodebb

Start NodeBB via PM2.

pm2 start app.js

List the NodeBB process.

pm2 ls

Detect the available init system.

pm2 startup

Copy and paste the ouput of this command in the CLI to set up your startup hook.

Save your process list.

pm2 save

That's it. Your NodeBB instance is now up and running.