Operating System CentOS

How to Install NodeBB on AlmaLinux 9 or Rocky Linux 9 (CentOS 7 Replacement)

Set up a NodeBB 4 forum on AlmaLinux 9 or Rocky Linux 9 with Node.js 22, Redis, systemd and Nginx. CentOS 7 is end-of-life; this is the current procedure.

NodeBB is an open source forum platform that runs on Node.js. This guide installs the current NodeBB 4 branch on AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, with Redis as the data store, a systemd service that keeps the forum running across reboots, and Nginx as the reverse proxy in front of it.

Older tutorials on this topic targeted CentOS 7. CentOS 7 reached end of life in June 2024 and no longer receives security updates, and the Node.js release it could run is far too old for NodeBB today. AlmaLinux 9 and Rocky Linux 9 are the drop-in replacements, and the commands below are the same on all three RHEL 9 family systems.

Requirements

  • A server running AlmaLinux 9, Rocky Linux 9 or CentOS Stream 9, kept up to date (the Node.js 22 module stream arrived with the 9.5 minor release).
  • A user with sudo rights. The examples use deploy.
  • A DNS name that points at the server. The examples use forum.example.com.
  • Memory: the NodeBB documentation lists 512 MB of RAM as the minimum. Redis keeps the whole data set in memory, so plan for more as the forum grows.

NodeBB 4 requires Node.js 22 or newer (its package.json declares "node": ">=22"). It supports three data stores: MongoDB (the default in the installer), PostgreSQL and Redis. This guide uses Redis because it is available from the distribution's own repositories, as in the original CentOS 7 article.

Step 1: Update the system

sudo dnf -y update

Reboot if a new kernel was installed.

Step 2: Install Node.js 22, Git and Redis

RHEL 9 family systems ship several Node.js versions as module streams. Install the 22 stream, then Git and Redis:

sudo dnf module install -y nodejs:22
sudo dnf install -y git redis

Check the versions. node -v must report 22 or later:

node -v
npm -v

Start Redis and enable it at boot:

sudo systemctl enable --now redis

Confirm that it answers. The reply should be PONG:

redis-cli ping

Step 3: Create a user and download NodeBB

Do not run NodeBB as root. Create a dedicated system user whose home directory is /opt/nodebb:

sudo useradd --system --create-home --home-dir /opt/nodebb --shell /sbin/nologin nodebb

Clone the v4.x release branch as that user. Only the versioned branches are considered stable; master is the development branch.

sudo -u nodebb -H git clone -b v4.x https://github.com/NodeBB/NodeBB.git /opt/nodebb/app

Step 4: Run the NodeBB setup

The setup script installs the npm dependencies, asks a few questions and writes config.json:

sudo -u nodebb -H bash -c 'cd /opt/nodebb/app && ./nodebb setup'

Answer the prompts as follows. Press Enter to accept a default shown in brackets.

  • URL used to access this NodeBB: enter the address exactly as visitors will type it, for example http://forum.example.com (use https:// if you will add a certificate straight away).
  • NodeBB secret: accept the generated value.
  • Which database to use: type redis.
  • Host IP or address of your Redis instance: 127.0.0.1.
  • Host port of your Redis instance: 6379.
  • Password of your Redis database: leave empty unless you configured one.
  • Which database to use (0..n): 0.
  • Administrator username, email and password: choose your own. This is the account you sign in with afterwards.

Step 5: Run NodeBB as a systemd service

./nodebb start works, but a forum started that way does not come back after a reboot. The NodeBB documentation provides a systemd unit; the version below is that unit adjusted for this layout and for Redis instead of MongoDB.

sudo vi /etc/systemd/system/nodebb.service
[Unit]
Description=NodeBB
Documentation=https://docs.nodebb.org
After=system.slice multi-user.target redis.service

[Service]
Type=forking
User=nodebb

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

[Install]
WantedBy=multi-user.target

Load the unit, then start and enable it:

