Upgrading NodeBB

NodeBB's periodic releases are located in the
Releases. These releases
contain what is usually considered the most bug-free code, and is
designed to be used on production-level instances of NodeBB.

You can utilise git to install a specific version of NodeBB, and upgrade
periodically as new releases are made.

To obtain the latest fixes and features, you can also git clone the
latest version directly from the repository (master branch), although
its stability cannot be guaranteed. Core developers will attempt to
ensure that every commit results in a working client, even if individual
features may not be 100% complete.

As always, the NodeBB team is not responsible for any
misadventures, loss of data, data corruption, or any other bad things
that may arise due to a botched upgrade - so please don't forget to
back up before beginning!

Upgrade Path

NodeBB's upgrade path is designed so that upgrading between versions is
straightforward. NodeBB will provide upgrade compatibility (via the
--upgrade flag) between the latest version of a lower branch and the
latest version of the higher branch. For example, if v0.2.2 is the
latest version in the v0.2.x branch, you can switch to the v0.3.x
branch and suffer no ill effects. Upgrading from v0.2.0 to v0.3.x is
not supported, and NodeBB will warn you when attempting to upgrade that
you are not upgrading cleanly.

Upgrading between patch revisions

e.g. v0.1.0 to v0.1.1

Patch revisions contain bugfixes and other minor changes. Updating to
the latest version of code for your specific version branch is all that
is usually required.

Execute steps 1 through 3.

Upgrading between minor revisions

e.g. v0.1.3 to v0.2.0

Minor revisions contain new features or substantial changes that are
still backwards compatible. They may also contain dependent packages
that require upgrading, and other features may be deprecated (but would
ideally still be supported).

Execute steps 1 through 4.

Upgrade Steps

Note: After upgrading between revisions (i.e. v0.0.4 to v0.0.5), it
may be necessary to run the following upgrade steps to ensure that any
data schema changes are properly upgraded as well:

1. Shut down your forum

While it is possible to upgrade NodeBB while it is running, it is
definitely not recommended, particularly if it is an active forum:

$ cd /path/to/nodebb
$ ./nodebb stop

2. Back up your data

note

This section is incomplete, please take care to back up your files
properly!

Backing up Redis

As with all upgrades, the first step is to back up your data! Nobody
likes database corruption/misplacement.

All of the textual data stored in NodeBB is found in a .rdb file. On
typical installs of Redis, the main database is found at
/var/lib/redis/dump.rdb.

Store this file somewhere safe.

Backing up MongoDB

To run a backup of your complete MongoDB you can simply run

mongodump

which will create a directory structure that can be restored with the
mongorestore command.

It is recommended that you first shut down your database. On Debian /
Ubuntu it's likely to be: sudo service mongodb stop

Store this file somewhere safe.

Avatars

Uploaded images (avatars) are stored in /public/uploads. Feel free to
back up this folder too:

cd /path/to/nodebb/public
tar -czf ~/nodebb_assets.tar.gz ./uploads

3. Grab the latest and greatest code

Navigate to your NodeBB: $ cd /path/to/nodebb.

If you are upgrading from a lower branch to a higher branch, switch
branches as necessary. Make sure you are completely up-to-date on
your current branch!.