Files
team/docs/main/administration-guide/upgrade/enterprise-roll-out-checklist.mdx
b5f007d35e docs: fix broken path links, anchors, and tab rendering from RST-to-MDX migration (#37433)
* docs: resolve cross-file anchor mismatches from RST-to-MDX migration

The Sphinx-to-Docusaurus migration converted `:ref:`/`{ref}` links using
naive text-slugification, so anchors that pointed to headings in a
different file (e.g. release-summary tables linking into their
respective changelog pages) were emitted as same-page fragments and
silently resolved to nothing.

Built a label registry from the original Sphinx `.. _label:` / `(label)=`
targets to recover the true source file for each cross-reference, then
rewrote the affected links to point at the correct file + heading
anchor. Fixes 282 broken cross-file anchors, primarily in the mobile/
desktop/server release-summary pages, plus assorted same-page anchor
mismatches caught by re-auditing after the prior admonition/anchor fix.

* docs: manually resolve remaining anchor mismatches after cross-file audit

Hand-verified fixes for anchors that fuzzy-matching alone couldn't
safely resolve (confirmed against actual heading text/context, and in a
few cases against the original RST source, before applying):

- Typos and dropped words carried over from the original Sphinx docs
  (e.g. "bot-acocunts", "auto-follow-all-new-channel-threads" ->
  "follow-all-new-channel-threads").
- Sphinx auto-generated duplicate-heading IDs (#id1/#id3/#id4) resolved
  to their real target headings.
- Numbered-step TOC links in enterprise-roll-out-checklist.mdx that
  dropped the leading "N. " used in the actual heading slugs.
- Push-notification docs pointing at the wrong file entirely
  (environment-configuration-settings instead of
  push-notification-server-configuration-settings).
- SAML "saml-enterprise" label resolved to its true cross-file target
  (authentication-configuration-settings#saml-2-0), recovered from the
  original RST label definition that the automated registry missed
  because it sat after an RST transition marker.
- sso-saml-technical references converted from broken same-page/
  malformed-path anchors to correct page links.

* docs: fix SAML 2.0 anchor slug (saml-2-0 -> saml-20)

github-slugger strips periods rather than hyphenating them, so "SAML
2.0" slugifies to saml-20, not saml-2-0 as previously fixed.

* docs: fix broken path links found during docs/main migration cleanup

* docs: convert div.tab blocks to Docusaurus Tabs/TabItem components

* docs: restore missing Kubernetes deployment architecture diagrams

The RST-to-MDX migration never copied over the AWS/Azure/Oracle
architecture diagrams referenced by the deployment-architecture-at-scale
page, leaving broken images in each Tabs/TabItem.

* docs: fix 7 anchor mismatches from the fragment/heading audit

Covers three root causes from the anchor mismatch breakdown:
- Fragment repeated the target page's own title instead of a real
  heading, so the link is simplified to point at the bare page.
- Heading exists verbatim but lives on a sibling settings page
  (experimental-configuration-settings, push-notification-server-
  configuration-settings) rather than environment-configuration-settings.
- A page path was mistakenly pasted into a same-page #fragment instead
  of being used as a real cross-page link.

* docs: fix 8 anchor slugs that were close but didn't match the real heading

Repoints links whose fragment was a plausible guess (typo, reworded
heading, or wrong section) at the actual auto-generated slug of the
target heading, confirmed by inspecting each target page directly.

* docs: merge split Tabs blocks so tabs render horizontally

The div.tab conversion script split some sibling tab groups into
separate single-item Tabs blocks whenever a stray blockquote marker
sat between them, causing them to render stacked instead of as one
horizontal tab bar. Merges the MySQL/PostgreSQL and Team/Enterprise
Edition tab groups back into single Tabs blocks.

* docs: remove Azure tab and restore Kubernetes deploy content

The Mattermost Operator, Azure, and Oracle platform tabs on the
Kubernetes deployment guide were split across two separate Tabs
blocks (rendering stacked instead of as one tab bar) and all three
tab bodies were empty because the migration never flattened the
original RST include directives. Removes the unsupported Azure tab
and restores the Mattermost Operator and Oracle content from the
pre-migration RST sources as a single merged Tabs block.

* addresscoderabbitreview

* docs: unify Linux/Kubernetes/Containers deploy pages and fix FIPS/STIG placement

Kubernetes and Containers duplicated full install content across a top-level
page (Tabs) and orphaned sidebar subpages that nothing linked to. Reworked
both to follow the Linux page's pattern: shared content on the landing page,
platform-specific instructions live once in their own subpage.

Also removed configure-fips-at-install-time.mdx, which claimed FIPS is
available for native Linux installs — FIPS/STIG in Mattermost is a container
image property (Chainguard-based build), not available outside Docker/
Kubernetes. Consolidated all FIPS/STIG references onto
containers/fips-stig.mdx and pointed the Mattermost Operator subpage (not
Oracle OKE, which doesn't expose image selection) at it.

* docs: fix review findings — image alt text, Important callout markup, typo

- Replace generic alt="image" on scaling diagrams with descriptive text
  identifying cloud provider and user scale.
- Convert raw div.important markup in deploy-containers.mdx to the
  repo's <Important> component, matching usage elsewhere in the file.
- Fix "Matermost" typo in manage-your-display-options.mdx.

---------

Co-authored-by: Hanzo Dev <[email protected]>
2026-07-10 14:50:13 +03:00

372 lines
20 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "Enterprise roll out checklist"
---
<PlanAvailability slug="ent-plus" />
This checklist is intended to serve as a guide to Enterprises who are rolling out Mattermost to thousands of users.
## Checklist overview
### Prepare for the roll out
- [1. Define the roll out project](#1-define-the-roll-out-project)
- [2. Validate essential security and compliance requirements](#2-validate-essential-security-and-compliance-requirements)
- [3. Create development, staging, and production environments](#3-create-development-staging-and-production-environments)
- [4. Configure and customize your Mattermost site](#4-configure-and-customize-your-mattermost-site)
- [5. Test production performance and redundancy](#5-test-production-performance-and-redundancy)
### Roll out Mattermost
- [1. Define your team and channel strategy](#1-define-your-team-and-channel-strategy)
- [2. Enable key integrations](#2-enable-key-integrations)
- [3. Prepare for user onboarding](#3-prepare-for-user-onboarding)
- [4. Deploy client apps](#4-deploy-client-apps)
- [5. Roll out to groups of users](#5-roll-out-to-groups-of-users)
- [6. Drive adoption](#6-drive-adoption)
### Review the roll out
- [1. Review project charter success metrics](#1-review-project-charter-success-metrics)
- [2. Review and analyze usage](#2-review-and-analyze-usage)
- [3. Analyze system performance](#3-analyze-system-performance)
- [4. Harden security](#4-harden-security)
- [5. Perform maintenance tasks](#5-perform-maintenance-tasks)
## Checklist details
### Prepare for the roll out
Much of the preparation work is focused on ensuring the environment is deployed and secured prior to onboarding users.
#### 1. Define the roll out project
- Define key stakeholders and project team members
> - Example project team members: Project Manager, Network Administrator, Database Administrator, Corporate Directory Administrator, Security & Compliance Administrator(s), User Support, User Champions, User Trainers
- Define use cases and requirements for teams, their workflows and their integrations
> - Resource: [https://mattermost.com/blog/27-things-enterprises-can-learn-startups-increase-productivity/](https://mattermost.com/blog/27-things-enterprises-can-learn-startups-increase-productivity/)
- Define success criteria, goals and metrics to measure success
- Create a Project Charter to document goals, tasks, deliverables, and decisions
> - Get buy-in from project team members and key stakeholders on the project charter
#### 2. Validate essential security and compliance requirements
- Review Mattermost security features
> - Resource: [https://docs.mattermost.com/security-guide/security-guide-index.html](https://docs.mattermost.com/security-guide/security-guide-index.html)
- Determine monitoring requirements
> - Database, network, storage, log integrity
> - Identify fields for log management tools (e.g. Splunk Enterprise event data)
- Determine environment access policies
> - Network access, physical access, group controlled access
- Determine encryption policies
> - Resource: [https://docs.mattermost.com/deployment-guide/encryption-options.html](https://docs.mattermost.com/deployment-guide/encryption-options.html)
> - Resource: [https://docs.mattermost.com/deployment-guide/transport-encryption.html](https://docs.mattermost.com/deployment-guide/transport-encryption.html)
- Determine system administration access policies
> - Identify the list of users or groups who need administrative access for Mattermost System Console, Command Line Tools, and API privileges
- Define and configure authentication policies
> - Resource: [https://docs.mattermost.com/product-overview/corporate-directory-integration.html](https://docs.mattermost.com/product-overview/corporate-directory-integration.html)
- Determine requirements for multi-factor authentication
> - Resource: [https://docs.mattermost.com/administration-guide/onboard/multi-factor-authentication.html](https://docs.mattermost.com/administration-guide/onboard/multi-factor-authentication.html)
- Configure and test SSO or Corporate Directory integration (SAML or AD/LDAP)
> - Resource: [https://docs.mattermost.com/administration-guide/onboard/sso-saml.html](https://docs.mattermost.com/administration-guide/onboard/sso-saml.html)
> - Resource: [https://docs.mattermost.com/administration-guide/onboard/ad-ldap.html](https://docs.mattermost.com/administration-guide/onboard/ad-ldap.html)
- Define your mobile usage policy
> - Resource: [https://docs.mattermost.com/deployment-guide/mobile/mobile-app-deployment.html](https://docs.mattermost.com/deployment-guide/mobile/mobile-app-deployment.html)
- Evaluate external network access requirements
> - The [Mattermost Marketplace](https://mattermost.com/marketplace) is a service hosted by Mattermost that functions as a central place to store the current versions of available Mattermost integrations. See [Enable Remote Marketplace](/administration-guide/configure/plugins-configuration-settings#enable-remote-marketplace) documentation for details about required external network access.
> - Mattermost supports external GIF providers. See [GIF Commands](/administration-guide/configure/integrations-configuration-settings#enable-gif-picker) configuration documentation for details about required external network access.
#### 3. Create development, staging, and production environments
- Finalize production environment design basing hardware on expected usage and requirements for high availability
> - Resource: [https://docs.mattermost.com/deployment-guide/reference-architecture/application-architecture.html](https://docs.mattermost.com/deployment-guide/reference-architecture/application-architecture.html)
> - Resource: [https://docs.mattermost.com/deployment-guide/deployment-guide-index.html](https://docs.mattermost.com/deployment-guide/deployment-guide-index.html)
> - Resource: [https://docs.mattermost.com/administration-guide/scale/scaling-for-enterprise.html](https://docs.mattermost.com/administration-guide/scale/scaling-for-enterprise.html)
> - Resource: [https://docs.mattermost.com/administration-guide/scale/high-availability-cluster-based-deployment.html](https://docs.mattermost.com/administration-guide/scale/high-availability-cluster-based-deployment.html)
- Create development and staging environments
> - Recommend using to test early configurations for database, authentication, file storage, Elasticsearch, prior to setting up high availability and load balancing
> - Recommend configuring staging to be an identical replication of your production environment
- Create a production environment
> - Install Mattermost
>
> > - Install the number of nodes based on your high availability requirements outlined in your production environment design
> > - Recommendation: Use Kubernetes and the Mattermost Operator, with external supported external database and file storage solutions. This will also provide blue/green deployment, rolling upgrades, and canary builds
> >
> > > - Resource: [https://docs.mattermost.com/deployment-guide/server/deploy-kubernetes.html](https://docs.mattermost.com/deployment-guide/server/deploy-kubernetes.html)
>
> - Install and configure database
>
> > - Install the number of read and search replicas based on your high availability requirements outlined in your production environment design
> >
> > > - Resource: [https://docs.mattermost.com/deployment-guide/reference-architecture/application-architecture.html](https://docs.mattermost.com/deployment-guide/reference-architecture/application-architecture.html)
> >
> > - (Optional) Set up configuration management via the database instead of a config file for high available environments
> >
> > > - Resource: [https://docs.mattermost.com/administration-guide/configure/configuration-in-your-database.html](https://docs.mattermost.com/administration-guide/configure/configuration-in-your-database.html)
>
> - Install and configure File Storage
>
> > - Resource: [https://docs.mattermost.com/deployment-guide/server/preparations.html#file-storage-preparation](https://docs.mattermost.com/deployment-guide/server/preparations.html#file-storage-preparation)
>
> - Install and configure proxy or load balancers
>
> > - Note: If running Kubernetes and the Mattermost Operator, proxies will be created automatically.
> > - Add SSL Cert
> >
> > > - Resource: [https://docs.mattermost.com/administration-guide/onboard/ssl-client-certificate.html](https://docs.mattermost.com/administration-guide/onboard/ssl-client-certificate.html)
> > > - Resource: [https://docs.mattermost.com/administration-guide/scale/high-availability-cluster-based-deployment.html#proxy-server-configuration](https://docs.mattermost.com/administration-guide/scale/high-availability-cluster-based-deployment.html#proxy-server-configuration)
> >
> > - (Optional) Set up certificate-based authentication (CBA) for user or device-based authentication with a digital certificate
> >
> > > - Resource: [https://docs.mattermost.com/administration-guide/onboard/certificate-based-authentication.html](https://docs.mattermost.com/administration-guide/onboard/certificate-based-authentication.html)
>
> - Configure SMTP for email notifications
>
> > - Resource: [https://docs.mattermost.com/administration-guide/configure/smtp-email.html](https://docs.mattermost.com/administration-guide/configure/smtp-email.html)
>
> - Set up Elasticsearch (highly recommended if your organization anticipates over two million posts)
>
> > - Resource: [https://docs.mattermost.com/administration-guide/scale/elasticsearch-setup.html](https://docs.mattermost.com/administration-guide/scale/elasticsearch-setup.html)
- Document network configuration
> - Example: [https://docs.mattermost.com/administration-guide/scale/backing-storage-benchmarks.html](https://docs.mattermost.com/administration-guide/scale/backing-storage-benchmarks.html)
#### 4. Configure and customize your Mattermost site
- Login to Mattermost and access the System Console to connect your environment to Mattermost
> - Resource: [https://docs.mattermost.com/administration-guide/configure/configuration-settings.html#environment-variables](https://docs.mattermost.com/administration-guide/configure/configuration-settings.html#environment-variables)
> - Upload your valid Enterprise License under Edition and License
> - Ensure site URL is set appropriately for your production, dev and staging environments
> - Add your database configuration to **System Console \> Environment \> Database**
> - Add your Elasticsearch or AWS OpenSearch configuration to **System Console \> Environment \> Elasticsearch**
> - Add your file storage system configuration to **System Console \> Environment \> File Storage**
> - Add your proxy configuration to **System Console \> Environment \> Image Proxy**
> - Add your SMTP configuration to **System Console \> Environment \> SMTP**
> - Enable Push Notifications by adding your server to **System Console \> Environment \> Push Notification Server**
> - Add your cluster configuration to **System Console \> Environment \> High Availability**
- Configure your site within the System Console
> - Resource: [https://docs.mattermost.com/administration-guide/configure/configuration-settings.html#site-configuration](https://docs.mattermost.com/administration-guide/configure/configuration-settings.html#site-configuration)
- Set site access policies including permissions for roles and guest access
> - Permissions Resource: [https://docs.mattermost.com/administration-guide/onboard/advanced-permissions.html](https://docs.mattermost.com/administration-guide/onboard/advanced-permissions.html)
> - Guest Access Resource: [https://docs.mattermost.com/administration-guide/onboard/guest-accounts.html](https://docs.mattermost.com/administration-guide/onboard/guest-accounts.html)
#### 5. Test production performance and redundancy
- Define and test disaster recovery policy and processes
> - Resource: [https://docs.mattermost.com/deployment-guide/server/deploy-kubernetes.html](https://docs.mattermost.com/deployment-guide/server/deploy-kubernetes.html)
> - Resource: [https://docs.mattermost.com/administration-guide/scale/high-availability-cluster-based-deployment.html#upgrade-guide](https://docs.mattermost.com/administration-guide/scale/high-availability-cluster-based-deployment.html#upgrade-guide)
- Performance test production environment
> - Load test production environment to verify that it will handle anticipated user load
>
> > - Resource: [https://github.com/mattermost/mattermost-load-test](https://github.com/mattermost/mattermost-load-test)
>
> - Set up Prometheus and Grafana to monitor performance
>
> > - Resource: [https://docs.mattermost.com/administration-guide/scale/deploy-prometheus-grafana-for-performance-monitoring.html](https://docs.mattermost.com/administration-guide/scale/deploy-prometheus-grafana-for-performance-monitoring.html)
>
> - Set up alerts in Grafana
>
> > - Resource: [https://docs.mattermost.com/administration-guide/scale/deploy-prometheus-grafana-for-performance-monitoring.html](https://docs.mattermost.com/administration-guide/scale/deploy-prometheus-grafana-for-performance-monitoring.html)
### Roll out Mattermost
Now that you have an environment in place, we recommend working through the following items in an iterative process. You may need to cycle through each of these topics multiple times to make adjustments to suit your organization as you onboard groups of users.
#### 1. Define your team and channel strategy
- Determine and create a team structure for your environment
> - Recommendation: Start with fewer teams in your early roll out
> - Resource: [https://docs.mattermost.com/end-user-guide/collaborate/channel-naming-conventions.html](https://docs.mattermost.com/end-user-guide/collaborate/channel-naming-conventions.html)
- Determine and create key channels to support your users. A default Town Square channel is created automatically and available on every team.
> - Recommendation: Add a “Support” channel for your users to escalate questions
- (Optional) Migrate messages and channels from legacy systems
> - Resource: [https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html](https://docs.mattermost.com/administration-guide/onboard/migrating-to-mattermost.html)
#### 2. Enable key integrations
- Build the list of key integrations and tools used by your teams
> - Resource: [https://developers.mattermost.com/integrate/getting-started/](https://developers.mattermost.com/integrate/getting-started/)
- Define use cases and requirements for plugins, bots, webhooks, slash commands
> - Resource: [https://developers.mattermost.com/integrate/other-integrations/](https://developers.mattermost.com/integrate/other-integrations/)
- Set up key integrations (or migrate from POC environments)
> - Resource: [https://mattermost.com/marketplace/](https://mattermost.com/marketplace/)
- Understand Mattermost API capabilities
> - Resource: [https://api.mattermost.com/](https://api.mattermost.com/)
#### 3. Prepare for user onboarding
- Onboard champion users
- Onboard trainers and support team
- Create a training plan
> - Resource: [https://academy.mattermost.com/](https://academy.mattermost.com/)
- Define user escalation and support processes
> - Ensure you have set the site’s support URL to your own support team under **System Console \> Site Configuration \> Customization**
- Notify users in advance of roll out
> - Sample email: [https://docs.mattermost.com/administration-guide/upgrade/welcome-email-to-end-users.html](https://docs.mattermost.com/administration-guide/upgrade/welcome-email-to-end-users.html)
#### 4. Deploy client apps
- Roll out desktop app
> - Resource: [https://docs.mattermost.com/deployment-guide/desktop/desktop-app-deployment.html](https://docs.mattermost.com/deployment-guide/desktop/desktop-app-deployment.html)
> - (Optional) Use the MSI installer to install on Windows machines
>
> > - Resource: [https://docs.mattermost.com/deployment-guide/desktop/desktop-msi-installer-and-group-policy-install.html](https://docs.mattermost.com/deployment-guide/desktop/desktop-msi-installer-and-group-policy-install.html)
- Roll out mobile app
> - Resource: [https://docs.mattermost.com/deployment-guide/mobile/mobile-app-deployment.html](https://docs.mattermost.com/deployment-guide/mobile/mobile-app-deployment.html)
> - (Optional) Use an EMM provider
>
> > - Resource: [https://docs.mattermost.com/deployment-guide/mobile/deploy-mobile-apps-using-emm-provider.html](https://docs.mattermost.com/deployment-guide/mobile/deploy-mobile-apps-using-emm-provider.html)
#### 5. Roll out to groups of users
- Provision user accounts
> - Resource: [https://docs.mattermost.com/administration-guide/onboard/user-provisioning-workflows.html](https://docs.mattermost.com/administration-guide/onboard/user-provisioning-workflows.html)
- (Optional) Bulk Load users
> - Resource: [https://docs.mattermost.com/administration-guide/onboard/bulk-loading-data.html](https://docs.mattermost.com/administration-guide/onboard/bulk-loading-data.html)
- Onboard users to teams and channels
> - Recommendation: Use LDAP Group Sync to automate this process
>
> > - Resource: [https://docs.mattermost.com/administration-guide/onboard/ad-ldap-groups-synchronization.html](https://docs.mattermost.com/administration-guide/onboard/ad-ldap-groups-synchronization.html)
- Implement your training plan to end users on how to use Mattermost
> - Train on using Mattermost
> - Train on how to use integrations
#### 6. Drive adoption
- Incrementally roll out to additional user groups
> - See “Roll Out to Groups of Users”
- Manage support requests and product requests from your end users
> - Resource: [https://mattermost.com/support/](https://mattermost.com/support/)
> - See the process below for escalating to Mattermost
- Enable additional integrations and plugins to support user workflows
> - Resource: [https://mattermost.com/marketplace/](https://mattermost.com/marketplace/)
- Understand management tools available to support users
> - mmctl Command Line Tool Resource: [https://docs.mattermost.com/administration-guide/manage/mmctl-command-line-tool.html](https://docs.mattermost.com/administration-guide/manage/mmctl-command-line-tool.html)
> - Command Line Tools Resource: [https://docs.mattermost.com/administration-guide/manage/command-line-tools.html](https://docs.mattermost.com/administration-guide/manage/command-line-tools.html)
### Review the roll out
We recommend that you review your rollout on a cadence that matches your iterative approach to rolling out to users. Below are some areas to consider.
#### 1. Review project charter success metrics
- Perform end-user surveys and measure satisfaction
- Verify use case fulfillment from original requirements gathering
- Measure your response time and resolution rate for user support issues
- Identify usage gaps and address or create a plan for addressing
#### 2. Review and analyze usage
- Review Project Charter success metrics - identify usage gaps and address or create a plan for addressing
- Monitor site and team statistics
> - Resource: [https://docs.mattermost.com/administration-guide/manage/statistics.html](https://docs.mattermost.com/administration-guide/manage/statistics.html)
> - Review: Total posts, total teams, total channels, total group chats, total direct chats, top channels, top teams
- Analyze usage by lines of business and peak usage times
#### 3. Analyze system performance
- Monitor trends in CPU/memory usage
- Review trends in database connections
- Review trends in Go routines
- Review trends in concurrent sessions
#### 4. Harden security
- Harden security controls around the web, desktop, and mobile security
- Harden configuration management
- Harden network security
> - Identify additional tests and scans
> - (Optional) Enable Compliance Reporting
>
> > - Resource: [https://docs.mattermost.com/administration-guide/comply/compliance-export.html](https://docs.mattermost.com/administration-guide/comply/compliance-export.html)
#### 5. Perform maintenance tasks
- Monitor for security updates (or sign up for email updates)
> - Resource: [https://mattermost.com/security-updates/](https://mattermost.com/security-updates/)
- Perform the first upgrade
> - Resource: [https://docs.mattermost.com/administration-guide/upgrade/upgrading-mattermost-server.html](https://docs.mattermost.com/administration-guide/upgrade/upgrading-mattermost-server.html)
- Determine upgrade schedule based on Mattermost release schedules and life cycle
> - Resource: [https://docs.mattermost.com/product-overview/releases-lifecycle.html](https://docs.mattermost.com/product-overview/releases-lifecycle.html)
- Run System checks and either address or set address-by date