docs

docs copied to clipboard

I can only quote the original issue from the mattermost-server repository, because @robert-scheck spelled out the problem meticulously already. I'll add a few additions below that quote.

It might, in general, be wise to remove all references to a specific PostgreSQL version and replace them by a link referencing a general "Supported PostgreSQL versions" page. This would prevent the need to modify all those install guides if anything changes in the PostgreSQL support regime.

As of writing, https://docs.mattermost.com/administration/important-upgrade-notes.html is unfortunately ambiguous about the supported PostgreSQL versions: It currently says that PostgreSQL 10 is supported for the latest Mattermost version, while it also says that PostgreSQL 10+ is required for new installations. Given there is already PostgreSQL 12, this unfortunately leaves open whether Mattermost supports PostgreSQL 12 or just 10.x. So does the "+" actually mean 10.x-only or really 10/11/12/...? This should never be left for guessing to the administrator, but always be clearly documented.

Expected behavior

Clear, non-ambiguous documentation of supported PostgreSQL versions, as e.g. Red Hat Enterprise Linux 8 and CentOS 8 are only shipping PostgreSQL 12.x (rather than ancient PostgreSQL versions).

Possible fixes

Please note that I do not know which versions of PostgreSQL are actually really supported by Mattermost, so the following are just textual suggestions for the documentation to improve the situation, while the actual versions needs to be inserted properly indeed.

• "New installs will require PostgreSQL 10.x, but PostgreSQL 11 (or later) is not yet supported."
• "New installs will require PostgreSQL 10 (or later), but PostgreSQL 14 (or later) is not yet supported."

At least the following pages need to be fixed regarding PostgreSQL:

• https://docs.mattermost.com/install/software-hardware-requirements.html
• https://docs.mattermost.com/install/installing-ubuntu-2004-LTS.html#install-postgresql-database-server
• https://docs.mattermost.com/install/install-debian.html#install-and-configure-the-components-in-the-following-order-note-that-you-need-only-one-database-either-mysql-or-postgresql (speaks of PostgreSQL 9.4 in code blocks)
• https://docs.mattermost.com/install/install-rhel-8.html#installing-postgresql-database
• https://docs.mattermost.com/install/installing-ubuntu-1804-LTS.html#install-postgresql-database-server
• https://docs.mattermost.com/install/install-rhel-7.html#install-postgresql-database

Cheers Thomas

As needed, the Server Platform can likely help support this documentation effort.

Thank you, @TwizzyDizzy, for your thoughtful and clear documentation feedback. I agree that PostgreSQL support needs work and I appreciate your suggestions.

I'm not sure how #5805 addresses the main concern. The merge request talks about "PostgreSQL v12+". But that still leaves open again whether this actually means PostgreSQL v12, v13, v14 or just PostgreSQL v12.1, v12.2, v12.3 etc.

Thank you for your feedback, @robert-scheck. You're making a very reasonable point about documentation granularity that's currently lacking in the Mattermost Product Documentation.

We're in the process of updating installation documentation to provide clearer guidance around minimum versus supported system requirements, and are taking this input into account as part of this effort.

CC @nab-77