Upgrading a Docker-based Discourse Forum instance

Discourse is the world-leading online web-based forum. It's a superb, extremely mature-and-yet-cutting edge platform. It also happens to be Free and Open Source Software, which is why we, at the OER Foundation, use it.

Like all good software, it's undergoing continuous improvement by its developer community who release fairly frequent - perhaps every couple weeks - updates. Luckily, keeping your Discourse forum up-to-date isn't particularly onerous.

Upgrading a Discourse instance deployed via Docker (as all of ours are) follows one of two possible workflows. Both usually start with either a Discourse administrator logging into the Discourse site (which she/he might not do very often) and noticing on the default admin dashboard page (see the first attached screenshot) that there is a pending upgrade, usually with a 'click here to upgrade' link. Alternatively, if an administrator is not logged in (the system is aware of this) the system sends administrators for the site an email (see the second attached screenshot for a sample) alerting them all that an upgrade is pending, with a link to the upgrade page in the Discourse administration system.

Always backup first!

As any good system administrator knows, their users' data is of utmost importance. So, before proceeding with any upgrade, it's crucial to make a backup of your system to ensure that if everything goes pear-shaped, you can recover and get back to where you were.

Normally, I consider it sufficient to take a Discourse 'backup' via the admin backup interface 'immediately before doing the upgrade' (see attached screenshot), leaving ''off'' the uploaded content, as this is unlikely to be affected or removed via the upgrade process, to save space. Doing this immediately prior to the upgrade minimises the chances that any users lose data (e.g. a recent post, in the space of time between the backup and the actual upgrade or even a post they're working on when the upgrade commences - if the latter happens, as long as they don't leave the page and wait for the forum to 'come back' after the upgrade, they should be able to proceed without losing anything... but there's a small chance they could be unlucky - be mindful of this and try to a) announce upgrades on the site prior to running them, and b) try to do so outside of your busiest hours, which should be easy to determine thanks to Discourse's superb analytics (also a feature of the default admin dashboard).

After conducting the backup, you can do the upgrade.

Upgrade Workflows

You will ''usually'' have a straightforward 'point-and-click' web browser based upgrade process, but on occasion, you will click on the 'upgrade link' and end up on a page like 'upgrade is too complicated for the web interface' message (see attached screenshot). In that latter case, things get a little more complicated. Also, such upgrades can result in somewhat more downtime for the forum, so only conduct them when you have sufficient time.

Web-based upgrade

In most cases, when you click on the "Click here to upgrade" link, you'll be taken to a page that assesses the various components (the Discourse codebase, the Docker subsystems, and any additional functional plugins) making up your Discourse install and alerts you which of those components have a pending upgrade. This can sometimes take a while (the system is having to compare what you have on your server to the official up-to-date versions of those things on the web), but when done, the page will show you 'upgrade' buttons for the components with upgrades pending as per the attached sample upgrade pages screenshot.

Once you've got those showing, you can click the 'Upgrade' button that's highlighted (if any - that one needs to be done first, prior to the others) and then the 'Start upgrade" operation for each one. Or, sometimes, you'll see an "Upgrade all" button at the top of the page, which applies all the pending upgrades in a single operation.

Usually, in practice, this renders your Discourse forum unusable (it'll be in 'maintenance mode' from a user's perspective) for a few seconds to a few minutes, depending on the upgrade.

Command line 'launcher' upgrade

When the upgrade is more fundamental, usually involving the Docker subsystem, you sometimes don't have the option of a web-based upgrade. Instead of the upgrade web pages from the previous section, you get message like that shown in the next screenshot, which talks about running the upgrade from the command line using the launcher command and doing a 'rebuild' of the system.

In that case, you need to be able to log into the host server (usually a remote cloud-based "Virtual Private Server" or VPS) - I always use SSH to do that see these instructions from a terminal on my Linux desktop - with suitable permissions (usually the ability to run 'sudo' commands, i.e. act as the administrative or 'root' user of that server).

Once you're logged in as a user with 'sudo' privileges, you need to go to the Docker configuration directory for that instance of Discourse - in the OER Foundation's case, I have the convention of having the installation in the /home/docker/ directory in a subdirectory with the same name as the as the site, e.g. forum.oeru.org. In that case, I'd enter

cd /home/docker/forum.oeru.org

Note that we don't use the default path for our Discourse installation (/var/discourse), so we're being rebels here. Doing an

ls -l

here should give a directory that looks a bit like this (you might not have the 'oeru'-related files) when listed:

-rw-rw-r-- 1 dave dave  1099 Nov 29  2019 LICENSE
-rw-r--r-- 1 dave root  8285 Jul 24  2021 README.md
-rw-rw-r-- 1 dave dave   258 Dec  2  2019 README.oeru
drwxrwxr-x 1 dave dave    16 Nov 29  2019 bin
drwxrwxr-x 1 dave dave    16 Apr 15 23:36 cids
drwxrwxr-x 1 dave dave    30 May 19 06:47 containers
-rwxrwxr-x 1 dave dave 11955 Apr 15 23:22 discourse-doctor
-rwxr-xr-x 1 dave root 27132 Oct 21  2021 discourse-setup
drwxrwxr-x 1 dave dave   192 Dec 22 04:43 image
-rwxrwxr-x 1 dave dave 23538 Apr 15 23:22 launcher
drwxrwxr-x 1 dave dave   120 Nov 16  2021 samples
drwxrwxr-x 1 dave dave    22 Nov 29  2019 scripts
drwxrwxr-x 1 dave dave    16 Nov 29  2019 shared
drwxrwxr-x 1 dave dave   866 Apr 15 23:22 templates
drwxr-xr-x 1 dave root   130 Jan 16 22:42 tests

The script we're going to use is the launcher script, and we're going to use the site's configuration which, by our convention, will reside in containers/app.yml(you can see its contents by typing less containers/app.yml assuming your user has sufficient permissions to view it directly. If not, prepend sudo to your command.

To run the upgrade, you have to complete two steps as suggested by the page you saw when you clicked on the upgrade link:

First, ensure that the 'git' repository that was used to provide this set of files to begin with is up-to-date - if your user owns these files (as my 'dave' user does in the example above) then run this to avoid changing the ownership of the files:

git pull

If you don't own the files you'll need to run

sudo git pull

which should result in a fairly quick (a few seconds) request to the git server, pulling down files that have been changed by the developers since the last time you did a git pull... Note, if the pull fails, you may find that you've altered one or more files for some reason and that the change you've made would be clobbered by the pull. The easiest thing to do in that case is - for each file - to (prepending with sudo if required):

cp [filename] [filename].bak

so you have a backup copy of your changed file, and then issue (again, with sudo prepended if necessary):

git checkout [filename]

which reverts [filename] to its original git-distributed version. The git pull should now work.

Second, simply type (again, prepending with sudo if required:

./launcher rebuild app

This will initiate what can be a rather long process (perhaps 1 to as many as, say, 30 minutes, depending on the upgrade, the amount that needs to be downloaded, your server's network bandwidth, and a variety of other variables) which will involve downloading new Docker containers with Discourse code, as well as possibly a new PostgreSQL database container among others. Your Discourse will continue running as long as it can safely do so, but then the launcher script will shut down the containers and restart them. It might also be 'recompiling' aggregated resources used by Discourse, like various Ruby On Rails gems, icon files, style sheets (CSS), or Javascript files...

Once it's done, you'll get the command prompt back. You're done! Have a look at your site and you should see you're up-to-date!

You can log out of the server vai CTRL-D or typing exit.

Problems?

I have, on a few occasions, had an upgrade fail for some reason. If that happens, you should see an indicator of has caused the failure (in a few cases for me, it was the fact that the PostgreSQL database didn't have enough time to restart before the Discourse app tried to access it to run data schema upgrades, and failed as a result. Changing the 'timeout' value from 5 seconds to 60 seconds fixed it - looking on the Meta Discourse - Discourse's own Discourse used to discuss running Discourse - is a very good resource when trying to solve system-related problems. It's worth creating an account for yourself on it if you're going to be responsible for a Discourse instance!