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.
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.
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
Note that we don't use the default path for our Discourse installation (
/var/discourse), so we're being rebels here. Doing an
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:
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.yml
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
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
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!
Add new comment