diff --git a/source/guides/upgrade-mattermost.rst b/source/guides/upgrade-mattermost.rst index 9bb388cb10a..c70c67a5c49 100644 --- a/source/guides/upgrade-mattermost.rst +++ b/source/guides/upgrade-mattermost.rst @@ -11,6 +11,7 @@ Upgrade Mattermost Important upgrade notes Prepare to upgrade Mattermost + Communicate scheduled maintenance Upgrade Mattermost Server Enterprise install and upgrade Install a license key @@ -19,6 +20,7 @@ Upgrade Mattermost Stay up to date with the latest features and improvements. * :doc:`Prepare to upgrade Mattermost ` - Learn how to prepare for a Mattermost upgrade. +* :doc:`Communicate scheduled mainenance ` - Learn best practices for communicating scheduled server mainenance in advance of a service maintenance window. * :doc:`Upgrade Mattermost Server ` - Learn the basics of upgrading your Mattermost server to the latest version. * :doc:`Enterprise install and upgrade ` - Learn how to upgrade your Mattermost server to premium versions. * :doc:`Install a license key ` - Learn how to add or change a Mattermost license key. diff --git a/source/upgrade/communicate-scheduled-maintenance.rst b/source/upgrade/communicate-scheduled-maintenance.rst new file mode 100644 index 00000000000..871411964d2 --- /dev/null +++ b/source/upgrade/communicate-scheduled-maintenance.rst @@ -0,0 +1,188 @@ +Communicate scheduled maintenance +================================== + +.. include:: ../_static/badges/allplans-cloud-selfhosted.rst + :start-after: :nosearch: + +Performing scheduled maintenance on a Mattermost server with 1,000 or more users requires advanced planning and a clear communication strategy to ensure minimal disruption and maximum transparency. + +This guide provides best practices for notifying users via email and Mattermost channels, updating the load balancer’s error message, and configuring a dismissable banner to inform users of the upcoming maintenance. + +Communication strategy +---------------------- + +A well-defined communication strategy is essential for informing users before, during, and after maintenance. The key components of this strategy are: + +- `Email notifications <#email-templates>`__: Send structured and consistent emails to users at intervals of 7 days, 3 days, and 1 day before the scheduled maintenance window. +- `Channel-based reminders <#channel-reminder-templates>`__: :doc:`Send messages ` similar to the emails in relevant Mattermost channels at the same intervals as the email notifications. +- `Mattermost Banner notification <#banner-notification>`__: Set a :doc:`system-wide notification ` to display at the top of the Mattermost instance ahead of the maintenance window and outage. +- `Display a load balancer message <#display-load-balancer-message>`__: Update the load balancer to show a maintenance message during the scheduled maintenance window of downtime. + +Notification templates +---------------------- + +Email Templates +~~~~~~~~~~~~~~~ + +7-Day notice email +^^^^^^^^^^^^^^^^^^ + +**Email subject**: Scheduled Maintenance Notification: [Date and Time] + +.. code-block:: none + + Dear Mattermost Users, + + This is a notification that our Mattermost server will undergo scheduled + maintenance on [Date] from [Start Time] to [End Time] [Time Zone]. + During this time, the Mattermost instance will be unavailable. + + We apologize for any inconvenience this may cause and appreciate your + understanding as we work to improve our service. + + If you have any questions or concerns, please contact our + support team at [Support Email]. + + Thank you for your cooperation. + + Best regards, + [Your Name] + [Your Position] + +3-Day notice email +^^^^^^^^^^^^^^^^^^ + +**Email subject**: Reminder: Scheduled Maintenance on [Date and Time] + +.. code-block:: none + + Dear Mattermost Users, + + This is a reminder that our Mattermost server will undergo scheduled + maintenance on [Date] from [Start Time] to [End Time] [Time Zone]. + The Mattermost instance will be unavailable during this period. + + If you have any questions or concerns, please contact our + support team at [Support Email]. + + Thank you for your cooperation. + + Best regards, + [Your Name] + [Your Position] + +1-Day notice email +^^^^^^^^^^^^^^^^^^ + +**Email subject**: Final Reminder: Scheduled Maintenance Tomorrow on [Date and Time] + +.. code-block:: none + + Dear Mattermost Users, + + This is a final reminder that our Mattermost server will undergo scheduled + maintenance tomorrow, [Date], from [Start Time] to [End Time] [Time Zone]. + The Mattermost instance will be unavailable during this period. + + If you have any questions or concerns, please contact our + support team at [Support Email]. + + Thank you for your cooperation. + + Best regards, + [Your Name] + [Your Position] + +Channel reminder templates +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +7-Day channel reminder +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + @all Please be advised that our Mattermost server will + undergo scheduled maintenance on [Date], + from [Start Time] to [End Time] [Time Zone]. + The instance will be unavailable during this time. We appreciate your understanding. + +3-Day channel reminder +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + @all This is a reminder that our Mattermost server will + undergo scheduled maintenance on [Date], + from [Start Time] to [End Time] [Time Zone]. + Please plan accordingly. + +1-Day channel reminder +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + @all Final reminder: Our Mattermost server will + undergo scheduled maintenance tomorrow, [Date], + from [Start Time] to [End Time] [Time Zone]. + Thank you for your cooperation. + +Banner notification +~~~~~~~~~~~~~~~~~~~ + +Sample message: + +.. code-block:: text + + Heads up! Scheduled maintenance is planned for [Date], + between [Start Time] and [End Time] [Time Zone]. + The Mattermost instance will be unavailable during this time. + +Users can dismiss the banner until they log in again, or until you update the banner. + +Display load balancer message +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Configure the load balancer to display a notification message during the scheduled maintenance window of downtime. + +1. Identify the load balancer you are using (e.g., AWS, HAProxy). +2. Edit configuration. Adjust paths and configurations according to your specific environment. + + - For AWS, navigate to the Load Balancer configurations in the EC2 console. + - For HAProxy, edit the ``haproxy.cfg`` file. + +See the sample message HTML below to use as a starting point: + +.. code-block:: html + + HTML Template + + + + Maintenance in Progress + + + +
+

Maintenance in Progress

+

Our Mattermost server is currently undergoing scheduled maintenance.

+

Estimated downtime: [Start Time] to [End Time] [Time Zone]

+

We apologize for any inconvenience and thank you for your understanding.

+

If you have any questions, please contact our support team at [Support Email].

+
+ + \ No newline at end of file