sudo systemctl daemon-reload
sudo systemctl enable --now nodebb

With --no-silent the forum logs to the journal. Check the service and test the local port (NodeBB listens on 4567 by default):

sudo systemctl status nodebb
curl -I http://127.0.0.1:4567

You should get an HTTP/1.1 200 OK response.

Step 6: Put Nginx in front of NodeBB

Install Nginx:

sudo dnf install -y nginx

Create a server block for the forum:

sudo vi /etc/nginx/conf.d/nodebb.conf
server {
    listen 80;

    server_name forum.example.com;

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

The Upgrade and Connection headers matter: NodeBB uses WebSockets, and without them the forum loads but keeps reconnecting.

SELinux is enforcing by default on these systems and stops Nginx from opening connections to a local port. Allow it, then test the configuration and start Nginx:

sudo setsebool -P httpd_can_network_connect 1
sudo nginx -t
sudo systemctl enable --now nginx

Step 7: Open the firewall

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Port 4567 does not need to be opened; only Nginx talks to it.

Step 8: Sign in

Open http://forum.example.com in a browser and sign in with the administrator account from step 4. The admin control panel is under /admin.

For a public forum, add a TLS certificate to the Nginx server block before you invite users. When the site moves to HTTPS, change the url value in /opt/nodebb/app/config.json to the https:// address and restart the service, otherwise WebSocket connections and links keep pointing at the old address:

sudo systemctl restart nodebb

Upgrading NodeBB

Back up first. With Redis the data lives in the dump file (on a typical install /var/lib/redis/dump.rdb); uploaded files are in public/uploads inside the NodeBB directory.

sudo systemctl stop nodebb
sudo cp /var/lib/redis/dump.rdb /root/nodebb-redis-backup.rdb
sudo tar -czf /root/nodebb-uploads.tar.gz -C /opt/nodebb/app/public uploads

Then fetch the latest code on the same release branch, run the upgrade script and start the forum again:

sudo -u nodebb -H bash -c 'cd /opt/nodebb/app && git fetch && git reset --hard origin/v4.x && ./nodebb upgrade'
sudo systemctl start nodebb

The upgrade script installs missing dependencies, updates plugins and themes and migrates the database when needed. See the NodeBB upgrade documentation before moving between major branches.

Troubleshooting

  • 502 Bad Gateway from Nginx: check that the service is running with sudo systemctl status nodebb, and that the SELinux boolean from step 6 is set (getsebool httpd_can_network_connect).
  • The forum loads but shows a connection-lost message: the url in config.json does not match the address in the browser, or the WebSocket headers are missing from the Nginx block.
  • Setup stops with a Node.js version error: run node -v. If it is below 22, switch streams with sudo dnf module reset nodejs followed by sudo dnf module install nodejs:22.
  • Logs: sudo journalctl -u nodebb -f.

Frequently asked questions

Should I use Redis, MongoDB or PostgreSQL?

All three are supported. MongoDB is the installer's default and what the official Ubuntu guide uses. Redis is fast because it holds everything in memory, but the NodeBB documentation warns that the server then needs roughly twice as much RAM as the data set, since Redis copies its data while saving to disk. For a small forum Redis is fine; for a large one, MongoDB or PostgreSQL is easier on memory.

Can I still install NodeBB on CentOS 7?

Not sensibly. CentOS 7 is end-of-life and current NodeBB needs Node.js 22 or newer. Move the forum to AlmaLinux 9 or Rocky Linux 9: back up the database and the public/uploads directory, install as above, and restore the data before starting the service.

Is the forever tool still needed to keep NodeBB running?

No. The systemd unit restarts NodeBB if it crashes and starts it at boot. The NodeBB documentation also notes that the restart and rebuild buttons in the admin panel do not work when the forum is run through forever.

How do I use a different port than 4567?

Add a "port" entry to config.json, restart the service and change the proxy_pass line in the Nginx server block to match.

Share story:

Continue reading other guides on How VPS.