diff --git a/source/_templates/custom-index.html b/source/_templates/custom-index.html index e73d91186d3..db921e82de9 100644 --- a/source/_templates/custom-index.html +++ b/source/_templates/custom-index.html @@ -215,7 +215,7 @@

Admin guide

-

Use Mattermost

+

User Guide

` to automatically erase data after a set period of time, a feature that meets the Right to Erasure principle. In Team Edition, you can use database scripts to achieve the same result. - **Profile Deletion:** Delete a user’s personal information via :ref:`mmctl user delete `. This permanently deletes all user information including messages created by the user. -- **Self-Hosted Push Notification Service:** Self-host your own push notification service, or deploy mobile apps with any EMM provider that supports `AppConfig `_ to meet security and compliance policies. See :doc:`our Mobile App deployment documentation ` to learn more. +- **Self-Hosted Push Notification Service:** Self-host your own push notification service, or deploy mobile apps with any EMM provider that supports `AppConfig `_ to meet security and compliance policies. See :doc:`our Mobile App deployment documentation ` to learn more. Data portability ^^^^^^^^^^^^^^^^^ diff --git a/source/about/cloud-dedicated.rst b/source/about/cloud-dedicated.rst index 983a4ab726a..8b0138ebf59 100644 --- a/source/about/cloud-dedicated.rst +++ b/source/about/cloud-dedicated.rst @@ -57,7 +57,7 @@ Mattermost Cloud Dedicated supports :doc:`IP filtering `, including AES-256 with 2048-bit RSA on all data transmissions, between Mattermost client applications and the Mattermost server. You may either set up TLS on the Mattermost Server or :doc:`install a proxy such as NGINX `, and set up TLS on the proxy. +Mattermost provides encryption-in-transit and encryption-at-rest capabilities. Mattermost supports :doc:`TLS encryption `, including AES-256 with 2048-bit RSA on all data transmissions, between Mattermost client applications and the Mattermost server. You may either set up TLS on the Mattermost Server or :doc:`install a proxy such as NGINX `, and set up TLS on the proxy. Connections to :doc:`Active Directory/LDAP ` can :ref:`optionally be secured with TLS or stunnel `. diff --git a/source/about/cloud-shared.rst b/source/about/cloud-shared.rst index 8b9891a5fc6..5037f58be30 100644 --- a/source/about/cloud-shared.rst +++ b/source/about/cloud-shared.rst @@ -57,7 +57,7 @@ Enterprise customers with a Mattermost Cloud Shared deployment can :ref:`configu Encryption ~~~~~~~~~~~ -Mattermost provides encryption-in-transit and encryption-at-rest capabilities. Mattermost supports :doc:`TLS encryption `, including AES-256 with 2048-bit RSA on all data transmissions, between Mattermost client applications and the Mattermost server. You may either set up TLS on the Mattermost Server or :doc:`install a proxy such as NGINX `, and set up TLS on the proxy. +Mattermost provides encryption-in-transit and encryption-at-rest capabilities. Mattermost supports :doc:`TLS encryption `, including AES-256 with 2048-bit RSA on all data transmissions, between Mattermost client applications and the Mattermost server. You may either set up TLS on the Mattermost Server or :doc:`install a proxy such as NGINX `, and set up TLS on the proxy. Connections to :doc:`Active Directory/LDAP ` can :ref:`optionally be secured with TLS or stunnel `. diff --git a/source/about/deprecated-features.rst b/source/about/deprecated-features.rst index c02d5764710..34490df2b40 100644 --- a/source/about/deprecated-features.rst +++ b/source/about/deprecated-features.rst @@ -20,7 +20,7 @@ Removed features by Mattermost version Mattermost Server v10.6.0 ~~~~~~~~~~~~~~~~~~~~~~~~~ -- Support for PostgreSQL v11 and v12 have been removed. The new minimum PostgreSQL version is v13+. See the :ref:`minimum supported PostgreSQL version policy ` documentation for details. +- Support for PostgreSQL v11 and v12 have been removed. The new minimum PostgreSQL version is v13+. See the :ref:`minimum supported PostgreSQL version policy ` documentation for details. Mattermost Server v10.5.0 ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/about/desktop.rst b/source/about/desktop.rst index 8358c6f918b..05a96b4eec9 100644 --- a/source/about/desktop.rst +++ b/source/about/desktop.rst @@ -19,4 +19,4 @@ Learn more about: * :doc:`Desktop releases ` * :doc:`Desktop changelog ` -See the :ref:`desktop app software requirements ` for details on supported operating systems and releases. \ No newline at end of file +See the :ref:`desktop app software requirements ` for details on supported operating systems and releases. \ No newline at end of file diff --git a/source/about/editions-and-offerings.rst b/source/about/editions-and-offerings.rst index 4d1f14b0eea..f90c29cbcbc 100644 --- a/source/about/editions-and-offerings.rst +++ b/source/about/editions-and-offerings.rst @@ -61,7 +61,7 @@ This offering includes all the features of `Mattermost Professional <#mattermost - :doc:`Enterprise-scale search with dedicated indexing and usage resourcing via cluster support `. - :doc:`Sychronization of access controls, channels, and teams with AD/LDAP Groups `. - :doc:`eDiscovery and compliance export automation `. -- :doc:`Enterprise mobile device management with custom EMM support via AppConfig `. +- :doc:`Enterprise mobile device management with custom EMM support via AppConfig `. - :doc:`Advanced legal controls with customizable end-user terms of service and re-acceptance duration `. - :ref:`Private mobility with ID-only push notifications `. - :doc:`Enhanced compliance with global and custom retention policies for messages and files `. @@ -89,7 +89,7 @@ Mattermost Professional Mattermost Professional is the set of collaboration features that enables you to build and scale your sophisticated technical workflows across multiple cross-functional teams to deliver mission-critical software. -* *Self-hosted deployments* - **Mattermost Professional** is available to our self-hosted community who either run, or upgrade to, our self-hosted commercial Mattermost Enterprise Edition (see :doc:`deployment guides `), who purchase the appropriate subscription license key through a `channel reseller `_ or by contacting a `Mattermost Expert `_, and who then install the license key onto their Mattermost server. A 30-day free trial to preview the features in this subscription can be activated in-product (**System Console > Edition and License > Start trial**). +* *Self-hosted deployments* - **Mattermost Professional** is available to our self-hosted community who either run, or upgrade to, our self-hosted commercial Mattermost Enterprise Edition (see :doc:`deployment guides `), who purchase the appropriate subscription license key through a `channel reseller `_ or by contacting a `Mattermost Expert `_, and who then install the license key onto their Mattermost server. A 30-day free trial to preview the features in this subscription can be activated in-product (**System Console > Edition and License > Start trial**). This offering includes all the features of `Mattermost Free <#mattermost-free>`__, plus: diff --git a/source/about/faq-notifications.rst b/source/about/faq-notifications.rst index 7ce9844ec28..cae461c577e 100644 --- a/source/about/faq-notifications.rst +++ b/source/about/faq-notifications.rst @@ -42,4 +42,4 @@ TPNS, hosted at `https://push-test.mattermost.com `__, which enables you to use a production-level Hosted Push Notification Service (HPNS) at ``https://push.mattermost.com``. -Learn more about :doc:`our mobile apps and push notification service `. +Learn more about :ref:`our push notification service `. diff --git a/source/about/faq-product.rst b/source/about/faq-product.rst index c685d29baa8..fdcee315495 100644 --- a/source/about/faq-product.rst +++ b/source/about/faq-product.rst @@ -186,6 +186,6 @@ What feature quality levels does Mattermost have? We strive to release viable features. This means that we put in a significant amount of effort to ensure we solve a use case with a high bar for quality. A feature that's viable and meets our criteria for our production quality levels will be released to production. -However, when working on large and complex features or new products, we may need to test them with a high volume of customers and users. For these scenarios, we'll release them as :ref:`Experimental ` or :ref:`Beta `, and implement feature flags and/or A/B testing to validate the effectiveness of features prior to production-level release. Additionally, we `dogfood our features `_ on our community server, and provide many configuration options that ensure customers can opt-in when trying experimental or beta features. +However, when working on large and complex features or new products, we may need to test them with a high volume of customers and users. For these scenarios, we'll release them as :ref:`Experimental ` or :ref:`Beta `, and implement feature flags and/or A/B testing to validate the effectiveness of features prior to production-level release. Additionally, we `dogfood our features `_ on our community server, and provide many configuration options that ensure customers can opt-in when trying experimental or beta features. -See the :doc:`Mattermost feature labels ` documentation for details on the status, maturity, and support level of each feature, and what you can expect at each level. +See the :doc:`Mattermost feature labels ` documentation for details on the status, maturity, and support level of each feature, and what you can expect at each level. diff --git a/source/about/frequently-asked-questions.rst b/source/about/frequently-asked-questions.rst index 10346f94a4d..8bbe9d5ca06 100644 --- a/source/about/frequently-asked-questions.rst +++ b/source/about/frequently-asked-questions.rst @@ -2,7 +2,7 @@ Frequently asked questions (FAQ) ================================= .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :hidden: General questions diff --git a/source/about/mattermost-desktop-releases.md b/source/about/mattermost-desktop-releases.md index 46441adbf53..db37074d15e 100644 --- a/source/about/mattermost-desktop-releases.md +++ b/source/about/mattermost-desktop-releases.md @@ -9,12 +9,12 @@ ## Frequency -Mattermost releases a new desktop app version every 4 months, in February, May, August, and November in [binary form](https://docs.mattermost.com/collaborate/install-desktop-app.html#install-and-update-the-mattermost-desktop-app). See the [Desktop app changelog](/about/desktop-app-changelog) for release details. +Mattermost releases a new desktop app version every 4 months, in February, May, August, and November in [binary form](https://docs.mattermost.com/collaborate/install-desktop-app.html). See the [Desktop app changelog](/about/desktop-app-changelog) for release details. ```{Important} - From Mattermost v9.11, Mattermost server extended releases are now paired with Mattermost desktop app extended releases. For an optimal user experience and for the latest security fixes, we strongly recommend updating desktop clients to the latest version your Mattermost server supports. See the table below for server compatibility, and see the [Mattermost extended support releases](#extended-support-releases) documentation to learn more about extended releases. -- If you prefer to control the server and client releases, we recommend disabling automatic client updates to prevent users from upgrading their desktop client to a version your server doesn't support. See the [install Mattermost desktop app](/collaborate/install-desktop-app) documentation for platform-specific details on automatic app updates. +- If you prefer to control the server and client releases, we recommend disabling automatic client updates to prevent users from upgrading their desktop client to a version your server doesn't support. See the [install Mattermost desktop app](https://docs.mattermost.com/collaborate/install-desktop-app.html) documentation for platform-specific details on automatic app updates. ``` ## Latest releases diff --git a/source/about/mattermost-v10-changelog.md b/source/about/mattermost-v10-changelog.md index dee44b7e27c..a193b85feca 100644 --- a/source/about/mattermost-v10-changelog.md +++ b/source/about/mattermost-v10-changelog.md @@ -16,7 +16,7 @@ - Original 10.6.0 release. ### Important Upgrade Notes - - Support for PostgreSQL v11 and v12 have been removed. The new minimum PostgreSQL version is v13+. See the [minimum supported PostgreSQL version policy](https://docs.mattermost.com/install/prepare-mattermost-database#minimum-supported-version-policy) documentation for details. + - Support for PostgreSQL v11 and v12 have been removed. The new minimum PostgreSQL version is v13+. See the [minimum supported PostgreSQL version policy](https://docs.mattermost.com/deploy/software-hardware-requirements#minimum-postgresql-database-support-policy) documentation for details. - Migration times: On a system with 12M posts, and 1M fileinfo entries, the migration takes 15s. This migration is non-locking. Note that there is no migration for MySQL deployments because this optimization is only applicable for PostgreSQL. ```{Important} diff --git a/source/about/mattermost-v9-changelog.md b/source/about/mattermost-v9-changelog.md index c925ae832a7..d6b9ac2e201 100644 --- a/source/about/mattermost-v9-changelog.md +++ b/source/about/mattermost-v9-changelog.md @@ -118,7 +118,7 @@ See [this walkthrough video](https://mattermost.com/video/mattermost-v9-11-chang - Added a new feature where an admin with user management permission can now edit a user's settings in **System Console > Users**. - Added download functionality for admins to download server logs from **Server Logs** page in the **System Console**. - LDAP vendor errors are now included in the Support Packet. - - Added [metadata](https://docs.mattermost.com/manage/generating-support-packet.html#contents-of-a-support-packet) to the Support Packet. + - Added [metadata](https://docs.mattermost.com/manage/admin/generating-support-packet.html#contents-of-a-support-packet) to the Support Packet. - We are now adding the user's ID and session ID to the audit log's Actor field for the login event, to match what we provide for the logout event. - Added support for custom status in bulk export/import. - Marked the ``RemoteTeamId`` field of the ``RemoteCluster`` entity as deprecated. diff --git a/source/about/mobile-app-changelog.md b/source/about/mobile-app-changelog.md index 4beca4e7e7b..a2723d8d021 100644 --- a/source/about/mobile-app-changelog.md +++ b/source/about/mobile-app-changelog.md @@ -3238,7 +3238,7 @@ Mattermost Mobile App v1.26.0 contains low to medium level security fixes. [Upgr ### Compatibility - If **DisableLegacyMfa** setting in ``config.json`` is set to ``true`` and [multi-factor authentication](https://docs.mattermost.com/onboard/multi-factor-authentication.html) is enabled, ensure your users have upgraded to mobile app version 1.17 or later. See [Important Upgrade Notes](https://docs.mattermost.com/upgrade/important-upgrade-notes.html) for more details. - - If you are using an EMM provider via AppConfig, make sure to add two new settings, `useVPN` and `timeoutVPN`, to your AppConfig file. The settings were added for EMM connections using VPN on-demand - one to indicate if every request should wait for the VPN connection to be established, and another to set the timeout in seconds. See docs for more details on [setting AppConfig values](https://docs.mattermost.com/deploy/mobile-appconfig.html#mattermost-appconfig-values) for VPN support. + - If you are using an EMM provider via AppConfig, make sure to add two new settings, `useVPN` and `timeoutVPN`, to your AppConfig file. The settings were added for EMM connections using VPN on-demand - one to indicate if every request should wait for the VPN connection to be established, and another to set the timeout in seconds. See docs for more details on [setting AppConfig values](https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html#mattermost-appconfig-values) for VPN support. - Mobile App v1.13+ is required for Mattermost Server v5.4+. - Android operating system 7+ [is required by Google](https://android-developers.googleblog.com/2017/12/improving-app-security-and-performance.html). - iPhone 5s devices and later with iOS 11+ is required. @@ -3247,7 +3247,7 @@ Mattermost Mobile App v1.26.0 contains low to medium level security fixes. [Upgr - iOS Share Extension now supports large file sizes and improved performance ### Bug Fixes - - Fixed support for EMM connections using VPN on-demand. See docs for more details on [setting AppConfig values](https://docs.mattermost.com/deploy/mobile-appconfig.html#mattermost-appconfig-values) for VPN support. + - Fixed support for EMM connections using VPN on-demand. See docs for more details on [setting AppConfig values](https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html#mattermost-appconfig-values) for VPN support. - Fixed several Android app crash / fatal error issues. - Fixed an issue on Android where the app crashed intermittently when selecting a link. - Fixed an issue where email notifications setting was out of sync with the webapp until the setting was edited. diff --git a/source/about/mobile.rst b/source/about/mobile.rst index 2220f0a49f5..ce685680af1 100644 --- a/source/about/mobile.rst +++ b/source/about/mobile.rst @@ -21,4 +21,4 @@ Learn more about: * :doc:`Mobile releases ` * :doc:`Mobile changelog ` -See the :ref:`mobile apps software requirements ` for details on supported operating systems and releases. \ No newline at end of file +See the :ref:`mobile apps software requirements ` for details on supported operating systems and releases. \ No newline at end of file diff --git a/source/about/release-policy.md b/source/about/release-policy.md index 89643c956d7..25fe544e1f7 100644 --- a/source/about/release-policy.md +++ b/source/about/release-policy.md @@ -37,7 +37,7 @@ We strongly recommend planning ahead for upgrades before the end of an ESR's lif ESRs don’t include changes to product functionality or new features. ESRs are intended for organizations who value stability over having the newest features and improvements, or who have a long internal testing and certification process to undergo when upgrading. Consider using ESRs for more stable and long-term deployments, especially in environments where frequent updates are challenging. If your organization prefers to have the newest features and improvements, Extended Support Releases may not be the best fit for you. -To install extended support releases, follow our [install](/guides/deployment) or [upgrade](/upgrade/upgrading-mattermost-server) documentation. To restore a previous ESR, restore the database and previous version if you need to revert an upgrade. Previous ESR versions continue remain subject to a [life cycle end date](/about/mattermost-server-releases). +To install extended support releases, follow our [install](/guides/deployment-guide) or [upgrade](/upgrade/upgrading-mattermost-server) documentation. To restore a previous ESR, restore the database and previous version if you need to revert an upgrade. Previous ESR versions continue remain subject to a [life cycle end date](/about/mattermost-server-releases). ```{Important} - We strongly recommend reviewing [upgrade best practices](https://docs.mattermost.com/upgrade/prepare-to-upgrade-mattermost.html#upgrade-best-practices) for upgrading, and [important upgrade notes](/upgrade/important-upgrade-notes) for all the versions beyond the current ESR version you have currently installed. See the [Mattermost v9 changelog](https://docs.mattermost.com/about/mattermost-v9-changelog.html) for a list of database, API, and `config.json` updates for all v9.x releases. diff --git a/source/about/secure-command-and-control.rst b/source/about/secure-command-and-control.rst index 8f8c93981bd..b1d5c120f26 100644 --- a/source/about/secure-command-and-control.rst +++ b/source/about/secure-command-and-control.rst @@ -11,13 +11,13 @@ The solution provides easy-to-use collaboration for technical teams, including t Features include: -* :doc:`Private mobile communications ` to provide secure mobile apps via encryption keys and certifications with custom mobile applications. -* :doc:`Custom push notification service ` to ensure notifications are not intercepted or leaked to unsecured channels by transmitting push notifications within your private network. -* :ref:`Remote user deactivation with data purge ` to mitigate sensitive data from being stored on mobile devices after a user departs the organization. -* (Professional & Enterprise) :ref:`Hosted push notifications service (HPNS) ` for production-level uptime SLAs and encrypted TLS connections between HPNS and Apple Push Notification Services, between HPNS and Google’s Firebase Cloud Messaging Service, and between HPNS and your Mattermost Server. +* :doc:`Private mobile communications ` to provide secure mobile apps via encryption keys and certifications with custom mobile applications. +* :ref:`Custom push notification service ` to ensure notifications are not intercepted or leaked to unsecured channels by transmitting push notifications within your private network. +* :doc:`Remote user deactivation with data purge ` to mitigate sensitive data from being stored on mobile devices after a user departs the organization. +* (Professional & Enterprise) :ref:`Hosted push notifications service (HPNS) ` for production-level uptime SLAs and encrypted TLS connections between HPNS and Apple Push Notification Services, between HPNS and Google’s Firebase Cloud Messaging Service, and between HPNS and your Mattermost Server. * (Professional & Enterprise) Mobile single-sign-on with :doc:`SAML `, :doc:`AD/LDAP `, :doc:`OpenID Connect `, :doc:`Google `, and :doc:`Office365 ` for centralized identity management and automatic account provisioning for fast and secure access to mobile applications. -* (Enterprise) :ref:`ID-only push notifications ` to remove the need to pass clear text notifications through Apple and Google’s mobile notification relays. -* (Enterprise) :doc:`Enterprise Mobility Management (EMM) ` to manage secure mobile endpoints with a managed app configuration (:doc:`via AppConfig `), such as AirWatch. +* (Enterprise) :ref:`ID-only push notifications ` to remove the need to pass clear text notifications through Apple and Google’s mobile notification relays. +* (Enterprise) :doc:`Enterprise Mobility Management (EMM) ` to manage secure mobile endpoints with a managed app configuration (:doc:`via AppConfig `), such as AirWatch. For an example case study, learn why `The U.S. Department of Defense relies on Mattermost for Secure Command and Control across devices `__, including flight crews who can now securely access documents from mobile devices anywhere in the world. diff --git a/source/about/security.rst b/source/about/security.rst index 6a4de5655d8..903cf068a7e 100644 --- a/source/about/security.rst +++ b/source/about/security.rst @@ -13,9 +13,9 @@ Mattermost offers a host of features to help keep your private cloud communicati Private Cloud deployment with secure mobile apps ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Mattermost can run entirely behind your firewall as a single Linux binary, as a Docker container, or on your Kubernetes cluster with a PostgreSQL database. Remote access can be enabled through the use of :ref:`VPN clients on PC and mobile devices ` so that Mattermost can be used outside your private network. -- Mattermost mobile apps can be deployed to an :doc:`internal Enterprise App Store ` by using source code available for Mattermost mobile apps and push notification service. -- Optionally, the provided Mattermost Mobile Apps can be used when the Mattermost server is reachable through the internet on port 443. In this configuration, you have the option of using compiled :doc:`iOS and Android applications in iTunes and Google Play provided by Mattermost, Inc. ` (Mattermost Enterprise and Mattermost Professional). +- Mattermost can run entirely behind your firewall as a single Linux binary, as a Docker container, or on your Kubernetes cluster with a PostgreSQL database. Remote access can be enabled through the use of :ref:`VPN clients on PC and mobile devices ` so that Mattermost can be used outside your private network. +- Mattermost mobile apps can be deployed to an :doc:`internal Enterprise App Store ` by using source code available for Mattermost mobile apps and push notification service. +- Optionally, the provided Mattermost Mobile Apps can be used when the Mattermost server is reachable through the internet on port 443. In this configuration, you have the option of using compiled iOS and Android applications in iTunes and Google Play provided by Mattermost, Inc. (Mattermost Enterprise and Mattermost Professional). - User sessions across web, PC, and mobile can be :doc:`remotely revoked through profile settings `, or via the System Console by deactivating accounts. - Mattermost apps can be packaged into leading Enterprise Mobility Management solutions including AirWatch and Blackberry through `AppDome `__. diff --git a/source/about/self-hosted-subscriptions.rst b/source/about/self-hosted-subscriptions.rst index bd6688dff8b..1430e7497fc 100644 --- a/source/about/self-hosted-subscriptions.rst +++ b/source/about/self-hosted-subscriptions.rst @@ -29,7 +29,7 @@ You can also use the :ref:`mmctl ` Mattermost not yet installed ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you haven't yet installed and deployed a Mattermost instance, visit the :doc:`Deployment Guide ` to get started. For information on creating a system admin account, visit our :doc:`Administrator Tasks ` documentation. +If you haven't yet installed and deployed a Mattermost instance, visit the :doc:`Deployment Guide ` to get started. For information on creating a system admin account, visit our :doc:`Administrator Tasks ` documentation. Add more users to your subscription ----------------------------------- diff --git a/source/about/unsupported-legacy-releases.md b/source/about/unsupported-legacy-releases.md index 805764c1582..17c46482870 100644 --- a/source/about/unsupported-legacy-releases.md +++ b/source/about/unsupported-legacy-releases.md @@ -1222,7 +1222,7 @@ Mattermost v7.4.0 contains a medium severity level security fix. [Upgrading](htt ### Bug Fixes - Fixed an issue with a nil point exception error during imports. - - Fixed an issue where users were unable to download a [Support Packet](https://docs.mattermost.com/manage/generating-support-packet.html) using the Desktop App. + - Fixed an issue where users were unable to download a [Support Packet](https://docs.mattermost.com/manage/admin/generating-support-packet.html) using the Desktop App. - Fixed an issue with the **Message forward** modal where the auto-complete in the comment box moved with the text cursor. - Fixed an issue where muted channels with an at-mention were displayed under the **Unreads** section of the channel switcher. - Fixed an issue where the Collapsed Reply Threads setting was displayed in the **System Console > Experimental Features** section. @@ -2460,7 +2460,7 @@ IMPORTANT: If you upgrade from a release earlier than v6.2, please read the othe - Mattermost v6.2.0 contains low to medium level security fixes. [Upgrading](https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html) to this release is recommended. Details will be posted on our [security updates page](https://mattermost.com/security-updates/) 30 days after release as per the [Mattermost Responsible Disclosure Policy](https://mattermost.com/security-vulnerability-report/). ### Important Upgrade Notes - - Channel results in the channel autocomplete will include private channels. Customers using [Bleve](https://docs.mattermost.com/deploy/bleve-search.html) or [Elasticsearch](https://docs.mattermost.com/scale/elasticsearch.html) for autocomplete will have to reindex their data to get the new results. Since this can take a long time, we suggest disabling autocomplete and running indexing in the background. When this is complete, re-enable autocomplete. Note that only channel members will see private channel names in autocomplete results. + - Channel results in the channel autocomplete will include private channels. Customers using [Bleve](https://docs.mattermost.com/configure/bleve-search.html) or [Elasticsearch](https://docs.mattermost.com/scale/elasticsearch.html) for autocomplete will have to reindex their data to get the new results. Since this can take a long time, we suggest disabling autocomplete and running indexing in the background. When this is complete, re-enable autocomplete. Note that only channel members will see private channel names in autocomplete results. - [Collapsed Reply Threads](https://docs.mattermost.com/messaging/organizing-conversations.html), available in beta, are known to have a negative impact on server performance. If you cannot easily scale up and tune your database, or if you are running the Mattermost application server and database server on the same machine, we recommended disabling [``ThreadAutoFollow``](https://docs.mattermost.com/configure/configuration-settings.html#automatically-follow-threads) and [``CollapsedThreads``](https://docs.mattermost.com/configure/configuration-settings.html#collapsed-reply-threads-beta) until Collapsed Reply Threads is promoted to general availability in Q2 2022. Learn more about these [performance considerations here](https://support.mattermost.com/hc/en-us/articles/4413183568276-What-to-expect-when-enabling-Collapsed-Reply-Threads-Beta). ```{Important} @@ -9375,7 +9375,7 @@ Multiple setting options were added to `config.json`. Below is a list of the add - Added message buttons to support user interactions with posts made by incoming webhooks and custom slash commands. #### Mobile Support for AppConfig -- iOS and Android mobile apps now support Enterprise Mobility Management (EMM) solutions through integration with [App Config](https://www.appconfig.org/). See [documentation](https://docs.mattermost.com/deploy/mobile-appconfig.html) to learn more. +- iOS and Android mobile apps now support Enterprise Mobility Management (EMM) solutions through integration with [App Config](https://www.appconfig.org/). See [documentation](https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html) to learn more. ### Improvements @@ -11414,7 +11414,7 @@ Thanks also to those who reported bugs that benefited the release, in alphabetic - Added server-side in-memory caching to reduce DB reads/writes. #### Connection Security -- TLS is now supported directly on the Mattermost server. Learn more in our [documentation](https://docs.mattermost.com/install/config-tls-mattermost.html). +- TLS is now supported directly on the Mattermost server. Learn more in our [documentation](https://docs.mattermost.com/deploy/server/setup-tls.html). - Support for automatically fetching certificates through Let's Encrypt. #### Minio File Storage @@ -12769,7 +12769,7 @@ Release date: 2016-04-16 #### TPNS and EAS options -- [Enterprise App Store](https://docs.mattermost.com/deployment/push.html#enterprise-app-store-eas) (EAS) and [Test Push Notification Service](https://docs.mattermost.com/deploy/mobile-hpns.html#hosted-push-notifications-service-hpns) (TPNS) option are now included in **System Console** > **Email Settings** > **Push Notification Settings** as built-in options. +- [Enterprise App Store](https://docs.mattermost.com/deployment/push.html#enterprise-app-store-eas) (EAS) and [Test Push Notification Service](https://docs.mattermost.com/configure/push-notification-configuration-settings.html#test-push-notifications-service-tpns) (TPNS) option are now included in **System Console** > **Email Settings** > **Push Notification Settings** as built-in options. ### Languages diff --git a/source/about/zero-trust.rst b/source/about/zero-trust.rst index cdeaa6e1102..57e92ceca98 100644 --- a/source/about/zero-trust.rst +++ b/source/about/zero-trust.rst @@ -41,8 +41,8 @@ Flexibility and control to host Mattermost securely to minimize the risk of vuln Mattermost's self-hosting enables tailored configurations for on-premises systems with specialized security needs, while cloud IP filtering ensures scalable control for remote or hybrid teams operating across distributed environments: -- `Self-hosting Mattermost `_: Enforces stricter data sovereignty requirements, and complete control over deployment environments, enabling organizations to implement custom Zero Trust security measures. -- `Cloud IP Filtering `_: Prevents untrusted entities from gaining initial access, restricting platform access to trusted network ranges, enforcing an evaluation of every connection. +- :doc:`Self-hosting Mattermost `: Enforces stricter data sovereignty requirements, and complete control over deployment environments, enabling organizations to implement custom Zero Trust security measures. +- :ref:`Cloud IP Filtering `: Prevents untrusted entities from gaining initial access, restricting platform access to trusted network ranges, enforcing an evaluation of every connection. Encryption ---------- diff --git a/source/collaborate/access-your-workspace.rst b/source/collaborate/access-your-workspace.rst index 2465e82f257..9d1b363ec99 100644 --- a/source/collaborate/access-your-workspace.rst +++ b/source/collaborate/access-your-workspace.rst @@ -1,10 +1,7 @@ Access your workspace ===================== -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -Your Mattermost :doc:`workspace ` is accessible through a URL link. You'll receive a link from your Mattermost system admin or through an email invitation. You can use that link in a web browser, or as a server connection in the :doc:`desktop app `, the :doc:`mobile app for iOS `, or the :doc:`mobile app for Android `. +Access your Mattermost instance with your credentials using a web browser, the desktop app, or the mobile app for iOS or Android. Depending on how Mattermost is configured, you'll log in using your email address, username, or single sign-on (SSO) username, and your password. .. tip:: @@ -24,20 +21,16 @@ Your Mattermost :doc:`workspace ` is accessible through **Web browser** - 1. Open a supported :ref:`web browser `. + 1. Open a supported :ref:`web browser `. 2. Copy and paste the Mattermost server link into the browser's address field. - 3. Enter your user credentials to log into Mattermost. - - .. tip:: + 3. Enter your user credentials to log into Mattermost. + 4. Bookmark the Mattermost URL in your web browser of choice so logging into Mattermost is easy in the future. - - We recommend bookmarking the Mattermost URL in your browser of choice so logging into Mattermost is easy in the future. - - The credentials you use to log in depend on how your system admin has configured Mattermost. You may be prompted for an `email address or username <#email-address-or-username>`__ and a password, or you may be able to `log in using other credentials <#single-sign-on-sso>`__. Contact your system admin for more information. - **Desktop app** - 1. Download and install the Mattermost :doc:`desktop app `. + 1. Download and install the Mattermost desktop app from the App Store (macOS), Microsoft Store (Windows), or by :doc:`using a package manager (Linux) `. 2. When prompted, enter the Mattermost server link and a display name for the Mattermost instance. The display name is helpful in cases where you connect to multiple Mattermost instances. See the :doc:`server connections ` documentation for details. - 3. Enter your user credentials to log into Mattermost. + 3. Enter your user credentials to log into Mattermost. 4. The team that displays first in the team sidebar opens. If you're not a member of a team yet, you're prompted to select a team to join. .. note:: @@ -46,15 +39,11 @@ Your Mattermost :doc:`workspace ` is accessible through .. tab:: Mobile - 1. Download and install the Mattermost :doc:`iOS mobile app ` or the :doc:`Android mobile app `. + 1. Download and install the Mattermost mobile app from the Apple App Store (iOS) or Google Play Store (Android). 2. When prompted, enter the Mattermost server link and a display name for the Mattermost instance. Server URLs must begin with either ``http://`` or ``https://``. The display name is helpful in cases where you connect to multiple Mattermost instances. See the :doc:`server connections ` documentation for details. 3. Enter your user credentials to log into Mattermost. 4. The team that displays first in the team sidebar opens. If you're not a member of a team yet, you're prompted to select a team to join. - .. tip:: - - The credentials you use to log in depend on how your system admin has configured Mattermost. You may be prompted for an email address or username and a password, or you may be able to log in using other credentials. Contact your system admin for details. - Reset your password -------------------- diff --git a/source/collaborate/install-android-app.rst b/source/collaborate/install-android-app.rst index d34aa6837da..8435fa626f1 100644 --- a/source/collaborate/install-android-app.rst +++ b/source/collaborate/install-android-app.rst @@ -1,9 +1,6 @@ Install the Mattermost Android mobile app ========================================= -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - Take Mattermost wherever you go by installing the Mattermost mobile app on your Android mobile device running Android 7.0 or later. 1. On your device, visit the Play Store. diff --git a/source/collaborate/install-desktop-app.rst b/source/collaborate/install-desktop-app.rst index e2257427a00..5c8f50e35d5 100644 --- a/source/collaborate/install-desktop-app.rst +++ b/source/collaborate/install-desktop-app.rst @@ -1,314 +1,14 @@ Install the Mattermost desktop app ================================== -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: +Download and install the Mattermost desktop app from the App Store (macOS), Microsoft Store (Windows), or by :doc:`using a package manager (Linux) `. When new desktop app releases become available, your desktop app is automatically updated. -The Mattermost desktop app is available for Linux, Mac, and Windows operating systems. The Desktop App supports all the features of the web experience, plus the following features: +We strongly recommend installing the desktop app on a local drive. Network shares aren't supported. -- :doc:`Connect to multiple Mattermost servers ` from a single interface, and navigate between servers using keyboard shortcuts. -- :doc:`Auto-start Mattermost ` when a user logs into their machine. -- :doc:`Add Mattermost ` to the Windows Start menu, the Taskbar, the Dock, or the System Tray. -- :doc:`Deep link to the desktop app ` via the ``mattermost://`` protocol if the app is already installed. (Windows/macOS only) -- :doc:`Set up Desktop Entry ` for the application to more easily `integrate into a desktop environment `_. (Linux only) - -See the :ref:`desktop app software requirements ` for details on supported operating systems and releases. - -Install and update the Mattermost desktop app ---------------------------------------------- - -You can download the `desktop app `_ directly from the Downloads page. You can also use the following installation guides for Linux, Mac, and Windows. - -.. tab:: Windows - - Windows 10+ is required. Automatic app updates are supported and enabled. When a new version of the desktop app is released, your app updates automatically. - - **Install the Mattermost Desktop App** - - 1. Download the latest version of the Mattermost desktop app for the `64-bit version of Windows `_ - 2. From the **\Downloads** folder, right-click on the file ``mattermost-desktop-setup-5.11.2-win.exe``, then select **Open** to start an installer for the app. Once finished, the Mattermost desktop app opens automatically. - - .. warning:: - Mattermost Desktop should always be installed on a local drive. Network Shares are not supported as installation locations. - - **MSI Installer and group policies** - - The following group policies are available supporting a state option of Not Configured, Enabled, or Disabled: - - +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ - | Group policy | Description | Mattermost release | Setting | - +==========================+============================================================+======================+============================+ - | Enable Server Management | If disabled, management of servers in the | v4.3 or later | ``EnableServerManagement`` | - | | app settings are disabled. | | | - +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ - | Default Server List | Define one or more default, permanent servers. | v4.3 or later | ``DefaultServerList`` | - +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ - | Automatic Updates | If disabled, automatic desktop app updates are disabled. | v5.1 or later | ``EnableAutoUpdates`` | - +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ - - **Disable automatic updates** - - Automatic desktop app updates can be disabled by configuring the supported group policy. See the :doc:`MSI installer and group policy documentation ` for instructions on installing the Mattermost Desktop App via an MSI installer, configuring supported group policies, and performing silent MSI installations. Changes to group policies require you to restart Mattermost for those changes to take effect. - -.. tab:: macOS - - MacOS 11+ is required. You have two ways to install the desktop app, and how you install the app determines whether it updates automatically. - - **Install from the App Store** - - We recommend that you install the desktop app from the `App Store `_. When you install through the App Store, your desktop app updates automatically when a new release is available. - - **Download the Desktop App from GitHub** - - You can download the `desktop app `_ directly from the Downloads page. However, when you install the desktop app this way, you can't manually check for updates, and updates won't be installed automatically. - - 1. Download the latest version of the Mattermost desktop app: - - - `Intel systems `_ - - `M1 systems `_ (Beta) - - 2. Double-click the download to open the disk image. - - 3. Drag the Mattermost application to the **Applications** folder. - - .. tip:: - You can review the current version of your desktop app by selecting **Mattermost > About Mattermost** from the macOS menu bar. - -.. tab:: Ubuntu/Debian - - Both a ``.deb`` package (Beta), and an official APT repository is available for Debian 9 and for Ubuntu releases 20.04 LTS or later. Automatic app updates are supported and enabled. When a new version of the desktop app is released, your app updates automatically. - - .. important:: - - The GPG public key has changed. If you had previously set up the repository on your system, you'll need to download the new key. You can set the ``UPDATE_GPG_KEY=yes`` environment variable when running the setup script to configure it to overwrite the previous key on your system with the new one. The first step of installation then becomes: ``curl -fsS -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo UPDATE_GPG_KEY=yes bash``. Depending on your setup, additional steps may also be required, particularly for installations that don't rely on the repository setup script. - - 1. At the command line, set up the Mattermost repository on your system: - - .. code-block:: sh - - curl -fsS -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo bash - - 2. Install the Mattermost desktop app: - - .. code-block:: sh - - sudo apt install mattermost-desktop - - 3. Update the Mattermost desktop app: - - .. code-block:: sh - - sudo apt upgrade mattermost-desktop - - **Snapcraft package** - - A snap is available for systems that have Snapcraft installed. Snapcraft is installed by default on Ubuntu 16.04 and later, but for most other Linux distributions you can install it manually. To install Snapcraft, see `Install snapd `_ on the Snapcraft website for details. - - 1. At the command line, execute the following command: - - .. code-block:: sh - - sudo snap install mattermost-desktop --beta - - 2. Run Mattermost as a desktop app. - - .. tip:: - You can review the current version of your desktop app by selecting the **More** |more-icon-vertical| icon located in the top left corner of the desktop app, then selecting **Help > Version...**. - -.. tab:: CentOS/RHEL - - Beta ``.rpm`` packages are available for CentOS and RHEL 7 and 8. Automatic app updates aren't supported. You must update your app manually. - - **Install the Mattermost Desktop App** - - 1. Download the latest version of the Mattermost desktop app for 64-bit systems: `mattermost-desktop-5.11.2-linux-x86_64.rpm `_ - - 2. At the command line, execute the following command: - - .. code-block:: sh - - sudo rpm -i mattermost-desktop-5.11.2-linux-x86_64.rpm - - 3. Run Mattermost as a desktop app. - - To manually update the desktop app, run the following command: - - .. code-block:: sh - - sudo rpm -u mattermost-desktop-5.11.2-linux-x86_64.rpm - - .. tip:: - You can review the current version of your desktop app by selecting the **More** |more-icon-vertical| icon located in the top left corner of the desktop app, then selecting **Help > Version...**. - -.. tab:: Generic Linux - - The Desktop app is available in two formats which are usable on most Linux distributions: a compressed tarball, and an AppImage binary. Both can be downloaded from the `Desktop App's Github releases page `_. Automatic app updates are supported and enabled on AppImage binary builds. When a new version of the desktop app is released, your app updates automatically. - - For instructions on how to use the AppImage binary, please refer to the `AppImage Quickstart documentation page `_. - - **Install the Desktop App's compressed tarball** - - 1. Download the latest version of the Mattermost desktop app for 64-bit systems: `mattermost-desktop-5.11.2-linux-x64.tar.gz `_ - - 2. Extract the archive to a convenient location, then give ``chrome-sandbox`` in the extracted directory the required ownership and permissions: ``sudo chown root:root chrome-sandbox && sudo chmod 4755 chrome-sandbox`` - - 3. Execute ``mattermost-desktop`` located inside the extracted directory. - - 4. To create a Desktop launcher, open the file ``README.md``, and follow the instructions in the **Desktop launcher** section. - - -Log in using the desktop app ------------------------------ - -The first time you log in to Mattermost using the desktop app, you'll see a splash screen that introduces you to desktop app functionality. - -1. Select **Get Started** to connect to a Mattermost server. -2. Enter a **Server URL** and **Server display name**, then select **Connect**. - -.. tip:: - - - Can't find your Mattermost server URL? Ask your company’s IT department or your Mattermost system admin for your organization’s **Mattermost Site URL**. It’ll look something like ``https://example.com/company/mattermost``, ``mattermost.yourcompanydomain.com``, or ``chat.yourcompanydomain.com``. These URLs could also end in ``.net``. - - Having trouble launching your Desktop App? See the `Troubleshooting section <#troubleshooting-your-desktop-app-installation>` for details. - -Additional documentation resources ----------------------------------- - -The following additional documentation resources are also available for the Mattermost desktop app: - -- :doc:`Desktop App changelog ` -- :doc:`Configure your desktop app experience ` -- `Source code `_ -- `Contributor’s guide `_ - -Troubleshooting your Desktop App installation ----------------------------------------------- - -Where is configuration stored locally? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The location of the Mattermost desktop app configuration file depends on the platform where you're running Mattermost (and, in the case of macOS, how you've chosen to install the app): - -- Windows: ``Users\\AppData\Roaming\Mattermost`` -- macOS installer: ``/Users//Library/Application Support/Mattermost`` -- macOS App Store: ``/Users//Library/Containers/Mattermost.Desktop/Data/Library/Application Support/Mattermost`` (via Finder: ``~/Library/Application Support/Mattermost`` as the extension is hidden) -- Linux: ``~/.config/Mattermost`` +1. When prompted, enter the Mattermost server link and a display name for the Mattermost instance. The display name is helpful in cases where you connect to multiple Mattermost instances. See the :doc:`server connections ` documentation for details. +2. Enter your user credentials to log into Mattermost. +3. The team that displays first in the team sidebar opens. If you're not a member of a team yet, you're prompted to select a team to join. .. note:: - - Local configuration data is not automatically removed when uninstalling the desktop app. If you wish to remove all data, you must manually remove the files from the applicable location noted above. - - Prior to uninstalling, you can choose to log out of any active sessions. You can terminate active sessions from another Mattermost session in **Profile > Security > View and Logout of Active Sessions**, then select **Log Out**. Desktop app sessions are labeled as **Native Desktop App**. - -How do I access logs? -~~~~~~~~~~~~~~~~~~~~~ - -From Mattermost desktop v5.3, you can access logs via **Help > Show logs**, which opens the file manager window showing the location of the log file. - -How do I download app diagnostics? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -From Mattermost desktop v5.3, you can download a diagnostics text file via **Help > Run diagnostics**, which can be attached to a Support ticket. - -Desktop App displays white screen while launching and doesn't load the page -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Delete the local ``Mattermost desktop app`` configuration file. See the `Where is configuration stored locally? <#where-is-configuration-stored-locally>`__ section above for file location details. -2. Reinstall the application. - -"Installation has failed" dialog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The app data might be corrupted. Remove all the files in ``%LOCALAPPDATA%\mattermost``, then try reinstalling the app. - -"The application "Mattermost" can't be opened" dialog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On macOS Catalina, this dialog can be triggered if the Mac Archive Utility is the default method for decompressing files. In this case using a third-party tool such as `Keka `_ or `Unarchiver `_ may resolve the problem. - -Desktop App window is black and doesn't load the page -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Ensure you have installed the latest desktop app version available. -2. Clear your cache and reload the app from **View > Clear Cache and Reload** or press :kbd:`Ctrl` :kbd:`Shift` :kbd:`R` on Windows or Linux, or :kbd:`⌘` :kbd:`⇧` :kbd:`R` on Mac. -3. Quit the app and restart it to see if the issue clears. -4. Disable GPU hardware acceleration. - - - On Windows or Linux, select **File > Settings** and clear the **Use GPU hardware acceleration** option. - - On macOS, select **Mattermost > Settings** and clear the **Use GPU hardware acceleration** option. - -5. If you are using a special video driver, such as Optimus, try disabling it to see if the problem is resolved. - -Desktop App window is white and doesn't load the page -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Ensure you have installed the latest desktop app version available. -2. Delete the ``%userprofile%\AppData\Roaming\Mattermost`` directory on your local machine. -3. Reinstall the desktop app. - -Desktop App is not visible, but the Mattermost icon is in the Task Bar -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This issue can occur on Windows in a multiple-monitor setup. When you disconnect the monitor that Mattermost is displayed on, Mattermost continues to display at screen coordinates that no longer exist. - -To resolve this issue, you can reset the desktop app screen location by deleting the screen location file. When the file is not present, the desktop app displays on the primary monitor by default. - -To reset the desktop app screen location: - -1. If the desktop app is running, right-click the Mattermost icon in the task bar, then select **Close Window**. -2. Open Windows File Explorer, and go to the ``%APPDATA%\Mattermost`` folder. -3. Delete the file ``bounds-info.json``. - -Desktop App constantly refreshes the page -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This issue can occur when ``localStorage`` has an unexpected state. To resolve the issue: - -- Windows: Open Windows File Explorer, go to the ``%APPDATA%\Mattermost`` folder, then delete the ``Local Storage`` folder. -- Mac: Open Finder, go to the ``~/Library/Application Support/Mattermost`` folder, then delete the ``Local Storage`` folder. -- Linux: Open the File Manager, go to the ``~/.config/Mattermost`` folder, then delete the ``Local Storage`` folder. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using ``rm -rf ~/.config/Mattermost``. - -Desktop App constantly asks to log in to Mattermost server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This issue can occur after a crash or unexpected shutdown of the desktop app that causes the app data to be corrupted. To resolve the issue: - -- Windows: Open Windows File Explorer, go to the ``%APPDATA%\Mattermost`` folder, then delete the ``IndexedDB`` folder and the ``Cookies`` and ``Cookies-journal`` files. -- Mac: Open Finder, go to the ``~/Library/Application Support/Mattermost`` folder, then delete the ``IndexedDB`` folder and the ``Cookies`` and ``Cookies-journal`` files. -- Linux: Open the file manager, go to the ``~/.config/Mattermost`` folder, then delete the ``IndexedDB`` folder and the ``Cookies`` and ``Cookies-journal`` files. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using ``rm -rf ~/.config/Mattermost``. - -"Internal error: BrowserWindow 'unresponsive' event has been emitted" -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Selecting **Show Details** on the dialog provides logs. Ways to resolve the issue: - -1. Clear the cache via **View > Clear Cache and Reload** or press :kbd:`Ctrl` :kbd:`Shift` :kbd:`R` on Windows or Linux, or :kbd:`⌘` :kbd:`⇧` :kbd:`R` on Mac. -2. Go to App Settings via **File > Settings** (or by pressing :kbd:`Ctrl` :kbd:`,` on Windows or Linux, or :kbd:`⌘` :kbd:`,` on Mac) and unselect hardware acceleration. - -Desktop app not responsive within Citrix Virtual Apps or Desktop Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Append ``Mattermost.exe;`` to the Registry Key ``HKLM\SYSTEM\CurrentControlSet\Services\CtxUvi\UviProcessExcludes`` and reboot the system. - -For further assistance, review the `Troubleshooting forum `_ for previously reported errors, or `join the Mattermost user community for troubleshooting help `_. - -Can I uninstall the desktop app I installed using snap on Linux? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes. Run the following command from a terminal window: ``sudo snap remove mattermost-desktop``. - -Report Desktop App issues -------------------------- - -When reporting issues found in the Mattermost desktop app, it's helpful to include the contents of the Developer Tools Console along with `the information on this page `_. - -To access the Developer Tools Console: - -1. In the menu bar, go to **View > Developer Tools > Developer Tools for Current Tab**. -2. Select the **Console** tab. -3. Right-click the log entry, then select **Save As**. -4. Save the file, then send it along with a description of your issue. -5. Close the console to disable the Developer Tools. - -You can open an additional set of developer tools for each server you have added to the desktop app. The tools can be opened by pasting this command in the Developer Tools Console you opened with the steps described above: - - .. code-block:: javascript - - document.getElementsByTagName("webview")[0].openDevTools(); + When you log into Mattermost using external user credentials, such as Google or Entra ID, you'll temporarily leave the desktop app during login while authenticating your credentials. Once you're successfully logged in to Mattermost, you'll be returned to the desktop app. See the `Single Sign-On (SSO) <#single-sign-on-sso>`__ section below for details on the external providers that Mattermosts supports. \ No newline at end of file diff --git a/source/collaborate/install-ios-app.rst b/source/collaborate/install-ios-app.rst index 06391f74936..1a375e26793 100644 --- a/source/collaborate/install-ios-app.rst +++ b/source/collaborate/install-ios-app.rst @@ -1,9 +1,6 @@ Install the Mattermost iOS mobile app ===================================== -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - Take Mattermost wherever you go by installing the Mattermost mobile app on your iOS mobile device running iOS 12.1 or later. 1. On your device, visit the App Store. diff --git a/source/collaborate/keyboard-shortcuts.rst b/source/collaborate/keyboard-shortcuts.rst index 3e6b853c7c4..9ddbf88b3df 100644 --- a/source/collaborate/keyboard-shortcuts.rst +++ b/source/collaborate/keyboard-shortcuts.rst @@ -26,7 +26,7 @@ Mattermost keyboard shortcuts help you make a more efficient use of your keyboar Channel navigation ------------------ -The following keyboard shortcuts for channels are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +The following keyboard shortcuts for channels are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +-------------------------------------+------------------------------+----------------------------------------------------------------------------------+ | On Windows & Linux | On Mac | Description | @@ -66,7 +66,7 @@ The following keyboard shortcuts for channels are supported in all :ref:`support File uploads ------------- -The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +-----------------------+--------------------+-----------------+ | On Windows & Linux | On Mac | Description | @@ -77,7 +77,7 @@ The following keyboard shortcuts are supported in all :ref:`supported browsers < Messages -------- -The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +-----------------------------------------------+--------------------------------------------+-----------------------------------------------------------+ | On Windows & Linux | On Mac | Description | @@ -102,7 +102,7 @@ The following keyboard shortcuts are supported in all :ref:`supported browsers < Message formatting -------------------- -The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app. +-----------------------------------+-----------------------------+------------------------+ | On Windows & Linux | On Mac | Description | @@ -117,7 +117,7 @@ The following keyboard shortcuts are supported in all :ref:`supported browsers < Accessibility nagivation ------------------------- -The following keyboard shortcuts work in all :ref:`supported browsers ` and in the Mattermost desktop app. +The following keyboard shortcuts work in all :ref:`supported browsers ` and in the Mattermost desktop app. +----------------------------------------------+------------------------------------------+--------------------------------------------------+ | On Windows & Linux | On Mac | Description | @@ -140,7 +140,7 @@ The following keyboard shortcuts work in all :ref:`supported browsers ` and in the Mattermost desktop app when :doc:`calls ` are enabled. +The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost desktop app when :doc:`calls ` are enabled. +-----------------------------------------------------------+--------------------------------------------------+-----------------------------------------------------------------------------------------+ | On Windows & Linux | On Mac | Description | @@ -216,7 +216,7 @@ The following navigation keyboard shortcuts are supported only in the Mattermost Zoom in & zoom out display --------------------------- -The following display keyboard shortcuts work in all :ref:`supported browsers ` and in the Mattermost desktop app. +The following display keyboard shortcuts work in all :ref:`supported browsers ` and in the Mattermost desktop app. +-------------------------------------+------------------------------+----------------------------------------+ | On Windows & Linux | On macOS | Description | diff --git a/source/collaborate/team-keyboard-shortcuts.rst b/source/collaborate/team-keyboard-shortcuts.rst index a71acb8b0ff..22126e31f1d 100644 --- a/source/collaborate/team-keyboard-shortcuts.rst +++ b/source/collaborate/team-keyboard-shortcuts.rst @@ -13,7 +13,7 @@ Keyboard shortcuts help you make a more efficient use of your keyboard when navi Team navigation --------------- -The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost Desktop App. +The following keyboard shortcuts are supported in all :ref:`supported browsers ` and in the Mattermost Desktop App. +-------------------------------------------+--------------------------------------+----------------------------------------------+ | On Windows & Linux | On Mac | Description | diff --git a/source/conf.py b/source/conf.py index b9cb9a8fc0d..0ba665fb0ed 100644 --- a/source/conf.py +++ b/source/conf.py @@ -182,7 +182,7 @@ def setup(_: Sphinx): "administration/backup.html": "https://docs.mattermost.com/deploy/backup-disaster-recovery.html", "administration/branding.html": - "https://docs.mattermost.com/configure/custom-branding-tools.html", + "https://docs.mattermost.com/manage/admin/customize-branding.html", "administration/bulk-export.html": "https://docs.mattermost.com/manage/bulk-export-tool.html", "administration/changelog.html": @@ -248,13 +248,13 @@ def setup(_: Sphinx): "administration/hipchat-migration-guidelines.html": "https://docs.mattermost.com/onboard/migrating-from-hipchat-to-mattermost.html", "administration/image-proxy.html": - "https://docs.mattermost.com/deploy/image-proxy.html", + "https://docs.mattermost.com/deploy/server/image-proxy.html", "administration/important-upgrade-notes.html": "https://docs.mattermost.com/upgrade/important-upgrade-notes.html", "administration/legacy-upgrade.html": - "https://docs.mattermost.com/guides/deployment.html#upgrade-mattermost", + "https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html", "administration/light-install-hindi.html": - "https://docs.mattermost.com/guides/deployment.html", + "https://docs.mattermost.com/deploy/server/deploy-containers.html", "administration/migrating.html#migrating-from-slack-using-the-mattermost-mmetl-tool-and-bulk-import": "https://docs.mattermost.com/onboard/migrating.html#migrating-from-slack-using-the-mattermost-mmetl-tool-and-bulk-import", "administration/migrating.html#migrating-from-slack-using-the-mattermost-web-app": @@ -302,11 +302,11 @@ def setup(_: Sphinx): "administration/upgrade.html#upgrade-team-edition-to-enterprise-edition": "https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html#upgrading-team-edition-to-enterprise-edition", "administration/upgrade-guide.html": - "https://docs.mattermost.com/guides/deployment.html#upgrade-mattermost", + "https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html", "administration/upgrading-to-2.0.html": - "https://docs.mattermost.com/guides/deployment.html#upgrade-mattermost", + "https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html", "administration/upgrading-to-3.0.html": - "https://docs.mattermost.com/guides/deployment.html#upgrade-mattermost", + "https://docs.mattermost.com/upgrade/upgrading-mattermost-server.html", "administration/user-provisioning.html": "https://docs.mattermost.com/onboard/user-provisioning-workflows.html", "administration/config-in-database.html#create-an-environment-file": @@ -429,6 +429,8 @@ def setup(_: Sphinx): "https://docs.mattermost.com/configure/experimental-configuration-settings.html#enable-local-mode-for-mmctl", "administration/upgrade.html#upgrade-guide": "https://docs.mattermost.com/guides/upgrade-mattermost.html", +"administration/release-lifecycle.html": + "https://docs.mattermost.com/about/releases-lifecycle.html", # Boards redirects "boards/navigating-mattermost-boards.html": @@ -874,13 +876,13 @@ def setup(_: Sphinx): "cloud/cloud-integrations.html": "https://developers.mattermost.com/integrate/admin-guide/admin-webhooks-incoming/", "cloud/cloud-mobile/cloud-app-config.html": - "https://docs.mattermost.com/deploy/mobile-appconfig.html", + "https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html", "cloud/cloud-mobile/troubleshooting-mobile.html": - "https://docs.mattermost.com/deploy/mobile-faq.html", + "https://docs.mattermost.com/deploy/mobile/mobile-faq.html", "cloud/cloud-reporting.html": "https://docs.mattermost.com/manage/cloud-reporting.html", "cloud/mobile-apps-faq.html": - "https://docs.mattermost.com/deploy/mobile-faq.html", + "https://docs.mattermost.com/deploy/mobile/mobile-faq.html", "cloud/cloud-user-management.html": "https://docs.mattermost.com/channels/manage-channel-members.html", @@ -917,6 +919,8 @@ def setup(_: Sphinx): # Configure redirects "configure/config-ssl-http2-apache2.html": "https://forum.mattermost.com/t/configuring-apache2-with-ssl-and-http-2/11939", +"configure/customizing-mattermost.html": + "https://docs.mattermost.com/configure/customize-mattermost.html", "configure/configuring-apache2.html": "https://forum.mattermost.com/t/configuring-apache2-as-a-proxy-for-mattermost-server/11938", "configure/enable-ai-copilot.html": @@ -1942,7 +1946,37 @@ def setup(_: Sphinx): # Deploy redirects "deploy/mobile-apps-faq.html": - "https://docs.mattermost.com/deploy/mobile-faq.html", + "https://docs.mattermost.com/deploy/mobile/mobile-faq.html", +"deploy/bleve-search.html": + "https://docs.mattermost.com/configure/bleve-search.html", +"deploy/image-proxy.html": + "https://docs.mattermost.com/deploy/server/image-proxy.html", +"deploy/consider-mobile-vpn-options.html": + "https://docs.mattermost.com/deploy/mobile/consider-mobile-vpn-options.html", +"deploy/mobile-appconfig.html": + "https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html", +"deploy/mobile-faq.html": + "https://docs.mattermost.com/deploy/mobile/mobile-faq.html", +"deploy/build-custom-mobile-apps.html": + "https://docs.mattermost.com/deploy/mobile/distribute-custom-mobile-apps.html", +"deploy/client-side-data.html": + "https://docs.mattermost.com/deploy/mobile/mobile-app-deployment.html", +"deploy/deploy-mobile-apps-using-emm-provider.html": + "https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html", +"deploy/mobile-hpns.html": + "https://docs.mattermost.com/deploy/mobile/host-your-own-push-proxy-service.html", +"deploy/mobile-overview.html": + "https://docs.mattermost.com/deploy/mobile/mobile-app-deployment.html", +"deploy/mobile-troubleshoot-notifications.html": + "https://docs.mattermost.com/deploy/mobile/mobile-troubleshooting.html", +"deploy/mobile-troubleshoot.html": + "https://docs.mattermost.com/deploy/mobile/mobile-troubleshooting.html", +"deploy/use-prebuilt-mobile-apps.html": + "https://docs.mattermost.com/deploy/mobile/mobile-app-deployment.html", +"deploy/desktop-app.html": + "https://docs.mattermost.com/deploy/desktop/desktop-app-deployment.html", +"deploy/deployment-overview.html": + "https://docs.mattermost.com/deploy/application-architecture.html", "deploy/deprecated-features.html": "https://docs.mattermost.com/about/deprecated-features.html", "deploy/desktop-app-changelog.html": @@ -2082,9 +2116,9 @@ def setup(_: Sphinx): "deployment/mobile-app-deployment.html": "https://docs.mattermost.com/deploy/mobile-overview.html", "deployment/on-boarding.html": - "https://docs.mattermost.com/getting-started/admin-onboarding-tasks.html", + "https://docs.mattermost.com/upgrade/admin-onboarding-tasks.html", "deployment/on-boarding.html#common-tasks": - "https://docs.mattermost.com/getting-started/admin-onboarding-tasks.html", + "https://docs.mattermost.com/upgrade/admin-onboarding-tasks.html", "deployment/permissions-backend.html": "https://docs.mattermost.com/onboard/advanced-permissions-backend-infrastructure.html", "deployment/pre-sales.html": @@ -2092,7 +2126,7 @@ def setup(_: Sphinx): "deployment/productivity-tools.html": "https://mattermost.com/marketplace/", "deployment/push.html": - "https://docs.mattermost.com/deploy/mobile-hpns.html", + "https://docs.mattermost.com/deploy/mobile/host-your-own-push-proxy-service.html", "deployment/scaling.html": "https://docs.mattermost.com/scale/scaling-for-enterprise.html", "deployment/sso-ldap.html": @@ -2219,21 +2253,53 @@ def setup(_: Sphinx): # Getting Started redirects "getting-started/implementation_plan.html": - "https://docs.mattermost.com/getting-started/implementation-plan.html", + "https://docs.mattermost.com/deploy/server/server-deployment-planning.html", +"getting-started/feature-labels.html": + "https://docs.mattermost.com/manage/feature-labels.html", +"getting-started/admin-onboarding-tasks.html": + "https://docs.mattermost.com/upgrade/admin-onboarding-tasks.html", +"getting-started/enterprise-roll-out-checklist.html": + "https://docs.mattermost.com/upgrade/enterprise-roll-out-checklist.html", +"getting-started/welcome-email-to-end-users.html": + "https://docs.mattermost.com/upgrade/welcome-email-to-end-users.html", +"getting-started/architecture-overview.html": + "https://docs.mattermost.com/deploy/application-architecture.html", +"getting-started/implementation-plan.html": + "https://docs.mattermost.com/deploy/server/server-deployment-planning.html", "getting-started/light-install.html": - "https://docs.mattermost.com/guides/deployment.html", + "https://docs.mattermost.com/deploy/server/deploy-containers.html", "getting-started/welcome_email.html": - "https://docs.mattermost.com/getting-started/welcome-email-to-end-users.html", + "https://docs.mattermost.com/upgrade/welcome-email-to-end-users.html", "getting-started/organizing-conversations.html": "https://docs.mattermost.com/collaborate/organize-conversations.html", # Guides redirects "guides/administrator.html": "https://docs.mattermost.com/guides/deployment.html", +"guides/administration.html": + "https://docs.mattermost.com/guides/administration-guide.html", +"guides/deployment-guides.html": + "https://docs.mattermost.com/guides/deployment-guide.html", +"guides/deployment.html": + "https://docs.mattermost.com/guides/deployment-guide.html", +"guides/desktop-mobile-app-deployment.html": + "https://docs.mattermost.com/deploy/desktop/desktop-app-deployment.html", +"guides/get-started-with-administration.html": + "https://docs.mattermost.com/guides/administration-guide.html", +"guides/server-deployment.html": + "https://docs.mattermost.com/deploy/server/server-deployment-planning.html", +"guides/other-administration-resources.html": + "https://docs.mattermost.com/guides/administration-guide.html", +"guides/prepare-for-your-mattermost-deployment.html": + "https://docs.mattermost.com/deploy/server/server-deployment-planning.html", +"guides/self-hosted-administration.html": + "https://docs.mattermost.com/guides/administration-guide.html", "guides/administrator.html#mattermost-integrations": "https://developers.mattermost.com/integrate/getting-started/", +"guides/deployment.html#install-guides": + "https://docs.mattermost.com/guides/deployment-guide.html#server-application", "guides/administrator.html#installing-mattermost": - "https://docs.mattermost.com/guides/deployment.html#install-guides", + "https://docs.mattermost.com/guides/deployment-guide.html#server-application", "guides/channels.html#access-your-workspace": "https://docs.mattermost.com/collaborate/access-your-workspace.html", "guides/channels.html#work-with-messages": @@ -2258,9 +2324,9 @@ def setup(_: Sphinx): "guides/developer.html": "https://developers.mattermost.com/integrate/admin-guide/", "guides/install-deploy-upgrade-scale.html": - "https://docs.mattermost.com/guides/deployment.html", + "https://docs.mattermost.com/guides/deployment-guide.html", "guides/install-deploy-upgrade-scale.html#install-mattermost": - "https://docs.mattermost.com/guides/deployment.html#install-guides", + "https://docs.mattermost.com/guides/deployment-guide.html#server-application", "guides/integration.html": "https://developers.mattermost.com/integrate/getting-started/", "guides/setup-onboard-manage-comply.html": @@ -2294,6 +2360,10 @@ def setup(_: Sphinx): "https://docs.mattermost.com/guides/deployment.html#changelogs", "guides/changelogs.html": "https://docs.mattermost.com/about/releases-lifecycle.html", +"guides/administration.html": + "https://docs.mattermost.com/guides/administration-guide.html", +"guides/deployment.html": + "https://docs.mattermost.com/guides/deployment-guide.html", # Help redirects resulting from the June 2021 docs reorganization project. "help/apps/desktop-changelog.html": @@ -2402,18 +2472,74 @@ def setup(_: Sphinx): # Install redirects "install/config-cloudfront.html": "https://docs.mattermost.com/configure/configuring-cloudfront-to-host-mattermost-static-assets.html", +"install/desktop-app-managed-resources.html": + "https://docs.mattermost.com/deploy/desktop/desktop-app-managed-resources.html", +"install/desktop-custom-dictionaries.html": + "https://docs.mattermost.com/deploy/desktop/desktop-custom-dictionaries.html", +"install/desktop-msi-installer-and-group-policy-install.html": + "https://docs.mattermost.com/deploy/desktop/desktop-msi-installer-and-group-policy-install.html", +"install/setting-up-aws-elastic-beanstalk-docker.html": + "https://docs.mattermost.com/deploy/server/containers/install-aws-beanstalk.html", +"install/install-docker.html": + "https://docs.mattermost.com/deploy/server/containers/install-docker.html", +"install/installing-mattermost-omnibus.html": + "https://docs.mattermost.com/deploy/server/linux/deploy-omnibus.html", +"install/prepare-mattermost-mysql-database.html": + "https://docs.mattermost.com/deploy/server/prepare-mattermost-mysql-database.html", +"install/prepare-mattermost-database.html": + "https://docs.mattermost.com/deploy/server/preparations.html", +"install/setting-up-socket-based-mattermost-database.html": + "https://docs.mattermost.com/deploy/server/setting-up-socket-based-mattermost-database.html", +"install/setup-nginx-proxy.html": + "https://docs.mattermost.com/deploy/server/setup-nginx-proxy.html", +"install/setup-tls.html": + "https://docs.mattermost.com/deploy/server/setup-tls.html", +"install/setup-mattermost-server.html": + "https://docs.mattermost.com/deploy/server/deploy-linux.html", +"install/trouble-postgres.html": + "https://docs.mattermost.com/deploy/server/trouble-postgres.html", +"install/trouble_mysql.html": + "https://docs.mattermost.com/deploy/server/trouble_mysql.html", +"install/troubleshooting.html": + "https://docs.mattermost.com/deploy/server/troubleshooting.html", +"install/software-hardware-requirements.html": + "https://docs.mattermost.com/deploy/software-hardware-requirements.html", +"install/install-rhel.html": + "https://docs.mattermost.com/deploy/server/linux/deploy-rhel.html", +"install/install-tar.html": + "https://docs.mattermost.com/deploy/server/linux/deploy-tar.html", +"install/install-ubuntu.html": + "https://docs.mattermost.com/deploy/server/linux/deploy-ubuntu.html", +"install/install-kubernetes.html": + "https://docs.mattermost.com/deploy/server/kubernetes/deploy-k8s.html", +"install/install-kubernetes-aks.html": + "https://docs.mattermost.com/deploy/server/kubernetes/deploy-k8s-aks.html", +"install/cluster-transport-encryption.html": + "https://docs.mattermost.com/deploy/transport-encryption.html", +"install/database-transport-encryption.html": + "https://docs.mattermost.com/deploy/transport-encryption.html", +"install/config-tls-mattermost.html": + "https://docs.mattermost.com/deploy/transport-encryption.html", +"install/proxy-to-mattermost-transport-encryption.html": + "https://docs.mattermost.com/deploy/transport-encryption.html", +"install/transport-encryption.html": + "https://docs.mattermost.com/deploy/transport-encryption.html", +"install/deploy-bitnami.html": + "https://docs.mattermost.com/deploy/server/deploy-linux.html", +"install/enterprise-install-upgrade.html": + "https://docs.mattermost.com/upgrade/enterprise-install-upgrade.html", "install/config-apache2.html": "https://forum.mattermost.com/t/configuring-apache2-as-a-proxy-for-mattermost-server/11938", "install/deploy-bitnami.html": - "https://docs.mattermost.com/install/deploying-team-edition-on-bitnami.html", + "https://docs.mattermost.com/deploy/server/deploy-kubernetes.html", "install/desktop.html": "https://docs.mattermost.com/collaborate/install-desktop-app.html", "install/desktop-managed-resources.html": - "https://docs.mattermost.com/install/desktop-app-managed-resources.html", + "https://docs.mattermost.com/deploy/desktop/desktop-app-managed-resources.html", "install/desktop-msi-gpo.html": - "https://docs.mattermost.com/install/desktop-msi-installer-and-group-policy-install.html", + "https://docs.mattermost.com/deploy/desktop/desktop-msi-installer-and-group-policy-install.html", "install/docker-ebs.html": - "https://docs.mattermost.com/install/setting-up-aws-elastic-beanstalk-docker.html", + "https://docs.mattermost.com/deploy/server/containers/install-aws-beanstalk.html", "install/docker-local-machine.html": "https://docs.mattermost.com/install/setting-up-local-machine-using-docker.html", "install/ee-install.html": @@ -2463,11 +2589,11 @@ def setup(_: Sphinx): "install/deploy-cloudron.html": "https://forum.mattermost.com/", "install/desktop-custom-dictionaries.html#setting-up-the-dictionaries": - "https://docs.mattermost.com/install/desktop-custom-dictionaries.html#prepare-custom-dictionaries", + "https://docs.mattermost.com/deploy/desktop/desktop-custom-dictionaries.html#prepare-custom-dictionaries", "install/desktop-custom-dictionaries.html#configuring-the-desktop-app": - "https://docs.mattermost.com/install/desktop-custom-dictionaries.html#configure-the-desktop-app", + "https://docs.mattermost.com/deploy/desktop/desktop-custom-dictionaries.html#configure-the-desktop-app", "install/desktop-custom-dictionaries.html#removing-customized-dictionaries": - "https://docs.mattermost.com/install/desktop-custom-dictionaries.html#remove-custom-dictionaries", + "https://docs.mattermost.com/deploy/desktop/desktop-custom-dictionaries.html#remove-custom-dictionaries", "install/self-managed-changelog.html": "https://docs.mattermost.com/about/legacy-self-hosted-changelog.html", "install/legacy-self-hosted-changelog.html": @@ -2552,27 +2678,25 @@ def setup(_: Sphinx): "install/setup-mattermost-server.html": "https://docs.mattermost.com/install/install-tar.html", "install/common-prod-deploy-docker.html": - "https://docs.mattermost.com/install/install-docker.html", + "https://docs.mattermost.com/deploy/server/containers/install-docker.html", "install/common-deploy-faq.html": "https://docs.mattermost.com/install/install-tar.html", "install/install-rhel-nginx.html": - "https://docs.mattermost.com/install/setup-nginx-proxy.html", + "https://docs.mattermost.com/deploy/server/setup-nginx-proxy.html", "install/config-ssl-http2-nginx.html": - "https://docs.mattermost.com/install/setup-nginx-proxy.html#configure-nginx-with-ssl-and-http-2", + "https://docs.mattermost.com/deploy/server/setup-nginx-proxy.html#configure-nginx-with-ssl-and-http-2", "install/config-proxy-nginx.html": - "https://docs.mattermost.com/install/setup-nginx-proxy.html", + "https://docs.mattermost.com/deploy/server/setup-nginx-proxy.html", "install/install-nginx.html": - "https://docs.mattermost.com/install/setup-nginx-proxy.html", + "https://docs.mattermost.com/deploy/server/setup-nginx-proxy.html", "install/faq_kubernetes.html": - "https://docs.mattermost.com/install/install-kubernetes.html", + "https://docs.mattermost.com/deploy/server/kubernetes/deploy-k8s.html", "install/common-prod-deploy-tar.html": "https://docs.mattermost.com/install/install-tar.html", "install/common-prod-deploy-omnibus.html": "https://docs.mattermost.com/install/install-tar.html", "install/common-local-deploy-docker.html": "https://docs.mattermost.com/install/trial-mattermost-using-docker.html", -"install/config-mattermost-server.html": - "https://docs.mattermost.com/guides/get-started-with-administration.html", "install/install-rhel-8": "https://docs.mattermost.com/install/install-rhel.html", "install/install-rhel-8.html#download-the-latest-mattermost-server-tarball": @@ -2598,11 +2722,11 @@ def setup(_: Sphinx): "install/install-kubernetes.html#does-the-mattermost-operator-replace-the-mattermost-helm-chart": "https://docs.mattermost.com/install/install-kubernetes.html#frequently-asked-questions", "install/install-docker.html#deploy-mattermost-on-docker-for-production-use": - "https://docs.mattermost.com/install/install-docker.html#deploy-mattermost-on-docker-quick-start", + "https://docs.mattermost.com/deploy/server/containers/install-docker.html#deploy-mattermost-on-docker-quick-start", "install/install-docker.html#installing-a-different-version-of-mattermost": - "https://docs.mattermost.com/install/install-docker.html#install-a-different-version-of-mattermost", + "https://docs.mattermost.com/deploy/server/containers/install-docker.html#install-a-different-version-of-mattermost", "install/manage_kubernetes.html": - "https://docs.mattermost.com/install/install-kubernetes.html", + "https://docs.mattermost.com/deploy/server/kubernetes/deploy-k8s.html", # Integrations redirects. # The integrations directory and its contents have been archived in FY23 Q2 and all applicable content has been moved from docs.mm.com to developers.mm.com. @@ -2636,6 +2760,12 @@ def setup(_: Sphinx): # Manage redirects "manage/scripts.html": "https://forum.mattermost.com/t/scripts-for-performing-discreet-tasks/13527", +"manage/error-codes.html": + "https://docs.mattermost.com/manage/admin/error-codes.html", +"manage/generating-support-packet.html": + "https://docs.mattermost.com/manage/admin/generating-support-packet.html", +"manage/self-hosted-billing.html": + "https://docs.mattermost.com/manage/admin/self-hosted-billing.html", "manage/command-line-tools.html#mattermost-channel": "https://docs.mattermost.com/manage/mmctl-command-line-tool.html#mmctl-channel", "manage/command-line-tools.html#mattermost-channel-add": @@ -3235,25 +3365,25 @@ def setup(_: Sphinx): # Mobile redirects "mobile/deploy-mobile-apps-using-emm-provider.html": - "https://docs.mattermost.com/deploy/deploy-mobile-apps-using-emm-provider.html", + "https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html", "mobile/mobile-appstore-install.html": - "https://docs.mattermost.com/deploy/use-prebuilt-mobile-apps.html", + "https://docs.mattermost.com/deploy/mobile/mobile-app-deployment.html", "mobile/mobile-blackberry.html": - "https://docs.mattermost.com/deploy/deploy-mobile-apps-using-emm-provider.html", + "https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html", "mobile/mobile-compile yourself.html": - "https://docs.mattermost.com/deploy/build-custom-mobile-apps.html", + "https://docs.mattermost.com/deploy/mobile/distribute-custom-mobile-apps.html", "mobile/mobile-faq#how-do-push-notifications-work.html": - "https://docs.mattermost.com/deploy/mobile-faq.html#how-do-push-notifications-work", + "https://docs.mattermost.com/deploy/mobile/mobile-faq.html#how-do-push-notifications-work", "mobile/mobile-hpns.html": - "https://docs.mattermost.com/deploy/mobile-hpns.html", + "https://docs.mattermost.com/deploy/mobile/host-your-own-push-proxy-service.html", "mobile/mobile-mobileiron.html": - "https://docs.mattermost.com/deploy/build-custom-mobile-apps.html", + "https://docs.mattermost.com/deploy/mobile/distribute-custom-mobile-apps.html", "mobile/mobile-overview.html": - "https://docs.mattermost.com/deploy/mobile-overview.html", + "https://docs.mattermost.com/deploy/mobile/mobile-app-deployment.html", "mobile/mobile-overview.html#use-an-emm-provider-with-managed-app-configuration": - "https://docs.mattermost.com/deploy/deploy-mobile-apps-using-emm-provider.html", + "https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html", "mobile/mobile-testing-notifications.html": - "https://docs.mattermost.com/deploy/mobile-testing-notifications.html", + "https://docs.mattermost.com/deploy/mobile/mobile-troubleshooting.html", # Onboard redirects "onboard/ad-ldap.html#active-directory-ldap-setup-e10-e20": @@ -3636,6 +3766,8 @@ def setup(_: Sphinx): # Upgrade redirects "upgrade/upgrading-mattermost-server.html#prepare-to-upgrade-to-the-latest-version": "https://docs.mattermost.com/upgrade/prepare-to-upgrade-mattermost.html", +"upgrade/installing-license-key.html": + "https://docs.mattermost.com/manage/admin/installing-license-key.html", "upgrade/upgrading-mattermost-server.html#upgrade-to-mattermost-v7-0": "https://docs.mattermost.com/upgrade/prepare-to-upgrade-mattermost.html#upgrade-to-mattermost-v7-0", "upgrade/upgrading-mattermost-server.html#upgrade-to-mattermost-v6-7": @@ -3757,9 +3889,9 @@ def setup(_: Sphinx): "welcome/manage-multiple-server-connections.html": "https://docs.mattermost.com/preferences/connect-multiple-workspaces.html", "welcome/what-changed-in-v70.html": - "https://docs.mattermost.com/guides/deployment.html#changelogs", + "https://docs.mattermost.com/about/mattermost-v10-changelog.html", "welcome/what-changed-in-v60.html": - "https://docs.mattermost.com/guides/deployment.html#changelogs", + "https://docs.mattermost.com/about/mattermost-v9-changelog.html", "welcome/whats-new-in-v72.html": "https://github.com/mattermost/focalboard/blob/main/docs/focalboard-plugin-end-user-guide.md", "welcome/keyboard-shortcuts.html#navigation-shortcuts-in-the-desktop-app": diff --git a/source/deploy/bleve-search.rst b/source/configure/bleve-search.rst similarity index 100% rename from source/deploy/bleve-search.rst rename to source/configure/bleve-search.rst diff --git a/source/configure/calls-deployment.md b/source/configure/calls-deployment.md index c8904a63009..f69c47e0af8 100644 --- a/source/configure/calls-deployment.md +++ b/source/configure/calls-deployment.md @@ -24,7 +24,7 @@ This document provides information on how to successfully make the Calls plugin ### Server -- Run Mattermost server on a secure (HTTPs) connection. This is a necessary requirement on the client to allow capturing devices (e.g., microphone, screen). See the [config TLS](https://docs.mattermost.com/install/config-tls-mattermost.html) section for more info. +- Run Mattermost server on a secure (HTTPs) connection. This is a necessary requirement on the client to allow capturing devices (e.g., microphone, screen). See the [config TLS](https://docs.mattermost.com/deploy/server/setup-tls.html) section for more info. - See [network requirements](#network) below. ### Client diff --git a/source/configure/configuration-settings.rst b/source/configure/configuration-settings.rst index 4934c84b441..4c4869d79cf 100644 --- a/source/configure/configuration-settings.rst +++ b/source/configure/configuration-settings.rst @@ -11,6 +11,25 @@ System admins for both self-hosted and Cloud Mattermost deployments can manage M - In self-hosted Mattermost deployments, configuration settings are maintained in the ``config.json`` configuration file, located in the ``mattermost/config`` directory, or :doc:`stored in the database `. System admins managing self-hosted deployments can also modify the ``config.json`` file directly using a text editor. - Mattermost requires write permissions to the ``config.json`` file; otherwise, configuration changes made within the System Console will have no effect. +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Self-hosted workspace edition and license settings + Cloud workspace subscription, billing, and account settings + Reporting configuration settings + User management configuration settings + Environment configuration settings + Site configuration settings + Authentication configuration settings + Plugins configuration settings + Integrations configuration settings + Compliance configuration settings + Experimental configuration settings + Deprecated configuration settings + Bleve search + Mattermost configuration settings are organized into the following categories within the System Console: - :doc:`Self-hosted workspace edition and license settings ` @@ -24,6 +43,8 @@ Mattermost configuration settings are organized into the following categories wi - :doc:`Integrations configuration settings ` - :doc:`Compliance configuration settings ` - :doc:`Experimental configuration settings ` +- :doc:`Deprecated configuration settings ` +- :doc:`Bleve search ` Configuration in database -------------------------- diff --git a/source/configure/configuring-cloudfront-to-host-mattermost-static-assets.rst b/source/configure/configuring-cloudfront-to-host-mattermost-static-assets.rst index 2976098446d..f4eea11dc42 100644 --- a/source/configure/configuring-cloudfront-to-host-mattermost-static-assets.rst +++ b/source/configure/configuring-cloudfront-to-host-mattermost-static-assets.rst @@ -1,7 +1,5 @@ -.. _config-cloudfront: - -Configuring CloudFront to host Mattermost static assets -======================================================= +(Optional) Configuring CloudFront to host Mattermost static assets +================================================================== .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: diff --git a/source/configure/customizing-mattermost.rst b/source/configure/customize-mattermost.rst similarity index 94% rename from source/configure/customizing-mattermost.rst rename to source/configure/customize-mattermost.rst index 49d1ca1a821..3a639214c39 100644 --- a/source/configure/customizing-mattermost.rst +++ b/source/configure/customize-mattermost.rst @@ -45,10 +45,10 @@ The Mattermost mobile apps can be customized if you choose to build the apps you To brand the mobile apps: -1. Fork the `mattermost-mobile `_ repository -2. Replace the name, images, and any key text strings -3. :doc:`Compile the apps <../deploy/build-custom-mobile-apps>` -4. Deploy the apps to an app store +1. Fork the `mattermost-mobile `_ repository. +2. Replace the name, images, and any key text strings. +3. Compile the custom apps. +4. Deploy the apps to an app store. While most organizations deploy to internal enterprise app stores, you are welcome to deploy to iTunes and Google Play as long as the branding is not confusable with official Mattermost products. diff --git a/source/configure/enable-copilot.rst b/source/configure/enable-copilot.rst index e52c51800bf..f7e24631471 100644 --- a/source/configure/enable-copilot.rst +++ b/source/configure/enable-copilot.rst @@ -1,5 +1,5 @@ -Enable Copilot -============== +(Recommended) Enable Copilot +============================ .. include:: ../_static/badges/allplans-cloud-selfhosted.rst :start-after: :nosearch: diff --git a/source/configure/enabling-chinese-japanese-korean-search.rst b/source/configure/enabling-chinese-japanese-korean-search.rst index 320064f5f7d..9a3f5fd225f 100644 --- a/source/configure/enabling-chinese-japanese-korean-search.rst +++ b/source/configure/enabling-chinese-japanese-korean-search.rst @@ -8,7 +8,7 @@ Chinese, Japanese and Korean search Enabling search for Chinese, Japanese and Korean (CJK) requires special configuration, since these languages do not contain spaces. -See :doc:`database requirements documentation ` for how to set up search for these languages. +See :doc:`database requirements documentation ` for how to set up search for these languages. Below is additional information on how to configure the database for different languages. @@ -112,9 +112,9 @@ Below is additional information on how to configure the database for different l Mattermost で日本語検索をするためにはデータベースの設定変更が必要です -- :ref:`MySQL ` +- :ref:`MySQL ` -- :ref:`Postgres ` +- :ref:`Postgres ` 日本語(CJK)検索設定のドキュメントの改善にご協力ください diff --git a/source/configure/environment-configuration-settings.rst b/source/configure/environment-configuration-settings.rst index 119c20f5e80..38eb121511f 100644 --- a/source/configure/environment-configuration-settings.rst +++ b/source/configure/environment-configuration-settings.rst @@ -148,7 +148,7 @@ Web server connection security | connection. | | | - **TLS**: Encrypts the communication between Mattermost | | | clients and your server. See the :doc:`configuring TLS on | | -| Mattermost ` for more details. | | +| Mattermost ` for details. | | +-----------------------------------------------------------------------+-----------------------------------------------------------------------+ .. config:setting:: tls-certificate-file @@ -200,7 +200,8 @@ Use Let's Encrypt +-----------------------------------------------------------------------------------------------+--------------------------------------------------------------------------+ | Enable the automatic retrieval of certificates from Let’s Encrypt. | - System Config path: **Environment > Web Server** | -| See the :doc:`configuring TLS on Mattermost documentation ` | - ``config.json`` setting: ``".ServiceSettings.UseLetsEncrypt: false",`` | +| See the :doc:`configuring TLS on Mattermost documentation | - ``config.json`` setting: ``".ServiceSettings.UseLetsEncrypt: false",`` | +| ` | | | for more details on setting up Let’s Encrypt. | - Environment variable: ``MM_SERVICESETTINGS_USELETSENCRYPT`` | | | | | - **true**: The certificate will be retrieved when a client | | @@ -365,7 +366,7 @@ Managed resource paths +--------------------------------------------------------+-------------------------------------------------------------------------+ | **Note:** | | When using the Mattermost Desktop App, additional configuration is required to open the link within the Desktop App instead of | -| in a browser. See the :doc:`desktop managed resources ` | +| in a browser. See the :doc:`desktop managed resources ` | | documentation for details. | +--------------------------------------------------------+-------------------------------------------------------------------------+ @@ -761,7 +762,7 @@ Data source | } | | | | **Note**: If you’re using MySQL 8.0 or later, the default collation has changed to ``utf8mb4_0900_ai_ci``. See our | -| :doc:`Database Software Requirements ` documentation for details on MySQL 8.0 support. | +| :doc:`Database Software Requirements ` documentation for details on MySQL 8.0 support. | | | | **To use TLS with MySQL databases** | | | @@ -962,7 +963,7 @@ Disable database search | Search behavior in Mattermost depends on which search engines are enabled. | | | | - When :doc:`Elasticsearch ` is enabled, Mattermost will try to use it first. | -| - If Elasticsearch fails or is disabled, Mattermost will attempt to use :doc:`Bleve `, if enabled. If this occurs, | +| - If Elasticsearch fails or is disabled, Mattermost will attempt to use :doc:`Bleve `, if enabled. If this occurs, | | you will see the warning ``Encountered error on SearchPostsInTeamForUser.`` | | - If both Elasticsearch and Bleve fail or are disabled, Mattermost tries to search the database directly, if this is enabled. | | - If all of the above methods fail or are disabled, the search results will be empty. | @@ -2075,7 +2076,7 @@ Enable searching content of documents within ZIP files +---------------------------------------------------------------+----------------------------------------------------------------------------------------+ | **Note**: Document content search within ZIP files is available, with mobile support coming soon. | | Searching document contents adds load to your server. For large deployments, or teams that share many large, text-heavy documents, | -| we recommend you review our :ref:`hardware requirements `, | +| we recommend you review our :ref:`hardware requirements `, | | and test enabling this feature in a staging environment before enabling it in a production environment. | +---------------------------------------------------------------+----------------------------------------------------------------------------------------+ @@ -2448,7 +2449,7 @@ Enable image proxy | external images. | | | - **false**: **(Default)** Disables the image proxy. | | +---------------------------------------------------------------+---------------------------------------------------------------------+ -| See the :doc:`image proxy ` documentation to learn more. | +| See the :doc:`image proxy ` documentation to learn more. | +---------------------------------------------------------------+---------------------------------------------------------------------+ .. config:setting:: image-proxy-type @@ -2471,7 +2472,7 @@ Image proxy type | as the image proxy. | | | - **atmos/camo**: An external atmos/camo image proxy is used. | | +---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| See the :doc:`image proxy ` documentation to learn more. | +| See the :doc:`image proxy ` documentation to learn more. | +---------------------------------------------------------------+-------------------------------------------------------------------------------+ .. config:setting:: remote-image-proxy-url @@ -2505,7 +2506,7 @@ Remote image proxy options | This setting isn't needed when using the **local** image | - ``config.json setting``: ``".ImageProxySettings.RemoteImageProxyOptions",`` | | proxy type. | - Environment variable: ``MM_IMAGEPROXYSETTINGS_REMOTEIMAGEPROXYOPTIONS`` | +---------------------------------------------------------------+-------------------------------------------------------------------------------+ -| See the :doc:`image proxy ` documentation to learn more. | +| See the :doc:`image proxy ` documentation to learn more. | +---------------------------------------------------------------+-------------------------------------------------------------------------------+ ---- @@ -3448,7 +3449,7 @@ Session idle timeout .. note:: - This setting has no effect when `extend session length with activity <#extend-session-length-with-activity>`__ is set to **true**. - - This setting applies to the webapp and the desktop app. For mobile apps, use an :doc:`EMM provider ` to lock the app when not in use. | + - This setting applies to the webapp and the desktop app. For mobile apps, use an :doc:`EMM provider ` to lock the app when not in use. | - In :doc:`high availability mode `, enable IP hash load balancing for reliable timeout measurement. ---- @@ -3612,7 +3613,7 @@ Allow untrusted internal connections | | | - Integrations using webhooks, slash commands, or message actions. This prevents them from requesting endpoints within the local network. | | - Link previews. When a link to a local network address is posted in a chat message, this prevents a link preview from being displayed. | -| - The local :doc:`image proxy `. If the local image proxy is enabled, images located on | +| - The local :doc:`image proxy `. If the local image proxy is enabled, images located on | | the local network cannot be used by integrations or posted in chat messages. | +-----------------------------------------------+-----------------------------------------------------------------------------------------------+ | | diff --git a/source/configure/push-notification-server-configuration-settings.rst b/source/configure/push-notification-server-configuration-settings.rst index 0adc9582896..a778cebce4f 100644 --- a/source/configure/push-notification-server-configuration-settings.rst +++ b/source/configure/push-notification-server-configuration-settings.rst @@ -1,7 +1,7 @@ :orphan: :nosearch: -Configure Mattermost to enable push notifications to Mattermost clients by going to **System Console > Environment > Push Notification Server**, or by editing the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. +Configure mobile push notifications for Mattermost by going to **System Console > Environment > Push Notification Server**, or by editing the ``config.json`` file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect. .. config:setting:: enable-push-notifications :displayname: Enable push notifications (Push Notifications) @@ -9,8 +9,10 @@ Configure Mattermost to enable push notifications to Mattermost clients by going :configjson: .EmailSettings.SendPushNotifications :environment: MM_EMAILSETTINGS_SENDPUSHNOTIFICATIONS - - **true**: **(Default)** Your Mattermost server sends mobile push notifications. - - **false**: Mobile push notifications are disabled. + - **Do not send push notifications**: Mobile push notifications are disabled. + - **Use HPNS connection with uptime SLA to send notifications to iOS and Android apps**: **(Default)** Use Mattermost's hosted push notification service. + - **Use TPNS connection to send notifications to iOS and Android apps**: Use Mattermost's test push notification service. + - **Manually enter Push Notification Service location**: When building your own custom mobile apps, you must host your own mobile push proxy service, and specify that URL in the Push Notification Server field. Enable push notifications ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -32,13 +34,39 @@ Enable push notifications | **Push Notification Server** field. | | +------------------------------------------------------------------+--------------------------------------------------------------------------------+ -.. note:: +Hosted Push Notifications Service (HPNS) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_static/badges/ent-pro-cloud-selfhosted.rst + :start-after: :nosearch: + +Mattermost Enterprise, Professional, and Cloud customers can use Mattermost's Hosted Push Notification Service (HPNS). The HPNS offers: + +- Access to a publicly-hosted Mattermost Push Notification Service (MPNS) `available on GitHub. `__ +- An explicit `privacy policy `__ for the contents of unencrypted messages. +- Encrypted TLS connections: + + - Between HPNS and Apple Push Notification Services + - Between HPNS and Google’s Firebase Cloud Messaging Service + - HPNS and your Mattermost Server +- Production-level uptime expectations. +- Out-of-box configuration for new servers means nothing is required to enable HPNS for new deployments. HPNS can be `enabled for existing deployments <#enable-hpns-for-existing-deployments>`_. - - Mattermost Enterprise, Professional, and Cloud customers can use Mattermost’s SLA-bound :ref:`Hosted Push Notification Service (HPNS) ` in one of two locations, including the United States and Germany. - - Mattermost Team Edition customers can use Mattermost's :ref:`Test Push Notification server (TPNS) `. - - The TPNS is provided for testing push notifications prior to compiling your own service, and isn't available for Mattermost Cloud deployments. Ensure you’re familiar with its limitations. - - Review the :doc:`mobile push notifications ` and :doc:`mobile apps ` documentation, including guidance on compiling your own mobile apps and MPNS, before deploying to production. See the :ref:`documentation ` for details on hosting your own push proxy service. - - To confirm push notifications are working, connect to the `Mattermost iOS App `__ available on the App Store, or the `Mattermost Android App `__ available on Google Play. +.. note:: + - The HPNS only works with pre-built apps Mattermost deploys through the Apple App Store and Google Play Store. If you build your own mobile apps, you must also `host your own Mattermost push proxy server <#host-your-own-push-proxy-service>`_. + - You must ensure that the push proxy can be reached on the correct port. For HPNS, it's port 443 from the Mattermost server. + - Mattermost doesn't store any notification data. Any data being stored is at the server level only, such as the ``device_id``, since the HPNS needs to know which device the notification must be sent to. + +Test Push Notifications Service (TPNS) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Non-commercial and self-hosted customers can use Mattermost's free, basic Test Push Notifications Service (TPNS). + +.. note:: + - The TPNS isn’t recommended for use in production environments, and doesn’t offer production-level update service level agreements (SLAs). + - The TPNS isn't available for Mattermost Cloud deployments. + - The TPNS only works with the pre-built mobile apps that Mattermost deploys through the Apple App Store and Google Play Store. If you have built your own mobile apps, you must also `host your own Mattermost push proxy service <#host-your-own-push-proxy-service>`_. + - You must ensure that the push proxy can be reached on the correct port. For TPNS, it's port 80 from the Mattermost server. - If you don't need or want Mattermost to send mobile push notifications, disabling this configuration setting in larger deployments may improve server performance in the following areas: - Reduced Processing Load: Generating and sending push notifications requires processing power and resources. By disabling them, the server can allocate those resources to other tasks. @@ -48,6 +76,23 @@ Enable push notifications - Simplified Error Handling: Push notification services can sometimes fail or have latency issues, requiring additional error handling. Disabling these notifications simplifies the system's operations. - However, disabling push notifications can negatively impact user experience, communication efficiency, and overall productivity. It’s important to balance performance improvements with the needs of your organization and users. +ID-only push notifications +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. include:: ../_static/badges/ent-cloud-selfhosted.rst + :start-after: :nosearch: + +Admins can enable mobile notifications to be fully private to protect a Mattermost customer against breaches in iOS and Android notification infrastructure by limiting the data sent to Apple and Google through a Mattermost configuration setting. + +The standard way to send notifications to iOS and Android applications requires sending clear text messages to Apple or Google so they can be forwarded to a user’s phone and displayed on iOS or Android. While Apple or Google assure the data is not collected or stored, should the organizations be breached or coerced, all standard mobile notifications on the platform could be compromised. + +To avoid this risk, Mattermost can be configured to replace mobile notification text with message ID numbers that pass no information to Apple of Google. When received by the Mattermost mobile application on a user’s phone, the message IDs are used to privately communicate with their Mattermost server and to retrieve mobile notification messages over an encrypted channel. This means that, at no time, is the message text visible to Apple or Google’s message relay system. The contents of the message also won't reach Mattermost. + +.. note:: + Because of the extra steps to retrieve the notifications messages under Mattermost’s private mobility capability with ID-only push notifications, end users may experience a slight delay before the mobile notification is fully displayed compared to sending clear text through Apple and Google’s platform. + +See our :ref:`configuration settings ` documentation to learn more about the ID-only push notifications configuration setting. See our :ref:`Mobile Apps FAQ documentation ` for details on using ID-only push notifications for data privacy. + .. config:setting:: push-notification-server-location :displayname: Push notification server location (Push Notifications) :systemconsole: Environment > Push Notification Server diff --git a/source/configure/self-hosted-account-settings.rst b/source/configure/self-hosted-account-settings.rst index 651dee24e0b..1f0cf54a7c0 100644 --- a/source/configure/self-hosted-account-settings.rst +++ b/source/configure/self-hosted-account-settings.rst @@ -22,6 +22,6 @@ You can also review and manage the following aspects of your self-hosted deploym - View the :doc:`edition ` of your Mattermost self-hosted deployment. - Manage your :doc:`product subscription `. -- :doc:`Upload a new license `. +- :doc:`Upload a new license `. - Remove a license to :doc:`downgrade the server `. - Talk to a `Mattermost Expert `_ for assistance. \ No newline at end of file diff --git a/source/configure/smtp-email.rst b/source/configure/smtp-email.rst index ceee3356ef7..f6b92e61440 100644 --- a/source/configure/smtp-email.rst +++ b/source/configure/smtp-email.rst @@ -23,7 +23,7 @@ Any SMTP email service can be used. You need a copy of the following information Alternatively, you can use one of the `services listed below <#sample-smtp-settings>`__, or can set up local ``sendmail`` by setting **Server Name** ``127.0.0.1`` with **Port** ``25``. - If deploying Mattermost using :doc:`Docker `, the standard docker ``172.16.0.0/12`` IP range isn't used. Specify the IP range ``192.168.0.0/24`` to the email service to avoid relay access errors. If using postfix, under ``/etc/postfix/main.cf``, specify ``mynetworks = 192.168.0.0/24``. This may vary depending on how Mattermost is deployed. Ensure that **Port 25** is open if a firewall is present. + If deploying Mattermost using :doc:`Docker `, the standard docker ``172.16.0.0/12`` IP range isn't used. Specify the IP range ``192.168.0.0/24`` to the email service to avoid relay access errors. If using postfix, under ``/etc/postfix/main.cf``, specify ``mynetworks = 192.168.0.0/24``. This may vary depending on how Mattermost is deployed. Ensure that **Port 25** is open if a firewall is present. Configure SMTP settings ------------------------ diff --git a/source/configure/using-outbound-proxy.rst b/source/configure/using-outbound-proxy.rst index 921aa73ebf0..3411a6e0531 100644 --- a/source/configure/using-outbound-proxy.rst +++ b/source/configure/using-outbound-proxy.rst @@ -1,12 +1,10 @@ -.. _outbound_proxy: - -Using an outbound proxy -======================= +(Optional) Using an outbound proxy +================================== .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -In some scenarios, you may wish to use Mattermost behind a proxy. This can be used to do things such as monitoring outbound traffic from Mattermost or controlling which websites can appear in link previews and other embedded content. If you only want to use a proxy for images, the :doc:`image proxy ` is also an option. +In some scenarios, you may wish to use Mattermost behind a proxy. This can be used to do things such as monitoring outbound traffic from Mattermost or controlling which websites can appear in link previews and other embedded content. If you only want to use a proxy for images, the :doc:`image proxy ` is also an option. Configuration ------------- diff --git a/source/deploy/application-architecture.rst b/source/deploy/application-architecture.rst new file mode 100644 index 00000000000..9d72a28e2d3 --- /dev/null +++ b/source/deploy/application-architecture.rst @@ -0,0 +1,180 @@ +Application architecture +========================= + +Mattermost is an open-source collaboration platform that offers secure messaging, file sharing, and integrations for team communication. It's self-hosted, providing IT admins full control over data, security, integrations, and customization. The platform is built with modular components to ensure scalability, flexibility, and extensibility. + +.. image:: ../images/network-diagram.svg + :alt: Mattermost network diagram shows how the components can be deployed. Includes optional configurations for scaling for larger enterprise organizations. + :class: bg-white + +Workflow overview +----------------- + +Users connect through various access points (web, mobile, desktop, email). Their requests are processed by the application layer (Mattermost Server), which manages API communications, authentication, notifications, and data workflows. + +The backend infrastructure supports these operations by storing all data and files in well-architected storage systems. + +Extendability and security layers ensure that the platform integrates seamlessly with enterprise systems while protecting sensitive data. + +Core components +---------------- + +The technical architecture revolves around 3 main layers: `Access layer <#access-layer>`__, `Application layer <#application-layer>`__, and `Backend infrastructure <#backend-infrastructure>`__. + +Access layer +~~~~~~~~~~~~ + +The Access Layer includes all the ways users interact with Mattermost, ensuring secure, scalable, and reliable communication across preferred platforms. High availability measures provide uninterrupted functionality for users, even in the face of server or network failures. + +- **Web Interface**: Users can access Mattermost through a web browser (Chrome, Firefox, Safari, Edge). The web client communicates with the Mattermost server over HTTPS protocols. High availability for web interfaces can be achieved through load-balanced reverse proxies (e.g., NGINX or HAProxy) that distribute user traffic across multiple Mattermost server instances. Backup proxy servers can ensure failover scenarios to keep the web interface operational during outages. +- **Desktop and Mobile Apps**: Native apps for iOS, Android, macOS, Windows, and Linux provide seamless functionality across devices. These apps rely on secure APIs to interact with the server for real-time messaging and updates. High availability can be ensured by deploying redundant server clusters to handle API requests, along with failover mechanisms that automatically redirect traffic to healthy servers. Mobile apps also benefit from retry mechanisms and fallback services for push notifications to maintain real-time responsiveness. +- **Email Interaction**: Support for email clients like Outlook, Gmail, or Thunderbird enables integration of email notifications (e.g., new message alerts, invitations) into users' typical workflows. The Access Layer ensures that users are always connected via platforms of their choice while maintaining secure, synchronized communication paths. Email services can be configured with multiple SMTP servers for redundancy, ensuring that notifications are sent without delay even if a primary mail server becomes unavailable. + +The Access Layer plays a critical role in ensuring that users are always connected via the platforms of their choice while maintaining secure, synchronized communication paths. With high availability measures in place, organizations can guarantee a seamless user experience, regardless of the scale or complexity of their deployment. + +Application layer +~~~~~~~~~~~~~~~~~ + +The Mattermost Server is the heart of the platform and responsible for processing all user and system operations. It's composed of multiple modular elements as follows: + +.. image:: ../images/architecture_basics.png + :alt: Mattermost architecture basics + :class: bg-white + +**RESTful JSON Web Service**: Handles all incoming API requests (from web clients, apps, and integrations) and ensures that responses are formatted in JSON. Acts as the communication bridge between the clients (Access Layer) and backend systems. To ensure high availability, this layer can be distributed across multiple servers and load-balanced, preventing service disruptions due to high traffic or server failure. + +**Authentication client**: Manages user authentication, ensuring secure login sessions. Integrates with traditional username/password-based authentication or enterprise-grade solutions like SSO (Single Sign-On) through Active Directory/LDAP. High availability is maintained through redundant authentication nodes and failover mechanisms, ensuring uninterrupted access even if a primary authentication service fails. + +**Authentication Provider**: Provides pluggable authentication frameworks to support OAuth, SSO, and third-party identity services. Particularly important for enterprise environments with centralized identity management. Redundancy and failover strategies ensure reliability by distributing authentication frameworks across multiple servers and offering fallback options for seamless identity management. + +**Notification Service**: Sends notifications through supported mediums: + +- **Push Notifications**: Real-time notifications to iOS and Android devices (via a Push Notification Service). High availabilty is ensured through multiple notification servers and retry mechanisms, guaranteeing that notifications are delivered even in the event of service disruptions. +- **Email Notifications**: Delivered to users when they are offline or need event alerts. Load balancing and backup mail server configurations help ensure email delivery remains consistent and reliable. + +**Data Management Service**: Responsible for managing message data, metadata, user profiles, and logs. Ensures the integrity of data passed between the database and the server. This layer serves as the operational core of the platform, orchestrating user activities with data handling and integration capabilities. + +High availability is achieved through database replication, failover strategies, and distributed data handling mechanisms. These measures ensure uninterrupted access to data and protect against component failures or downtime. The Data Management Service serves as the operational core of the platform, orchestrating user activities with scalable and fault-tolerant data handling capabilities. + +Backend infrastructure +~~~~~~~~~~~~~~~~~~~~~~ + +The backend infrastructure provides the storage and data handling capabilities required for Mattermost operations. It consists of the following components: + +**Database Systems**: Mattermost uses PostgreSQL as its primary database (supports Amazon RDS for cloud-hosted PostgreSQL) to store all persistent data, such as: + +- Messages +- User accounts and credentials +- Configuration settings +- Team/channel metadata + +To ensure high availability, database systems can leverage clustering, replication, and failover mechanisms. PostgreSQL supports features like synchronous and asynchronous replication to create replicas for redundancy. Cloud-hosted solutions like Amazon RDS provide automatic failover and backup capabilities, ensuring continuous operation during system failures. + +**File Storage**: Manages all multimedia assets (e.g., file uploads, images, videos) shared across channels. Storage solutions include the following options: + +- **Local Storage**: Files stored directly on the server’s filesystem. For high availability, redundancy can be achieved using RAID configurations or backups to recover from disk failures. +- **Network Attached Storage (NAS)**: Common for enterprises centralizing file storage within their network. NAS setups can include fault-tolerant configurations like distributed systems or replication for uninterrupted access. +- **S3**: Offers cloud-based scalable storage for larger environments or organizations with distributed deployments. The database and file storage handle scalability, ensuring efficient support for millions of messages and files while guaranteeing data consistency. S3 inherently supports high availability by distributing data across multiple availability zones, ensuring no single point of failure. + +High availability measures ensure scalable and fail-safe support for millions of messages and files while guaranteeing data consistency. + +**System Extensions**: Mattermost is not only a collaboration tool but also a platform designed for extensibility. Key extensibility features include: + +**Self-Hosted Integrations**: Connect Mattermost to other local or cloud-based systems like Jira, GitLab, or any custom integrations your team needs. Leverage built-in APIs and webhooks to automate workflows and trigger system-to-system communications. For high availaiblity, integrations can employ redundant communication channels and retry mechanisms to handle transient failures gracefully. + +**Third-Party Authentication**: Bind integrations to third-party platforms (e.g., Slack-importing APIs, OAuth services). Third-party identity services ensure consistent and secure user access flows. Third-party identity services can leverage load-balancing and failover strategies to ensure consistent and secure user access flows, even under high traffic or outages. + +**Security and Scalability Features**: Security and scalability are baked into the architecture, making Mattermost ideal for enterprise use cases: + +**Security** + +- A reverse proxy like NGINX or a hardware proxy is deployed to manage external traffic. It protects servers, enforces HTTPS, and handles load balancing. +- Configurable SSL/TLS encryption ensures data security during transmission. +- Granular user permissions and roles secure sensitive information within teams. + +**Scalability and High Availability**: The Enterprise Edition supports deploying multiple Mattermost servers in a clustered environment to balance user requests across multiple servers for reliability and performance in large organizations. Clustering ensures automatic failover so that user traffic is shifted to functioning servers in case of outages. + +**Notifications and communication services**: Mattermost supports asynchronous and real-time communication, enhanced by notification systems tailored for different workflows: + +- **Push Notifications**: Delivered to mobile devices for message alerts or mentions. High availability is achieved with backup notification services and retry mechanisms for reliable delivery. +- **Email Integration**: Provides regular notifications when users are offline or inactive. Failover mail servers and distributed configurations ensure email notifications are sent without interruption. + +These services ensure continuous engagement and communication. + +Communication protocols +~~~~~~~~~~~~~~~~~~~~~~~ + +There are also communication protocols (HTTPS and WS) that define the type of connection the user makes with the Mattermost server. High availability measures ensure reliable and resilient connections between clients and the Mattermost server, especially in production environments. + +**HTTPS Connection** (Secure Hypertext Transfer Protocol) + +- HTTPS connections to the Mattermost server render pages and provide access to core platform functionality, but do not include real-time interactivity (which is enabled by WSS connections). +- HTTPS is a secure, encrypted protocol and is highly recommended for production. Unencrypted HTTP connections may be used in initial testing and configuration, but should never be used in a production environment. For high availability, HTTPS traffic should be handled by a reverse proxy (e.g., NGINX or HAProxy) with load balancer configurations to distribute connections across multiple Mattermost server instances. Redundant proxy servers ensure failover capabilities, providing uninterrupted service. + +**WSS Connection** (Secure WebSocket Protocol) + +Secure WebSocket (WSS) connections to the Mattermost Server enable real-time updates and notifications between clients and the server. + +If a WSS connection is not available and HTTPS is substituted, the system will appear to work but real-time updates and notifications will not. In this mode of operation, updates will only appear on a page refresh. WSS has a persistent connection to the Mattermost server when a client is connected, while HTTPS has an intermittent connection and only connects to the server when a page or file is requested. + +High availability for WSS connections can be achieved through clustering Mattermost servers and load balancing WebSocket connections across those cluster nodes. Proxy servers and WebSocket-specific configurations (such as sticky sessions or connection persistence) are essential to maintain real-time interactivity during server or network failures. + +.. image:: ../images/architecture_with_protocol.png + :alt: Mattermost architecture with protocol connections + :class: bg-white + +By incorporating high availability strategies into communication protocols, the platform ensures secure, scalable, and reliable connections for both regular user interactions (via HTTPS) and real-time updates (via WSS). These measures are critical for mission-critical environments and distributed deployments where continuous communication is necessary. + +**Behind a VPN** + +Mattermost is intended to be installed within a private network which can offer multiple factors of authentication, including secure access to computing devices and physical locations. If outside access is required, a virtual private network client (VPN), such as `OpenVPN `__, with additional authentication used to connect to Mattermost for web, desktop, and mobile experiences, is recommended. + +**Non-VPN setup** + +If Mattermost is accessible from the open internet, the following is recommended: + +1. An IT admin should be assigned to set up appropriate network security, subscribe to `the Mattermost security bulletin `__, and :doc:`apply new security updates `. +2. The organization enables :doc:`SAML Single Sign-on ` or enable :doc:`MFA `. + +If Mattermost is accessible from the open internet with no VPN or MFA set up, we recommended using it only for non-confidential, unimportant conversations where impact of a compromised system is not essential. + +Mattermost services ports +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following table lists the Mattermost services ports for Mattermost Server, push proxy, and mobile app clients. System admins with clients that need to speak to the Mattermost server without a proxy can open specific firewall ports as needed. + +**Mattermost Server** + ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| Service Name | Config Setting | Port (default) | Protocol | Direction | Info | ++=============================================================+=======================================+===================================+===========+============+===============================================================+ +| HTTP/Websocket | ServiceSettings.ListenAddress | 8065/80/443 (TLS) | TCP | Inbound | External (no proxy) / Internal (with proxy) | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+ Usually this requires port 80 and 443 when running HTTPS. | +| | | | | | | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| Cluster | ClusterSettings.GossipPort | 8074 | TCP/UDP | Inbound | Internal | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| Metrics | MetricsSettings.ListenAddress | 8067 | TCP | Inbound | External (no proxy) / Internal (with proxy) | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| Database | SqlSettings.DataSource | 5432 (PostgreSQL) / 3306 (MySQL) | TCP | Outbound | Usually internal (recommended) | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| LDAP | LdapSettings.LdapPort | 389 | TCP/UDP | Outbound | | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| S3 Storage | FileSettings.AmazonS3Endpoint | 443 (TLS) | TCP | Outbound | | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| SMTP | EmailSettings.SMTPPort | 10025 | TCP/UDP | Outbound | | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ +| Push Notifications | EmailSettings.PushNotificationServer | 443 (TLS) | TCP | Outbound | | ++-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ + +**Push Proxy** + ++---------------+-----------------+-----------------+-----------+------------+----------------------------------------------+ +| Service Name | Config Setting | Port (default) | Protocol | Direction | Info | ++===============+=================+=================+===========+============+==============================================+ +| Push Proxy | ListenAddress | 8066 | TCP | Inbound | External (no proxy) / Internal (with proxy) | ++---------------+-----------------+-----------------+-----------+------------+----------------------------------------------+ + +**Mobile Clients** + +To receive push notifications, your network must allow traffic on `port 5223 for iOS devices `_ and `ports 5228-5230 for Android `_. \ No newline at end of file diff --git a/source/deploy/build-custom-mobile-apps.rst b/source/deploy/build-custom-mobile-apps.rst deleted file mode 100644 index dc7469dd301..00000000000 --- a/source/deploy/build-custom-mobile-apps.rst +++ /dev/null @@ -1,109 +0,0 @@ -Building and distributing your own custom Mattermost mobile apps -================================================================ - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -You can build and distribute custom versions of the Mattermost mobile app. Choosing this approach means :doc:`you've decided not to use the mobile app Mattermost has made available ` through public app stores. This also means that you've decided to :ref:`host your own push proxy service `. - -This approach is recommended for: - -- Organizations that want to customize their Mattermost mobile Apps. -- Customers using self-hosted Mattermost Enterprise or Professional Edition, or Mattermost Team Edition, that prefer to host their own push proxy server instead of using one of Mattermost’s hosted versions. - -.. note:: - - - A Mattermost Enterprise subscription plan (or a legacy Enterprise Edition license) is required to request assistance or troubleshooting help from `Mattermost Customer Support `__ when building and deploying custom mobile apps. Customers on other Mattermost subscription plans can develop and deploy custom mobile apps, but can't request technical support assistance through Mattermost Customer Support. - - With the release of Mattermost mobile app v2.0, mobile app v1.55 becomes the official :doc:`extended support mobile release `, and will be supported for an extended timeframe. - -Deployment options ------------------- - -When you decide to build your own Mattermost mobile apps, you have multiple ways to deploy: - -- Submitting your app to `an Enterprise App Store <#using-an-enterprise-app-store>`_. -- Using `an Enterprise Mobile Management (EMM) provider <#using-an-emm-provider>`_. -- Submitting your app to `public app stores <#using-public-app-stores>`_. -- Using `another distribution method <#using-another-distribution-method>`_. - -Setting up push notifications ------------------------------ - -See our :doc:`Mobile Push Notifications ` documentation to learn about setting up push notifications for custom-built mobile apps. - -Developing and maintaining your custom app ------------------------------------------- - -The Mattermost Mobile App is an open source project. Customizing Mattermost mobile apps requires a fork of the source code. Your team will be responsible for maintaining that fork, as well as keeping that fork updated with any changes made by Mattermost. - -This means that you manage the maintenance of your custom Mattermost mobile apps, such as rebuilding and incorporating feature and/or security updates. If this isn't done regularly, your applications won't match the functionality of our publicly-available applications, and could be incompatible with future versions of Mattermost Server. - -This process can be complicated and can greatly increase deployment time, not only initially, but whenever the mobile apps need to be updated. We recommend having your development team `review the Mattermost Mobile Apps developer documentation `__ to ensure they understand the scale and requirements of taking this path. This documentation provides guidance on building, compiling, signing, and white-labeling Mattermost Mobile apps. - -In general, building your own mobile apps will present some challenges, including: - -- Installing the necessary developer tools (such as Nodejs, XCode Developer Tools, Android SDKs, as well as others). -- Obtaining and providing certificates for your custom Mattermost mobile apps*. -- Signing your custom Mattermost mobile apps*. -- Distributing your Mobile app to your users. - -***** Mattermost mobile apps are signed, and they have certificates and keys associated with Mattermost and public app stores. This means Mattermost’s Mobile App won’t work if you choose to privately host the Mattermost Push Proxy Service (MPNS). You'll need to build your own custom mobile app. - -Custom mobile app branding -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Ensure you select a unique app name that helps users distinguish your version from others, such as " Collaboration". See our `Brand and Visual Design Guidelines `__ in our company Handbook for details. - -URL Schema Limitations -~~~~~~~~~~~~~~~~~~~~~~ -If you are building your own version of Mattermost's mobile client, you need to be aware of the following things: - -- To allow users to simultaneously run the App Store versions of Mattermost, in addition to the custom company version, you will need to adapt the URL schemes used for the app in the build, as well as configure those schemes on the server using :ref:`App Custom URL Schemes ` -- Be aware that the ``bundleid`` for the application should not include ``rnbeta``. -- The same change would be required in a custom build of the Mattermost desktop app. -- The mobile and desktop custom clients would no longer be able to log into other Mattermost servers (unless they had the same custom app schema configuration change applied). - -Deploying your custom app -------------------------- - -You have a number of ways to deploy your custom app for your users to download to their mobile devices. - -Using an enterprise app store -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This is the most common way for customers to distribute their apps, and it’s our recommended approach. Once your custom app is added to your own enterprise App Store, your users can download it from the store directly or from an EMM catalog. - -Using an EMM provider -~~~~~~~~~~~~~~~~~~~~~ - -Alternatively, you can use an EMM provider to push the application to the user’s device, then use the AppConfig standard to enforce a selection of app-specific controls. - -For additional details, see the following documentation: - -- :doc:`Deployment Using an EMM provider ` to learn more about deploying your custom Mattermost Mobile apps through an EMM provider. -- :doc:`Manage app configuration using AppConfig ` to learn more about managing your app configuration using App Config, and the configuration options that can be sent from the EMM provider to Mattermost mobile apps. - -Using public app stores -~~~~~~~~~~~~~~~~~~~~~~~ - -This is the same process Mattermost uses to make Mattermost mobile apps available for everyone. Before your app can be listed on the public app stores, you need to submit it to the public app stores for review and approval. - -As part of the submission process, you need to identify an update strategy that accounts for the release of new versions of Mattermost mobile apps. - -This update strategy should include: - -- Reviewing compatibility requirements. -- Validating mobile app versions connecting to the server. -- Updating Mattermost Server. -- Updating Mattermost mobile apps. - -We highly recommend you update your custom Mattermost mobile apps to incorporate any security or service releases. Prior to distribution, check any compatibility requirements for the mobile apps and the Mattermost server. Consult the :doc:`Mattermost mobile app changelog ` and the :doc:`Mattermost server releases ` documentation for details. - -.. important:: - - Not all provided updates are compatible with all previous versions of Mattermost Server. Updating only Mattermost mobile apps or updating the mobile apps before Mattermost Server can result in incompatibility issues. - -Using another distribution method -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can set up an alternate distribution method to deploy your custom app, such as a file sharing platform. diff --git a/source/deploy/client-side-data.rst b/source/deploy/client-side-data.rst deleted file mode 100644 index 6fc8cdda165..00000000000 --- a/source/deploy/client-side-data.rst +++ /dev/null @@ -1,64 +0,0 @@ -Client-side data storage FAQ -============================ - -Mobile web experience ---------------------- - -**1. What data is stored?** - Similar to a desktop web browser, data may be stored in the mobile web browser cache which resides on the storage system of the device operating system which is protected by security measures in the physical device and its operating system. -**2. How is the data protected?** - Security for mobile web experience is similar to the security for a desktop web experience. -**3. When is the data deleted?** - If you log out or your account is deactivated, the data in the browser cache may reside until the cache expires or the temporary file system store on the operating system is cleared, depending on your operating system. - - -Mobile app experience ---------------------- - -To speed up initial loading time, Mattermost mobile apps cache data locally on the device for v1.1 and later. Below are common questions on cached data: - -**1. What data is stored locally with the new mobile apps on a mobile device?** - The data that can be found on the device depends solely on whether or not the user is logged in to the Mattermost server, and is independent of the state of the device's connection or the state of the app. While logged in, anything that the user is normally allowed to see is eligible for storage on the device, which includes the following content: - - - Messages - - Files and images that are attached to messages - - Profile pictures, usernames, and email addresses of people in the currently open channel - - In addition, metadata that the app uses for keeping track of its operations is also cached. The metadata includes user IDs, channel IDs, team IDs, and message IDs. - - Currently, cache cannot be reset remotely on connected mobile devices. - -**2. What about push notifications?** - Push notification storage is managed by the operating system on the device. Mattermost can be configured to send limited amounts of information that does not include the message text or channel name, and it can also be configured to not send push notifications at all. - -**3. Where is the data stored and how is that data protected?** - The data is stored in the app's local storage. It's protected by the security measures that a device normally provides to the apps that are installed on it. - -**4. How long is the data stored?** - Data is stored until the user logs out, or until it is purged during normal cache management. Deactivating a user account forces a logout and subsequent purging of data from the device. - -**5. Are messages pre-loaded?** - No. Messages are sent to the device on demand. They are not pre-loaded in anticipation of users scrolling up or switching channels. - -**6. What happens to messages that are deleted on the server after a user has seen them?** - The messages are deleted from the client. - -**7. What data is stored on a mobile device after an account is deactivated in the following cases:** - a. *The mobile device is connected with app running.* - - All the data listed in questions 1 and 2, but within 60 seconds after an account is deactivated on the server, all app data is deleted from the cache. - - b. *The mobile device is disconnected with app running.* - - All the data listed in questions 1 and 2, but within 60 seconds after the device reconnects, all app data is deleted from the cache. - - c. *The mobile device is connected with the app not running.* - - All the data listed in Questions 1 and 2, but within 60 seconds after the app is started, all app data is deleted from the cache. - - d. *The mobile device is disconnected and app is not running.* - - All the data listed in Questions 1 and 2, but within 60 seconds after the device reconnects and the app is started, all app data is deleted from the cache. - -**8. What data might be on the device after a user account is deactivated and all data is deleted from the cache?** - If file attachments are enabled on the server, users can download files that are attached to messages and store them on their local file system. After they are downloaded, the files are outside the control of the app and can remain on the device indefinitely. diff --git a/source/deploy/deploy-mobile-apps-using-emm-provider.rst b/source/deploy/deploy-mobile-apps-using-emm-provider.rst deleted file mode 100644 index 791b2e8856d..00000000000 --- a/source/deploy/deploy-mobile-apps-using-emm-provider.rst +++ /dev/null @@ -1,48 +0,0 @@ -Deploying mobile apps using an EMM provider -=========================================== - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -Admins can enhance mobile security by deploying with `Enterprise Mobility Management (EMM) `__ and :doc:`Mattermost AppConfig ` compatibility to secure mobile endpoints with management application configuration. - -You can use an EMM to: - -- Enforce users to download the Mattermost pre-built or custom apps managed by your organization. -- Set default server url address. -- Restrict users from changing servers. -- Enforce security policies. - -An EMM provider pushes Mattermost Mobile apps to EMM-enrolled devices. This approach is recommended for organizations that typically use EMM solutions to deploy Mobile apps to meet security and compliance policies. - -Manage app configuration using AppConfig ----------------------------------------- - -AppConfig is our recommended approach for app configuration and management. It was introduced by the `AppConfig Community `__, a group of leading EMM providers and app developers who have come together to make it easier for developers and customers to drive mobility in business. - -AppConfig provides an easy way to configure enterprise mobile apps with any EMM providers listed on the `AppConfig website `__. Using AppConfig, you can manage default settings and security controls on public app stores and custom-built mobile clients. For example, you can pre-configure your Mattermost server URL and username. - -See our :ref:`Mattermost AppConfig Values ` documentation for details on the configuration options that can be sent from the EMM provider to Mattermost Mobile apps. - -.. important:: - - Mattermost only supports the AppConfig standard for securing Mattermost mobile apps via an EMM provider due to incompatibilities with app wrapping and React Native applications. Different EMM vendors refer to “wrapping” in different ways, but it ultimately comes down to unpacking the mobile client bundle, injecting additional SDKs, and re-packaging/re-signing. React Native is the technology used to develop the Mattermost mobile apps. - - Mattermost doesn’t support app wrapping, and Mattermost mobile apps won't function properly when using app wrapping (e.g., Websockets for real-time messaging will break). Use app wrapping/containerization technology at your own risk. - - A Mattermost Enterprise subscription plan (or a legacy Enterprise Edition license) is required to request assistance or troubleshooting help from `Mattermost Customer Support `__ when building and deploying custom mobile apps. Customers on other Mattermost subscription plans can develop and deploy custom mobile apps, but can't request technical support assistance through Mattermost Customer Support. - - With the release of Mattermost mobile app v2.0, mobile app v1.55 becomes the official :doc:`extended support mobile release `, and will be supported for an extended timeframe. - -Enroll devices --------------- - -When building your own custom versions or deploying the pre-built Mattermost Mobile apps, consider your organization’s mobile policy: - -- Can users bring their own device (BYOD) If so, what devices will be used? -- Are devices company-owned and company-issued? -- Are both options supported? -- What operating systems do you want to start testing? - -Once you know what possible device configurations you’ll be supporting, consider creating a sample configuration, then running validation tests against each configuration item. - -Generate and assign device profiles ------------------------------------ - -Generate and assign a device profile for device-wide configurations through the EMM provider. \ No newline at end of file diff --git a/source/deploy/deployment-overview.rst b/source/deploy/deployment-overview.rst deleted file mode 100644 index 8cb60bfa6ef..00000000000 --- a/source/deploy/deployment-overview.rst +++ /dev/null @@ -1,242 +0,0 @@ -Deployment overview -=================== - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -The following Mattermost network diagram illustrates a private cloud deployment of Mattermost with optional configurations for scaling to performance from teams to large organizations. - -.. image:: ../images/network-diagram.svg - :alt: Mattermost network diagram shows how the components of a private cloud deployment could be deployed. Includes optional configurations for scaling for larger enterprise organizations. - :class: bg-white - -.. note:: - - GitLab Mattermost deployment is `documented separately `__ and not included below. - -Requirements and installation guides -------------------------------------- - -Mattermost supports workplace messaging for teams using one to three servers with instructions available in the Install Guides section of this documentation. See the :doc:`Software and Hardware Requirements ` documentation for server sizing estimates. - -User experience ----------------- - -PC web experience -^^^^^^^^^^^^^^^^^ - -End users can securely share messages and files using a web-based Mattermost experience in Chrome, Firefox, Safari, and Edge. Please see :doc:`Software and Hardware Requirements ` documentation for full details. - -Mobile App experience -^^^^^^^^^^^^^^^^^^^^^^ - -Native applications for iOS and Android are available for interacting with the Mattermost server and receiving encrypted push notifications from your private cloud. Organizations can use :ref:`a Hosted Push Notification Service ` with encrypted communications to mobile apps on the App Store and Google Play, or deploy to an :ref:`Enterprise App Store ` on your organization's private network. A :ref:`Test Push Notification Service ` is available for use while evaluating options. - -Mobile web experience -^^^^^^^^^^^^^^^^^^^^^ - -End users can securely share messages and files using a mobile web-based Mattermost experience on iOS and Android devices. Please see :doc:`Software and Hardware Requirements ` documentation for full details. - -Email client -^^^^^^^^^^^^ - -Receive emails on desktop and mobile from the Mattermost server. - -Communication protocols ------------------------ - -HTTPS connection (secure hypertext transfer protocol) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The HTTPS connection to the Mattermost server renders pages and provides core functionality. It doesn't include real-time interactivity, which is enabled by the WSS connection. - -If the HTTPS connection isn't available, the Mattermost service won't work. HTTPS is a secure, encrypted protocol and is highly recommended for production. An unencrypted HTTP connection may be used in initial testing and configuration but it is not recommended for production. - -WSS connection (secure WebSocket protocol) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -WSS is a secure, encrypted connection and is highly recommended. An unencrypted WSS connection may be used in initial testing and configuration but it is not recommended for production. - -The WSS connection to the Mattermost server enables real-time updates and notifications. If the WSS connection is not available, but HTTPS is available, the system will appear to work, but real-time updates and notifications will not work. Updates will only appear on a page refresh. WSS will be a persistent connection to the Mattermost server while you are connected, while HTTPS will be intermittent depending on when you load a page or a file. - -Typically a "Mattermost unreachable" error message will be displayed warning users that the Mattermost server is either unreachable or the WebSocket connection is not properly configured. - -Network access and multi-Factor authentication ----------------------------------------------- - -Behind a VPN -^^^^^^^^^^^^ - -Mattermost is intended to be installed within a private network which can offer multiple factors of authentication, including secure access to computing devices and physical locations. - -If outside access is required, a virtual private network client (VPN), such as `OpenVPN `__, with additional authentication used to connect to Mattermost for web, desktop, and mobile experiences, is recommended. - -Non-VPN setup -^^^^^^^^^^^^^^^ - -If Mattermost is accessible from the open internet, the following is recommended: - -1. An IT admin should be assigned to set up appropriate network security, subscribe to `the Mattermost security bulletin `__, and :doc:`apply new security updates `. -2. The organization enables :doc:`SAML Single Sign-on ` or enable :doc:`MFA ` using Google Authenticator. - -If Mattermost is accessible from the open internet with no VPN or MFA set up, we recommended using it only for non-confidential, unimportant conversations where impact of a compromised system is not essential. - -Data center infrastructure ---------------------------- - -Push notification service -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_static/badges/ent-pro-only.rst - :start-after: :nosearch: - -The :ref:`Mattermost Push Notification Service (MPNS) ` routes push notifications to: - -1. Apple Push Notification Service to send notifications to the Mattermost iOS app. -2. Google Push Notification Service to send notifications to the Mattermost Android app. - -If you're deploying mobile applications to an Enterprise App Store, your MPNS should be behind your firewall on your private network. If you're using mobile apps in the App Store and Google Play, you can relay notifications to mobile apps using the :ref:`Hosted Push Notification Service (HPNS) `. - -HPNS does not connect to your mobile apps directly. It sends messages over an encrypted channel to Apple or Google which are relayed to the app users downloaded from the App Store or Google Play. - -Proxy -^^^^^^ - -The proxy manages Secure Socket Layer (SSL) encryption and sets the policy on how network traffic will be routed to the Mattermost server. - -Mattermost install guides include setup instructions for the NGNIX software proxy by default. For large scale deployments, a hardware proxy with dedicated devices for processing SSL encryption and decryption could potentially increase efficiencies. - -In a High Availability configuration (Enterprise subscription plans only) the proxy would also balance network load across multiple Mattermost servers. - -Microsoft Active Directory Single Sign-On -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. include:: ../_static/badges/ent-pro-only.rst - :start-after: :nosearch: - -Mattermost Enterprise and Professional supports Microsoft Active Directory and LDAP Single Sign-on with secure transport over TLS or stunnel. - -Private Cloud integrations -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mattermost offers complete access to its Web Service APIs, along with incoming and outgoing webhooks, and slash command options for integrating with your self-managed systems. - -`Visit our app directory `__ for dozens of open source integrations to common tools like Jira, Jenkins, GitLab, Trac, Redmine, and SVN, along with interactive bot applications (Hubot, mattermost-bot), and other communication tools (Email, IRC, XMPP, Threema) that are freely available for use and customization. - -Email service -^^^^^^^^^^^^^ - -For notifications and account verification, Mattermost connects to your existing email service over SMTP, including Microsoft Exchange, Amazon SES, SendGrid, and self-hosted email solutions. - -Mattermost Server ------------------ - -Mattermost Server installs as a single compiled binary file. All server settings are stored in a configuration file, ``config/config.json``, which can be updated directly or via the web-based System Console user interface. - -RESTful JSON web service -^^^^^^^^^^^^^^^^^^^^^^^^ - -The entirety of the Mattermost server is accessible through a RESTful web service API. The API can be completely accessed by developers creating custom applications for Mattermost either directly or via Javascript and Golang drivers. - -Authentication client -^^^^^^^^^^^^^^^^^^^^^ - -Authenticates users by email or username plus password. - -Authentication provider -^^^^^^^^^^^^^^^^^^^^^^^^ - -Enables authentication of Mattermost server to other services with authentication client interface using OAuth2. - -Notification service -^^^^^^^^^^^^^^^^^^^^ - -Sends notifications via SMTP email and mobile push notifications via Mattermost Push Notification Service. - -Data management service -^^^^^^^^^^^^^^^^^^^^^^^ - -Connects to and manages supported databases. - -High Availability -^^^^^^^^^^^^^^^^^ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -Large organizations needing sophisticated, large scale, High Availability configurations can set up a :doc:`highly available, horizontally scalable ` deployment. Talk to a `Mattermost Expert `_ for guidance on configuring and sizing Mattermost to support your specific needs. - -Data stores ------------- - -Databases -^^^^^^^^^^ - -Mattermost uses a Postgres database to store and retrieve system data and to execute full text search. Solid State Drives (SSDs) can be used for faster read times to increase performance. - -See :ref:`Database requirements ` for full details. - -Multiple read replicas -~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -For enterprise deployments, the Mattermost database can be configured with a master and multiple read replicas. The read replicas can be configured as a redundant backup to the active server, so that during hardware failures operation can be diverted to the read replica server without interrupting service. - -The safest configuration is to size the disk space on the read replica used for failover two to three times larger than storage available on master, so that if the master fails because it runs out of disk space it will fail over to a read replica with enough extra space to run smoothly until the master is corrected. - -Search replicas -~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -You can configure one or more search replicas to isolate search queries. A search replica is similar to a read replica, but is used only for handling search queries. - -Global deployments -~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -Enterprise customers with deployments spanning many time zones can talk to a `Mattermost Expert `_ for guidance on advanced configurations to minimize latency by: - -1. Storing static assets over a global CDN. -2. Deploying multiple Mattermost servers to host API communication closer to the location of end users. -3. Deploying multiple database read replicas closer to the location of end users. - -File store -^^^^^^^^^^^ - -Images and files shared by users are stored and retrieved in one of three options. - -1. For teams sharing only modest amounts of file data, local storage on the same physical machine as the Mattermost server may be sufficient. -2. For enterprises sharing very large amounts of data, a Network Attached Storage (NAS) server may be used, which can scale to petabytes if necessary. -3. Alternatively, for both ease-of-use and scale, a third option is to use Amazon's S3 file storage service. - -Deployment options -------------------- - -Mattermost Enterprise Edition customers can talk to a `Mattermost Expert `_ for advice on deployment options for their specific environments. The following section describes common deployment configurations. - -Mobile devices with VPN clients (recommended) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mattermost can be deployed behind your company firewall on a private network with access from the outside via a Virtual Private Network (VPN). This means running a VPN client on the mobile devices and desktop computers that need to access Mattermost. - -The :ref:`Mattermost Push Notification Service ` (MPNS) should be behind your firewall on your private network. MPNS does not connect with mobile apps directly, it forwards push notifications from the Mattermost server to a relay service for the App Store or Google Play, or to mobile apps within an Enterprise App Store. - -Mobile devices without VPN clients -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If Mattermost is available on the internet, we recommend using :doc:`SAML Single Sign-on ` or enable :doc:`MFA ` using Google Authenticator. - -The :ref:`Mattermost Push Notification Service ` (MPNS) should be behind your firewall inside your private network. MPNS does not connect with mobile apps directly, it forwards push notifications from the Mattermost server to a relay service for App Store or Google Play, or directly to mobile apps within an Enterprise App Store behind your firewall. - -For support for certificate-based authentication for mobile devices, talk to a `Mattermost Expert `_ for more information. - -Mobile devices with an EMM provider -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mattermost mobile applications can also be deployed via :doc:`EMM providers who support AppConfig `. EMM solutions typically offer per-app VPN capabilities that can be used to connect to mobile apps behind a VPN. \ No newline at end of file diff --git a/source/deploy/desktop-app.rst b/source/deploy/desktop-app.rst deleted file mode 100644 index bf0600b735e..00000000000 --- a/source/deploy/desktop-app.rst +++ /dev/null @@ -1,143 +0,0 @@ -Desktop App deployment guide -============================= - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -Mattermost desktop applications are available for Windows, macOS, and Linux operating systems. - -You can `download the apps directly from our download page `__ and visit our :doc:`installation guides ` for help during setup and for troubleshooting tips. - -This page provides a guide on how to customize and distribute your own Mattermost desktop app, and how to distribute the official Windows desktop app silently to end users, pre-configured with the server URL and other app settings. - -Custom build configuration --------------------------- - -You can customize and distribute your own Mattermost desktop application by configuring `src/common/config/buildConfig.ts `__. - -1. Configure the desktop app's ``buildConfig.ts`` file. There are multiple parameters you can configure to customize the user experience: - -``defaultTeams`` -~~~~~~~~~~~~~~~~ - - Description - List of server URLs and their display names added to the desktop app by default, which the user cannot modify. Users can still add servers `through the Server Management page <#enableservermanagement>`_ unless ``enableServerManagement`` is set to ``false``. - - Expects an array of key-value pairs. - - Example - -.. code-block:: text - - defaultTeams: [ - { - name: 'example', - url: 'https://example.com' - }, - { - name: 'mattermost', - url: 'https://www.mattermost.com' - } - ] - -``helpLink`` -~~~~~~~~~~~~ - - Description - The URL of the help documentation in **Help > Learn More** menu bar item. If none is specified, the menu option is hidden. - - Expects a string. - - Examples - -.. code-block:: text - - helpLink: 'https://docs.mattermost.com/messaging/managing-desktop-app-servers.html' - helpLink: '' - -``enableServerManagement`` -~~~~~~~~~~~~~~~~~~~~~~~~~~ - - Description - Controls whether users can add, edit, or remove servers on the app settings page. If set to false, at least one server must be specified for ``defaultTeams`` or else users cannot interact with any servers. - - Expects a boolean, true or false. - - Examples - -.. code-block:: text - - enableServerManagement: true - -2. To build the application, follow the `Mattermost Desktop Development Guide `__. - -Windows App: Pre-configuration and silent deployment ------------------------------------------------------ - -You can distribute the official Windows desktop app silently to end users, pre-configured with the server URL. You can also set all the :doc:`app settings ` except for the **Start app on login** option. - -1. Download the latest Windows installer from the `Mattermost download page `__. - -2. Move the executable file into a shared place such as a file server. - -3. To create a batch file in Windows: - - - Open a text editor of your choice, such as Notepad or Notepad++. - - Copy and paste the following commands in the text file: - -.. code-block:: text - - rem "Step 1: Install Mattermost desktop app silently into user's local disk" - start \\SERVER\shared_folder\mattermost-setup-4.6.2-win.exe --silent - - if not exist "%APPDATA%\Mattermost" mkdir %APPDATA%\Mattermost - - rem "Step 2: Generate initial config.json into user's config directory" - ( - echo { - echo "version": 2, - echo "teams": [ - echo { - echo "name": "core", - echo "url": "https://community.mattermost.com", - echo "order": 0 - echo } - echo ], - echo "showTrayIcon": true, - echo "trayIconTheme": "light", - echo "minimizeToTray": true, - echo "notifications": { - echo "flashWindow": 2, - echo "bounceIcon": true, - echo "bounceIconType": "informational" - echo }, - echo "showUnreadBadge": true, - echo "useSpellChecker": true, - echo "enableHardwareAcceleration": true, - echo "autostart": true, - echo "spellCheckerLocale": "en-US", - echo "darkMode": false - echo } - ) > %APPDATA%\Mattermost\config.json - -.. note:: - - Instead of using this command to install the desktop app into a shared folder, you can also copy the executable to the folder before running it. This allows the shared folder to only require read-only permissions. - -4. Save the text file with the extension ``.bat``. For instance, ``mattermost-app-install.bat``. -5. Use standard software asset management tools to distribute and deploy the batch file to each user. - -Once run, the desktop app is added to the user’s local directory, along with the pre-configured ``config.json`` file. The installer creates a shortcut for the desktop app in the user's start menu; if a zip version is used, you need to create the shortcut manually. - -Windows App: Silently removing the app ---------------------------------------- - -To remove the app silently from a user's computer, you can run the following command: - -.. code-block:: text - - %userprofile%\AppData\local\Programs\mattermost-desktop\Uninstall Mattermost.exe /currentuser /S - -.. note:: - The .exe needs to be closed when this command is run - diff --git a/source/deploy/desktop/desktop-app-deployment.rst b/source/deploy/desktop/desktop-app-deployment.rst new file mode 100644 index 00000000000..29a270698df --- /dev/null +++ b/source/deploy/desktop/desktop-app-deployment.rst @@ -0,0 +1,41 @@ +Desktop App Deployment +======================= + +.. include:: ../../_static/badges/allplans-selfhosted.rst + :start-after: :nosearch: + +The Mattermost desktop app is available for Windows, macOS, and Linux operating systems, and offers :doc:`additional functionality ` beyond the web-based experience. + +Learn more about desktop app :ref:`software requirements `, :doc:`releases and server compatibility ` as well as the :doc:`what's changed across releases `. + +Download +--------- + +Download and install the Mattermost desktop app from the App Store (macOS), Microsoft Store (Windows), or by :doc:`using a package manager (Linux) `. When new desktop app releases become available, your desktop app is automatically updated. + +We strongly recommend installing the desktop app on a local drive. Network shares aren't supported. + +If you prefer to manage distribution of the mobile app to your users, see the deployment options below. + +Deployment options +------------------ + +Learn about installation, configuration, and management options for deploying the desktop app in your environment. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + /deploy/desktop/linux-desktop-install.rst + /deploy/desktop/distribute-a-custom-desktop-app.rst + /deploy/desktop/silent-windows-desktop-distribution.rst + /deploy/desktop/desktop-msi-installer-and-group-policy-install.rst + /deploy/desktop/desktop-custom-dictionaries.rst + /deploy/desktop/desktop-app-managed-resources.rst + +* :doc:`Distribute a custom desktop app ` +* :doc:`Silent Windows desktop distribution ` +* :doc:`MSI installer and group policy guide ` +* :doc:`Custom dictionaries for Windows and Linux ` +* :doc:`Managed resources for the desktop app ` \ No newline at end of file diff --git a/source/install/desktop-app-managed-resources.rst b/source/deploy/desktop/desktop-app-managed-resources.rst similarity index 89% rename from source/install/desktop-app-managed-resources.rst rename to source/deploy/desktop/desktop-app-managed-resources.rst index e3e5df5388b..93d0ec402cb 100644 --- a/source/install/desktop-app-managed-resources.rst +++ b/source/deploy/desktop/desktop-app-managed-resources.rst @@ -1,13 +1,13 @@ Desktop managed resources ========================= -.. include:: ../_static/badges/allplans-selfhosted.rst +.. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: The Mattermost desktop app supports managed resources. A managed resource can be any service available on the same hostname using the same protocol as the Mattermost server. .. note:: - Using this feature requires a :doc:`custom build of the Mattermost desktop app `. + Using this feature requires a `custom build of the Mattermost desktop app `. Add the path of a managed resource to your configuration file. When selected, it opens as a pop-up window in the Mattermost desktop app. diff --git a/source/install/desktop-custom-dictionaries.rst b/source/deploy/desktop/desktop-custom-dictionaries.rst similarity index 76% rename from source/install/desktop-custom-dictionaries.rst rename to source/deploy/desktop/desktop-custom-dictionaries.rst index 1a301f45c34..7b40933676b 100644 --- a/source/install/desktop-custom-dictionaries.rst +++ b/source/deploy/desktop/desktop-custom-dictionaries.rst @@ -1,14 +1,7 @@ Desktop App custom dictionaries =============================== -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -On Windows or Linux, Mattermost desktop app v4.7.1 and later supports custom dictionary definitions served through a URL. If custom dictionaries aren't specified, default dictionary definitions are obtained automatically from Chromium's CDNs (content delivery networks). - -.. note:: - - On macOS, the Mattermost desktop app uses dictionary definitions provided by Apple that can't be customized. +From Mattermost desktop app v4.7.1, custom dictionary definitions can be served through a URL on Windows and Linux. If custom dictionaries aren't specified, default dictionary definitions are obtained automatically from Chromium's CDNs (content delivery networks). On macOS, the Mattermost desktop app uses dictionary definitions provided by Apple that can't be customized. Prepare custom dictionaries --------------------------- diff --git a/source/install/desktop-msi-installer-and-group-policy-install.rst b/source/deploy/desktop/desktop-msi-installer-and-group-policy-install.rst similarity index 67% rename from source/install/desktop-msi-installer-and-group-policy-install.rst rename to source/deploy/desktop/desktop-msi-installer-and-group-policy-install.rst index c02f141b24b..3d48720f022 100644 --- a/source/install/desktop-msi-installer-and-group-policy-install.rst +++ b/source/deploy/desktop/desktop-msi-installer-and-group-policy-install.rst @@ -1,57 +1,71 @@ -Desktop MSI installer and group policy installation guides -================================================================== +Desktop MSI installer and group policy guide +============================================= -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +This page provides guidance on installing the desktop app MSI and use Group Policies in Windows for Mattermost Enterprise or Professional. The MSI installer package can be downloaded `here `_. -This guide provides steps to install the MSI and use Group Policies in Windows for Mattermost Enterprise or Professional. The MSI installer package can be downloaded `here `_. +.. tip:: + + Want to :doc:`distribute the official Windows desktop app silently ` to your end users instead? Download group policy and MSI installer files ---------------------------------------------- 1. Using a newly created Windows VM or dedicated Windows computer, make sure to use a Windows version that supports ``Edit group policy`` out of the box (i.e. Windows 10 Pro or Enterprise). - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00001.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00001.png :alt: When downloading group policy and MIS installer files, ensure to use a Windows version that supports Edit group policy. 2. Navigate to the `Mattermost Desktop `__ repository on `GitHub.com `__. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00002.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00002.png :alt: Go to the mattermost/desktop repository on GitHub. 3. Navigate to the release page for `version v5.11.2 `__ and download the appropriate installer for your version of Windows (32-bit vs. 64-bit). 4. Download the `source.zip `__ file as well to extract group policy files. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00003.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00003.png :alt: In the mattermost/desktop repository on GitHub, go to the release page for the latest desktop release, then download the installer for your version of Windows. Download the source.zip file as well to extract group policy files. Install group policy files locally ----------------------------------- +The following group policies are available supporting a state option of Not Configured, Enabled, or Disabled: + + +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ + | Group policy | Description | Mattermost release | Setting | + +==========================+============================================================+======================+============================+ + | Enable Server Management | If disabled, management of servers in the | v4.3 or later | ``EnableServerManagement`` | + | | app settings are disabled. | | | + +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ + | Default Server List | Define one or more default, permanent servers. | v4.3 or later | ``DefaultServerList`` | + +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ + | Automatic Updates | If disabled, automatic desktop app updates are disabled. | v5.1 or later | ``EnableAutoUpdates`` | + +--------------------------+------------------------------------------------------------+----------------------+----------------------------+ + 1. Browse to the folder the above files were downloaded to and unzip the ``desktop-5.11.2.zip`` file in place. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00004.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00004.png :alt: Go to the install download directory on your machine and unzip the ZIP file. 2. Navigate to the unzipped ``desktop-5.11.2\resources\windows\gpo`` folder and copy the contents. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00005.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00005.png :alt: Go to the \resources\windows\gpo directory and copy its contents. 3. Navigate to the ``C:\Windows\PolicyDefinitions`` folder and paste the files copied in the last step. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00006.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00006.png :alt: Go to the Windows\PolicyDefinitions directory and paste the files you copied in the previous step. 4. Verify the ``mattermost.admx`` file is in the ``C:\Windows\PolicyDefinitions`` folder. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00007.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00007.png :alt: Verify the mattermost.admx file is present in the Windows\PolicyDefinitions directory. 5. Verify the ``mattermost.adml`` file is in the ``C:\Windows\PolicyDefinitions\en-US`` folder. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00008.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00008.png :alt: Verify the mattermost.adml file is present in the Windows\PolicyDefinitions\en-US directory. .. note:: @@ -59,29 +73,33 @@ Install group policy files locally * ``\\FQDNDomain\sysvol\FQDNDomain\Policies\PolicyDefinitions`` can be used instead of ``C:\Windows\PolicyDefinitions`` if available. * ``\\FQDNDomain\sysvol\FQDNDomain\Policies\PolicyDefinitions\en-US`` can be used instead of ``C:\Windows\PolicyDefinitions\en-US`` if available. +**Disable automatic updates** + +Automatic desktop app updates can be disabled by configuring the supported group policy. Changes to group policies require you to restart Mattermost for those changes to take effect. + Configure Mattermost using group policy settings ------------------------------------------------- 1. Run the ``Edit group policy`` application by selecting **Start**, typing ``gpedit`` into the search field, then selecting the resulting **Edit group policy** search option. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00009.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00009.png :alt: When configuring Mattermost using group policy settings, run the Edit group policy application by going to Start, typing gpedit into the search field, then selecting the resulting Edit group policy search option. 2. In the **Edit group policy** window, navigate to ``Local Computer Policy\Computer Configuration\Administrative Templates\Mattermost``. In this example, double-click on ``DefaultServerList`` to set one or more default servers that will appear on app launch. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00010.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00010.png :alt: In the Edit group policy window, go to Local Computer Policy > Computer Configuration > Administrative Templates > Mattermost. To set one or more default servers to appear on app launch, for example, double-click on DefaultServerList to begin. 3. In the resulting window for **DefaultServerList**, select **Enabled** to turn the feature on, then select the **Show…** button in the **Options:** section of the window to add default servers. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00011.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00011.png :alt: In the DefaultServerList window, enable the feature, then select Show..., located under Options, to add the default servers. 4. In the resulting window, add desired Mattermost servers using a memorable name (i.e., Community) and the web URL of the Mattermost server (i.e., https://community.mattermost.com). 5. Select **OK** twice, then close the **Edit group policy** app. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00012.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00012.png :alt: Add the default servers by name and by URL, then select OK twice to close the Edit group policy application. Verify group policy settings have been applied @@ -89,14 +107,14 @@ Verify group policy settings have been applied 1. Open up the Registry Editor by selecting **Start**, typing ``Registry Editor`` in the search field, then selecting the **Registry Editor** option in the search results. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00013.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00013.png :alt: When verifying group policy settings, open the Registery Editor by going to Start, typing Registry Editor into the search field, then selecting the resulting Registry Editor search option. 2. In the **Registry Editor** window, navigate to ``Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Mattermost\DefaultServerList`` and verify the servers you added using the **Edit group policy** app are listed. 3. Once verified, close the **Registry Editor**. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00014.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00014.png :alt: Go to Computer > HKEY_LOCAL_MACHINE > SOFTWARE > Policies > Mattermost > DefaultServerList to veryfiy the servers you added, then close the Registry Editor. Install the Mattermost Desktop App using the MSI installer @@ -109,17 +127,17 @@ Install the Mattermost Desktop App using the MSI installer 1. Within the folder the MSI installer was downloaded to, double-click on the MSI installer to begin the Mattermost Desktop installation process. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00015.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00015.png :alt: Go to the folder where you downloaded the Mattermost Desktop App, and double-click on the MSI file to begin the installation process. 2. Installation of the MSI requires admin permission, so accept the resulting request to allow the installer to make changes to your device. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00016.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00016.png :alt: You'll be prompted to allow the Mattermost Desktop App to make changes to your system. You must select Yes to continue with the installation process. 3. Select **Finish** when the installation is complete. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00017.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00017.png :alt: When the installation is complete, select Finish. Verify group policy settings in the installed desktop app @@ -129,7 +147,7 @@ Verify group policy settings in the installed desktop app 2. Verify the app loads the first server you defined in the **Edit group policy** app. - .. image:: ../images/desktop/msi_gpo/msi_gpo_installation_test_00018.png + .. image:: ../../images/desktop/msi_gpo/msi_gpo_installation_test_00018.png :alt: Verify group policy settings in the Mattermost Desktop App by opening the app from the Start menu, and verifying that the app loads the first server you defined in the Edit group policy. Advanced MSI options @@ -162,8 +180,8 @@ Use the ``ALLUSERS`` parameter to install the MSI for all users: ``msiexec /i mattermost-desktop-v5.11.2-x64.msi ALLUSERS=1`` .. note:: - - Installing the MSI for all users :ref:`disables automatic updates ` for the desktop app on Windows. - - To :ref:`disable automatic updates ` on a per-user basis, use the ``DISABLEAUTOUPDATE`` parameter: ``msiexec /i mattermost-desktop-v5.11.2-x64.msi DISABLEAUTOUPDATE=1`` + - Installing the MSI for all users disables automatic updates for the desktop app on Windows. + - To disable automatic updates on a per-user basis, use the ``DISABLEAUTOUPDATE`` parameter: ``msiexec /i mattermost-desktop-v5.11.2-x64.msi DISABLEAUTOUPDATE=1`` Specify an install directory ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/deploy/desktop/desktop-troubleshooting.rst b/source/deploy/desktop/desktop-troubleshooting.rst new file mode 100644 index 00000000000..a8d65acae28 --- /dev/null +++ b/source/deploy/desktop/desktop-troubleshooting.rst @@ -0,0 +1,134 @@ +Desktop app troubleshooting +============================ + +Where is configuration stored locally? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The location of the Mattermost desktop app configuration file depends on the platform where you're running Mattermost (and, in the case of macOS, how you've chosen to install the app): + +- Windows: ``Users\\AppData\Roaming\Mattermost`` +- macOS installer: ``/Users//Library/Application Support/Mattermost`` +- macOS App Store: ``/Users//Library/Containers/Mattermost.Desktop/Data/Library/Application Support/Mattermost`` (via Finder: ``~/Library/Application Support/Mattermost`` as the extension is hidden) +- Linux: ``~/.config/Mattermost`` + +.. note:: + + - Local configuration data is not automatically removed when uninstalling the desktop app. If you wish to remove all data, you must manually remove the files from the applicable location noted above. + - Prior to uninstalling, you can choose to log out of any active sessions. You can terminate active sessions from another Mattermost session in **Profile > Security > View and Logout of Active Sessions**, then select **Log Out**. Desktop app sessions are labeled as **Native Desktop App**. + +How do I access logs? +~~~~~~~~~~~~~~~~~~~~~ + +From Mattermost desktop v5.3, you can access logs via **Help > Show logs**, which opens the file manager window showing the location of the log file. + +How do I download app diagnostics? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From Mattermost desktop v5.3, you can download a diagnostics text file via **Help > Run diagnostics**, which can be attached to a Support ticket. + +Desktop App displays white screen while launching and doesn't load the page +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +1. Delete the local ``Mattermost desktop app`` configuration file. See the `Where is configuration stored locally? <#where-is-configuration-stored-locally>`__ section above for file location details. +2. Reinstall the application. + +"Installation has failed" dialog +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The app data might be corrupted. Remove all the files in ``%LOCALAPPDATA%\mattermost``, then try reinstalling the app. + +"The application "Mattermost" can't be opened" dialog +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On macOS Catalina, this dialog can be triggered if the Mac Archive Utility is the default method for decompressing files. In this case using a third-party tool such as `Keka `_ or `Unarchiver `_ may resolve the problem. + +Desktop App window is black and doesn't load the page +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Ensure you have installed the latest desktop app version available. +2. Clear your cache and reload the app from **View > Clear Cache and Reload** or press :kbd:`Ctrl` :kbd:`Shift` :kbd:`R` on Windows or Linux, or :kbd:`⌘` :kbd:`⇧` :kbd:`R` on Mac. +3. Quit the app and restart it to see if the issue clears. +4. Disable GPU hardware acceleration. + + - On Windows or Linux, select **File > Settings** and clear the **Use GPU hardware acceleration** option. + - On macOS, select **Mattermost > Settings** and clear the **Use GPU hardware acceleration** option. + +5. If you are using a special video driver, such as Optimus, try disabling it to see if the problem is resolved. + +Desktop App window is white and doesn't load the page +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Ensure you have installed the latest desktop app version available. +2. Delete the ``%userprofile%\AppData\Roaming\Mattermost`` directory on your local machine. +3. Reinstall the desktop app. + +Desktop App is not visible, but the Mattermost icon is in the Task Bar +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This issue can occur on Windows in a multiple-monitor setup. When you disconnect the monitor that Mattermost is displayed on, Mattermost continues to display at screen coordinates that no longer exist. + +To resolve this issue, you can reset the desktop app screen location by deleting the screen location file. When the file is not present, the desktop app displays on the primary monitor by default. + +To reset the desktop app screen location: + +1. If the desktop app is running, right-click the Mattermost icon in the task bar, then select **Close Window**. +2. Open Windows File Explorer, and go to the ``%APPDATA%\Mattermost`` folder. +3. Delete the file ``bounds-info.json``. + +Desktop App constantly refreshes the page +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This issue can occur when ``localStorage`` has an unexpected state. To resolve the issue: + +- Windows: Open Windows File Explorer, go to the ``%APPDATA%\Mattermost`` folder, then delete the ``Local Storage`` folder. +- Mac: Open Finder, go to the ``~/Library/Application Support/Mattermost`` folder, then delete the ``Local Storage`` folder. +- Linux: Open the File Manager, go to the ``~/.config/Mattermost`` folder, then delete the ``Local Storage`` folder. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using ``rm -rf ~/.config/Mattermost``. + +Desktop App constantly asks to log in to Mattermost server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This issue can occur after a crash or unexpected shutdown of the desktop app that causes the app data to be corrupted. To resolve the issue: + +- Windows: Open Windows File Explorer, go to the ``%APPDATA%\Mattermost`` folder, then delete the ``IndexedDB`` folder and the ``Cookies`` and ``Cookies-journal`` files. +- Mac: Open Finder, go to the ``~/Library/Application Support/Mattermost`` folder, then delete the ``IndexedDB`` folder and the ``Cookies`` and ``Cookies-journal`` files. +- Linux: Open the file manager, go to the ``~/.config/Mattermost`` folder, then delete the ``IndexedDB`` folder and the ``Cookies`` and ``Cookies-journal`` files. Linux file managers may hide folders starting with a period by default. You can delete them from the terminal using ``rm -rf ~/.config/Mattermost``. + +"Internal error: BrowserWindow 'unresponsive' event has been emitted" +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Selecting **Show Details** on the dialog provides logs. Ways to resolve the issue: + +1. Clear the cache via **View > Clear Cache and Reload** or press :kbd:`Ctrl` :kbd:`Shift` :kbd:`R` on Windows or Linux, or :kbd:`⌘` :kbd:`⇧` :kbd:`R` on Mac. +2. Go to App Settings via **File > Settings** (or by pressing :kbd:`Ctrl` :kbd:`,` on Windows or Linux, or :kbd:`⌘` :kbd:`,` on Mac) and unselect hardware acceleration. + +Desktop app not responsive within Citrix Virtual Apps or Desktop Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Append ``Mattermost.exe;`` to the Registry Key ``HKLM\SYSTEM\CurrentControlSet\Services\CtxUvi\UviProcessExcludes`` and reboot the system. + +For further assistance, review the `Troubleshooting forum `_ for previously reported errors, or `join the Mattermost user community for troubleshooting help `_. + +Can I uninstall the desktop app I installed using snap on Linux? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Yes. Run the following command from a terminal window: ``sudo snap remove mattermost-desktop``. + +Report Desktop App issues +------------------------- + +When reporting issues found in the Mattermost desktop app, it's helpful to include the contents of the Developer Tools Console along with `the information on this page `_. + +To access the Developer Tools Console: + +1. In the menu bar, go to **View > Developer Tools > Developer Tools for Current Tab**. +2. Select the **Console** tab. +3. Right-click the log entry, then select **Save As**. +4. Save the file, then send it along with a description of your issue. +5. Close the console to disable the Developer Tools. + +You can open an additional set of developer tools for each server you have added to the desktop app. The tools can be opened by pasting this command in the Developer Tools Console you opened with the steps described above: + + .. code-block:: javascript + + document.getElementsByTagName("webview")[0].openDevTools(); + + diff --git a/source/deploy/desktop/distribute-a-custom-desktop-app.rst b/source/deploy/desktop/distribute-a-custom-desktop-app.rst new file mode 100644 index 00000000000..07c9c96758c --- /dev/null +++ b/source/deploy/desktop/distribute-a-custom-desktop-app.rst @@ -0,0 +1,85 @@ +Distribute a custom desktop app +================================ + +You can customize and distribute your own Mattermost desktop application by configuring `src/common/config/buildConfig.ts `__. + + + +1. Configure the desktop app's ``buildConfig.ts`` file. You can configure the following parameters to customize the user experience, including `defaultTeams <#defaultTeams>`__, `helpLink <#helpLink>`__, and `enableServerManagement <#enableServerManagement>`__. + +2. Follow the `Mattermost Desktop Development Guide `__ to build the application. +3. Distribute the application to your users. + +``defaultTeams`` +----------------- + +List of server URLs and their display names added to the desktop app by default, which the user cannot modify. Users can still add servers `through the Server Management page <#enableservermanagement>`_ unless ``enableServerManagement`` is set to ``false``. Expects an array of key-value pairs. + +Example: + +.. code-block:: text + + defaultTeams: [ + { + name: 'example', + url: 'https://example.com' + }, + { + name: 'mattermost', + url: 'https://www.mattermost.com' + } + ] + +``helpLink`` +------------- + +The URL of the help documentation in **Help > Learn More** menu bar item. If none is specified, the menu option is hidden. Expects a string. + +Example: + +.. code-block:: text + + helpLink: 'https://docs.mattermost.com/messaging/managing-desktop-app-servers.html' + helpLink: '' + +``enableServerManagement`` +-------------------------- + +Controls whether users can add, edit, or remove servers on the app settings page. If set to false, at least one server must be specified for ``defaultTeams`` or else users cannot interact with any servers. Expects a boolean, true or false. + +Example: + +.. code-block:: text + + enableServerManagement: true + +Managed resources +------------------- + +:doc:`Custom builds ` of the Mattermost desktop app support managed resources which are services available on the same hostname and protocol as the Mattermost server. + +To configure managed resources, add their path to the ``managedResources`` field in your configuration file. Selecting a managed resource opens it as a pop-up window in the desktop app. + +Additionally, you must configure the :ref:Managed Resource Paths ` server configuration setting. For example, adding the ``/video`` path: + +.. code-block:: text + + [...] + managedResources: ['trusted', 'video'], + [...] + +Below are examples of server URLs with valid and invalid managed resource URLs: + +Server: ``https://mattermost.my.org`` + +- Valid: ``https://mattermost.my.org/video`` +- Valid: ``https://mattermost.my.org/conference`` +- Invalid: ``http://mattermost.my.org/video`` (different protocol) +- Invalid: ``https://conference.my.org`` (different origin) + +Server: ``https://my.org/mattermost`` + +- Valid: ``https://my.org/video`` +- Valid: ``https://my.org/conference`` +- Invalid: ``http://my.org/video`` (different protocol) +- Invalid: ``https://conference.my.org`` (different origin) diff --git a/source/deploy/desktop/linux-desktop-install.rst b/source/deploy/desktop/linux-desktop-install.rst new file mode 100644 index 00000000000..57494833d91 --- /dev/null +++ b/source/deploy/desktop/linux-desktop-install.rst @@ -0,0 +1,86 @@ +Install desktop app on Linux +============================= + +This page describes how to install the Mattermost desktop app on Linux. + +.. tab:: Ubuntu/Debian + + Both a ``.deb`` package (Beta), and an official APT repository is available for Debian 9 and for Ubuntu releases 20.04 LTS or later. Automatic app updates are supported and enabled. When a new version of the desktop app is released, your app updates automatically. + + .. important:: + + The GPG public key has changed. If you had previously set up the repository on your system, you'll need to download the new key. You can set the ``UPDATE_GPG_KEY=yes`` environment variable when running the setup script to configure it to overwrite the previous key on your system with the new one. The first step of installation then becomes: ``curl -fsS -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo UPDATE_GPG_KEY=yes bash``. Depending on your setup, additional steps may also be required, particularly for installations that don't rely on the repository setup script. + + 1. At the command line, set up the Mattermost repository on your system: + + .. code-block:: sh + + curl -fsS -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo bash + + 2. Install the Mattermost desktop app: + + .. code-block:: sh + + sudo apt install mattermost-desktop + + 3. Update the Mattermost desktop app: + + .. code-block:: sh + + sudo apt upgrade mattermost-desktop + + **Snapcraft package** + + A snap is available for systems that have Snapcraft installed. Snapcraft is installed by default on Ubuntu 16.04 and later, but for most other Linux distributions you can install it manually. To install Snapcraft, see `Install snapd `_ on the Snapcraft website for details. + + 1. At the command line, execute the following command: + + .. code-block:: sh + + sudo snap install mattermost-desktop --beta + + 2. Run Mattermost as a desktop app. + + .. tip:: + You can review the current version of your desktop app by selecting the **More** |more-icon-vertical| icon located in the top left corner of the desktop app, then selecting **Help > Version...**. + +.. tab:: CentOS/RHEL + + Beta ``.rpm`` packages are available for CentOS and RHEL 7 and 8. Automatic app updates aren't supported. You must update your app manually. + + **Install the Mattermost Desktop App** + + 1. Download the latest version of the Mattermost desktop app for 64-bit systems: `mattermost-desktop-5.11.2-linux-x86_64.rpm `_ + + 2. At the command line, execute the following command: + + .. code-block:: sh + + sudo rpm -i mattermost-desktop-5.11.2-linux-x86_64.rpm + + 3. Run Mattermost as a desktop app. + + To manually update the desktop app, run the following command: + + .. code-block:: sh + + sudo rpm -u mattermost-desktop-5.11.2-linux-x86_64.rpm + + .. tip:: + You can review the current version of your desktop app by selecting the **More** |more-icon-vertical| icon located in the top left corner of the desktop app, then selecting **Help > Version...**. + +.. tab:: Generic Linux + + The Desktop app is available in two formats which are usable on most Linux distributions: a compressed tarball, and an AppImage binary. Both can be downloaded from the `Desktop App's Github releases page `_. Automatic app updates are supported and enabled on AppImage binary builds. When a new version of the desktop app is released, your app updates automatically. + + For instructions on how to use the AppImage binary, please refer to the `AppImage Quickstart documentation page `_. + + **Install the Desktop App's compressed tarball** + + 1. Download the latest version of the Mattermost desktop app for 64-bit systems: `mattermost-desktop-5.11.2-linux-x64.tar.gz `_ + + 2. Extract the archive to a convenient location, then give ``chrome-sandbox`` in the extracted directory the required ownership and permissions: ``sudo chown root:root chrome-sandbox && sudo chmod 4755 chrome-sandbox`` + + 3. Execute ``mattermost-desktop`` located inside the extracted directory. + + 4. To create a Desktop launcher, open the file ``README.md``, and follow the instructions in the **Desktop launcher** section. \ No newline at end of file diff --git a/source/deploy/desktop/silent-windows-desktop-distribution.rst b/source/deploy/desktop/silent-windows-desktop-distribution.rst new file mode 100644 index 00000000000..bcc3e913870 --- /dev/null +++ b/source/deploy/desktop/silent-windows-desktop-distribution.rst @@ -0,0 +1,70 @@ +Silent Windows desktop distribution +===================================== + +You can distribute the official Windows desktop app silently to end users, pre-configured with the server URL. Additionally, you can customize all of the :doc:`desktop app settings `, except the **Start app on login** option. + +.. tip:: + + Want to :ref:`perform a silent installation of the desktop app MSI ` instead? + +1. Download the latest Windows installer from the `Mattermost download page `__. + +2. Move the executable file into a shared place such as a file server. + +3. To create a batch file in Windows: + + - Open a text editor of your choice, such as Notepad or Notepad++. + - Copy and paste the following commands in the text file: + + .. code-block:: text + + rem "Step 1: Install Mattermost desktop app silently into user's local disk" + start \\SERVER\shared_folder\mattermost-setup-4.6.2-win.exe --silent + + if not exist "%APPDATA%\Mattermost" mkdir %APPDATA%\Mattermost + + rem "Step 2: Generate initial config.json into user's config directory" + ( + echo { + echo "version": 2, + echo "teams": [ + echo { + echo "name": "core", + echo "url": "https://community.mattermost.com", + echo "order": 0 + echo } + echo ], + echo "showTrayIcon": true, + echo "trayIconTheme": "light", + echo "minimizeToTray": true, + echo "notifications": { + echo "flashWindow": 2, + echo "bounceIcon": true, + echo "bounceIconType": "informational" + echo }, + echo "showUnreadBadge": true, + echo "useSpellChecker": true, + echo "enableHardwareAcceleration": true, + echo "autostart": true, + echo "spellCheckerLocale": "en-US", + echo "darkMode": false + echo } + ) > %APPDATA%\Mattermost\config.json + +4. Save the text file with the extension ``.bat``. For instance, ``mattermost-app-install.bat``. +5. Use standard software asset management tools to distribute and deploy the batch file to each user. + +Once run, the desktop app is added to the user’s local directory, along with the pre-configured ``config.json`` file. The installer creates a shortcut for the desktop app in the user's start menu; if a zip version is used, you need to create the shortcut manually. + +.. tip:: + + You can copy the executable to the folder before running it instead of using this command to install the desktop app into a shared folder. This allows the shared folder to only require read-only permissions. + +Windows App: Silently removing the app +--------------------------------------- + +To remove the app silently from a user's computer, you can run the following command with the .exe file closed: + +.. code-block:: text + + %userprofile%\AppData\local\Programs\mattermost-desktop\Uninstall Mattermost.exe /currentuser /S \ No newline at end of file diff --git a/source/deploy/encryption-options.rst b/source/deploy/encryption-options.rst index bdbb87639cf..58c108fc152 100644 --- a/source/deploy/encryption-options.rst +++ b/source/deploy/encryption-options.rst @@ -11,7 +11,7 @@ Encryption is not required for GDPR, although it can be used as an additional sa Encryption-in-transit --------------------- -Mattermost supports TLS encryption including AES-256 with 2048-bit RSA on all data transmissions between Mattermost client applications and the Mattermost server. You may either set up TLS on the Mattermost Server or install a proxy such as NGINX and set up TLS on the proxy. Refer to our :doc:`configuration guide for more details `. +Mattermost supports TLS encryption including AES-256 with 2048-bit RSA on all data transmissions between Mattermost client applications and the Mattermost server. You may either set up TLS on the Mattermost Server or install a proxy such as NGINX and set up TLS on the proxy. Refer to our :doc:`configuration guide for more details `. Connections to Active Directory/LDAP can :ref:`optionally be secured with TLS or stunnel `. diff --git a/source/deploy/manual-postgres-migration.rst b/source/deploy/manual-postgres-migration.rst index eb4350af645..d7c1964d407 100644 --- a/source/deploy/manual-postgres-migration.rst +++ b/source/deploy/manual-postgres-migration.rst @@ -130,7 +130,7 @@ Before a manual migration - Confirm your Mattermost version. See the **About** modal for details. - Schedule the migration window. This process requires you to stop the Mattermost Server during the migration. - See the `schema-diffs <#schema-diffs>`__ section to ensure data compatibility between schemas. - - Prepare your PostgreSQL environment by creating a database and user. See the :doc:`database ` documentation for details. + - Prepare your PostgreSQL environment by creating a database and user. See the :doc:`database ` documentation for details. - On `newer versions `_ of PostgreSQL, newly created users do not have access to ``public`` schema. The access should be explicitly granted by running ``GRANT ALL ON SCHEMA public to mmuser``. Schema diffs diff --git a/source/deploy/mobile-hpns.rst b/source/deploy/mobile-hpns.rst deleted file mode 100644 index 2a63b9f1b65..00000000000 --- a/source/deploy/mobile-hpns.rst +++ /dev/null @@ -1,125 +0,0 @@ -Mobile push notifications -========================= - -A push proxy is a key technology behind notification transmission that enables notifications between the server and a Mobile app. See our :ref:`Mobile Apps FAQ documentation ` to learn more about how push notifications work. - -Mattermost offers a :doc:`Mattermost Push Notification Service (MPNS) ` for Team Edition, Cloud, and Enterprise deployments. - -Test Push Notifications Service (TPNS) --------------------------------------- - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -Self-hosted customers can use Mattermost's free, basic Test Push Notifications Service (TPNS). - -.. note:: - - The TPNS isn’t recommended for use in production environments, and doesn’t offer production-level update service level agreements (SLAs). - - The TPNS isn't available for Mattermost Cloud deployments. - -Enable TPNS -~~~~~~~~~~~ - -To use the Mattermost TPNS, go to **System Console > Environment > Push Notification Server > Enable Push Notifications**, then select **Use TPNS connection to send notifications to iOS and Android apps**. - -See our :doc:`Testing Push Notifications ` documentation to learn more about testing mobile push notifications. - -.. note:: - - The TPNS only works with the pre-built mobile apps that Mattermost deploys through the Apple App Store and Google Play Store. If you have built your own mobile apps, you must also `host your own Mattermost push proxy service <#host-your-own-push-proxy-service>`_. - - You must ensure that the push proxy can be reached on the correct port. For TPNS, it's port 80 from the Mattermost server. - -Hosted Push Notifications Service (HPNS) ----------------------------------------- - -.. include:: ../_static/badges/ent-pro-cloud-selfhosted.rst - :start-after: :nosearch: - -Mattermost Enterprise, Professional, and Cloud customers can use Mattermost's Hosted Push Notification Service (HPNS). The HPNS offers: - -- Access to a publicly-hosted Mattermost Push Notification Service (MPNS) `available on GitHub. `__ -- An explicit `privacy policy `__ for the contents of unencrypted messages. -- Encrypted TLS connections: - - - Between HPNS and Apple Push Notification Services - - Between HPNS and Google’s Firebase Cloud Messaging Service - - HPNS and your Mattermost Server -- Production-level uptime expectations. -- Out-of-box configuration for new servers means nothing is required to enable HPNS for new deployments. HPNS can be `enabled for existing deployments <#enable-hpns-for-existing-deployments>`_. - -.. note:: - - The HPNS only works with pre-built apps Mattermost deploys through the Apple App Store and Google Play Store. If you build your own mobile apps, you must also `host your own Mattermost push proxy server <#host-your-own-push-proxy-service>`_. - - You must ensure that the push proxy can be reached on the correct port. For HPNS, it's port 443 from the Mattermost server. - - Mattermost doesn't store any notification data. Any data being stored is at the server level only, such as the ``device_id``, since the HPNS needs to know which device the notification must be sent to. - -Enable HPNS for existing deployments -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Configuring your existing Mattermost instance to use the Mattermost HPNS is a single, one-time step. - -1. Follow the instructions to :doc:`install or upgrade to Enterprise Edition `. - -2. Go to **System Console > Environment > Push Notification Server**. - -3. Set **Enable Push Notifications** to **Use HPNS connection with uptime SLA to send notifications to iOS and Android apps**. Note that this option is only available in Mattermost Enterprise Edition. - -4. Mattermost Enterprise and Professional customers: Specify the physical location of the **Push Notification Server**. - - - United States: ``https://push.mattermost.com`` - - Germany: ``https://hpns-de.mattermost.com`` - -.. image:: ../images/mobile_hpns.png - :alt: Configure a licensed self-hosted Mattermost deployment to use the Mattermost Hosted Push Notification Server (HPNS) in the System Console by going to Environment > Push Notification Server. Select the HPNS option, then specify the server URL. - -5. Review the Mattermost Terms of Service and the Mattermost Privacy Policy, then select the box "I understand and accept the Mattermost Hosted Push Notification Service Terms of Service and Privacy Policy" to acknowledge that you understand the terms of use. - -6. Select **Save** - -After setup, test push notifications to confirm they are working. - -ID-only push notifications -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-cloud-selfhosted.rst - :start-after: :nosearch: - -Admins can enable mobile notifications to be fully private to protect a Mattermost customer against breaches in iOS and Android notification infrastructure by limiting the data sent to Apple and Google through a Mattermost configuration setting. - -The standard way to send notifications to iOS and Android applications requires sending clear text messages to Apple or Google so they can be forwarded to a user’s phone and displayed on iOS or Android. While Apple or Google assure the data is not collected or stored, should the organizations be breached or coerced, all standard mobile notifications on the platform could be compromised. - -To avoid this risk, Mattermost can be configured to replace mobile notification text with message ID numbers that pass no information to Apple of Google. When received by the Mattermost mobile application on a user’s phone, the message IDs are used to privately communicate with their Mattermost server and to retrieve mobile notification messages over an encrypted channel. This means that, at no time, is the message text visible to Apple or Google’s message relay system. The contents of the message also won't reach the :ref:`Mattermost Push Notification Service (MPNS) `. - -.. note:: - Because of the extra steps to retrieve the notifications messages under Mattermost’s private mobility capability with ID-only push notifications, end users may experience a slight delay before the mobile notification is fully displayed compared to sending clear text through Apple and Google’s platform. - -See our :ref:`configuration settings ` documentation to learn more about the ID-only push notifications configuration setting. See our :ref:`Mobile Apps FAQ documentation ` for details on using ID-only push notifications for data privacy. - -Host your own push proxy service --------------------------------- - -Customers building their own custom mobile apps must host their own push proxy service using one of the following methods: - -- Compile your own MPNS from the `open source repository `__. -- Use the `pre-compiled version of MPNS available on GitHub `__. - -See our `developer documentation `__ on working with the Mattermost Push Notification Service. - -Enable MPNS -~~~~~~~~~~~ - -1. Go to **System Console > Environment > Push Notification Server**. -2. Under **Enable Push Notifications**, select **Manually enter Push Notification Service location**. -3. Enter the location of your MPNS in the **Push Notification Server** field, then select **Save**. -4. (Optional) Customize mobile push notification contents. Most deployments choose to include the full message content sent in the notification payload. - - a. Go to **System Console > Site Configuration > Notifications**. - b. Under **Push Notification Contents**, select the type of information to include in push notifications, then select **Save**. - -.. note:: - - - We recommend that your instance of the MPNS be behind your firewall inside your private network, or in your DMZ, in a way that the Mattermost server can access it. - - The MPNS does not connect with Mattermost mobile apps directly; the MPNS parses and forwards push notifications from the Mattermost server to the Apple Push Notification Service (APNS) or the Firebase Cloud Messaging (FCM). - - The MPNS must be able to communicate with the Apple Push Notification Service over HTTP/2. If an outbound proxy appliance is deployed between the MPNS and APNS, ensure it supports HTTP/2. - - Ensure you use encrypted TLS connections between your MPNS and Apple Push Notification Service, between your MPNS and Google FCM, and between your MPNS and your Mattermost server. - - You must ensure that the push proxy can be reached on the correct port. The default port is 8086. - - As part of the process of building the applications, you'll need to sign the applications. You must also obtain the appropriate certificate for both Android and iOS. If this isn't done, the applications won't be able to interact with your instance of the MPNS. Once this is complete, you can proceed with the deployment of your MPNS instance. - - We strongly recommend that you subscribe to `Mattermost Security Bulletins `__. When you're notified of security updates for the MPNS, apply them promptly. diff --git a/source/deploy/mobile-overview.rst b/source/deploy/mobile-overview.rst deleted file mode 100644 index b8a13868fc9..00000000000 --- a/source/deploy/mobile-overview.rst +++ /dev/null @@ -1,87 +0,0 @@ -Deploy Mattermost mobile apps -============================= - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -This documentation provides foundational information you need when developing a plan for an enterprise mobile application deployment. It’s intended for business leaders, system administrators, and mobile app developers responsible for deploying Mattermost in their organization. - -This documentation provides information to help you determine the ideal mobile deployment model for your organization, understand what’s required to build your own Mattermost Mobile Apps, and deploy Mattermost mobile apps. - -.. tip:: - - Download `this Mattermost mobile datasheet `_ to learn more about key features and use cases for the Mattermost mobile app. - -Decision summary ----------------- - -When planning for a mobile app deployment, you have two important decisions to make: - -- What app will you deploy? A pre-built app or your own custom build? -- How will you deploy it? - -.. note:: - - - Mattermost Cloud customers must use Mattermost pre-built public apps for mobile deployment. - - Some features described in this guide are available only in Mattermost Enterprise Edition. - -Mattermost provides official mobile apps through public app stores including the `Apple App Store `_ and the `Google Play Store `_. These apps are referred to throughout this documentation as Mattermost's pre-built mobile apps. Using Mattermost's pre-built apps is the easiest and fastest approach since your users can download the apps from public app stores, or you can use an EMM provider to maintain full control over the distribution process or enforce or restrict specific security policies. See :doc:`Using Mattermost’s Pre-Built Apps ` to learn more about using Mattermost pre-built apps. - -If you want to control the app's look and feel, or host your own push proxy server, you can build your own mobile apps and manage your own app distribution. See :doc:`Building and Distributing Your Own Custom Mattermost Mobile Apps ` to learn more about working with custom built apps. - -The following table summarizes the key differences between these two approaches: - -+----------------------------------------------------------------+---------------------------------------------------------------------+ -| **Use Pre-Built Apps (Highly Recommended)** | **Build Custom Apps (Not Easy)** | -+================================================================+=====================================================================+ -| **Recommended for:** | **Recommended for:** | -| | | -| Self-supporting teams who need standard features. | Teams that need to customize the app, or prefer to host their own | -| | push proxy server. | -+----------------------------------------------------------------+---------------------------------------------------------------------+ -| **Benefits:** | **Benefits:** | -| | | -| - Easiest way to deploy Mattermost Apps. | You maintain full control over the look and feel of your mobile | -| - Test push notifications using Mattermost mobile push proxy | app. | -| options. | | -| - Apps update automatically with the latest features | **Limitations:** | -| enhancements, and security updates. | | -| | - Requires development knowledge and resources to maintain mobile | -| **Limitations:** | app code as Mattermost releases new product updates. | -| | - Must deploy your own push proxy server. | -| - Can’t white-label Mattermost Mobile Apps. | | -| - Can’t deploy your own push proxy server. | | -+----------------------------------------------------------------+---------------------------------------------------------------------+ - -Technical and Security Requirements ------------------------------------ - -See our :ref:`Supported Devices/Mobile Device Requirements ` documentation for basic mobile device requirements, and our :doc:`Supported Mattermost Server Versions ` documentation for details on Mattermost Server minimum requirements. - -We recommend running the latest version of the Mattermost Server and the Mattermost Push Notification Service (MPNS) as they contain the most recent features and applicable security updates. - -If this isn't possible, we encourage you to be on the most recent Extended Support Release version of Mattermost Server. This release has critical feature updates that will ensure compatibility in a number of areas, including the Mattermost Push Notification Service (MPNS). - -.. important:: - Not all provided updates are compatible with all previous versions of Mattermost. Updating only Mattermost Mobile Apps or updating the Mobile apps before updating Mattermost Server can result in compatibility issues. - -You should also start thinking about technical and security requirements in parallel with an implementation plan. Feel free to use our :doc:`implementation plan template ` available in the Mattermost documentation. - -Also, start engaging your technical and security teams with the following questions: - -- Are there any known security or access requirements? -- Is an :doc:`Enterprise Mobile Management (EMM) Provider ` needed? -- Is a :doc:`VPN connection required `? - -Asking questions like these requires you to pause before jumping into your Mattermost mobile project. However, it will help ensure you see a return on your investment. - -Getting Help ------------- - -If you need assistance, please reach out using one or more of the following methods. - -- **Community:** Join our Mattermost community and post your specific questions in the `Developers: Mobile `__ channel. -- **Documentation:** We link to a lot of mobile-specific documentation within this guide, but we encourage you to visit all of our `product documentation `__. -- **Forums:** For more troubleshooting help, `open a new topic in our forum `__ and include the steps to reproduce your issue so we can test on our side. -- **GitHub:** `Visit us on GitHub `__ to create issues in any of our repositories. -- **Enterprise Support:** If you're a Mattermost Enterprise Edition subscriber, open a support ticket in the `Enterprise Edition Support portal `__. diff --git a/source/deploy/mobile-testing-notifications.rst b/source/deploy/mobile-testing-notifications.rst deleted file mode 100644 index 8810a273d4a..00000000000 --- a/source/deploy/mobile-testing-notifications.rst +++ /dev/null @@ -1,43 +0,0 @@ -Testing push notifications -========================== - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -Make sure to configure push notifications for your :doc:`pre-built mobile apps `, or for :doc:`your custom built mobile apps `. - -Then use the following instructions to confirm push notifications are working properly. - -1. Log in to your mobile app with an account on your Mattermost Server, which we’ll refer to as “Account A”. - -2. (iOS) When the app asks whether you wish to receive notifications, **confirm you want to receive notifications**. - - .. image:: ../images/mobile_push_prompt.png - :alt: Mattermost prompts you to confirm whether you want to allow mobile push notifications. To test mobile push notifications, you must select Allow. - :width: 300 px - -3. Confirm push notifications are enabled for “Account A”. - - A. Go to the notification settings menu in the mobile app. - - .. image:: ../images/mobile_notification_settings.gif - :alt: Access notification settings by selecting your profile picture to access Settings > Notifications. - :width: 300 px - - B. Check that the mobile push notifications are set to send. - - .. image:: ../images/mobile_push_send_for.png - :alt: Select Push Notifications to confirm when mobile push notifications will be sent. - :width: 300 px - - .. image:: ../images/mobile_push_send_when.png - :alt: Specify whether all new messages or only mentions and direct messages send push notifications. - :width: 300 px - -4. Have “Account A” put the app to background or close the app. - -5. Using a browser, log in to “Account B” on the same Mattermost Server. - -6. Open a direct message with “Account A”, and send a message. - -7. A push notification with the message should appear on the mobile device of “Account A”. If the push notification does not appear, follow :doc:`troubleshooting steps ` to look for issues. diff --git a/source/deploy/mobile-troubleshoot-notifications.rst b/source/deploy/mobile-troubleshoot-notifications.rst deleted file mode 100644 index 51a2abaca89..00000000000 --- a/source/deploy/mobile-troubleshoot-notifications.rst +++ /dev/null @@ -1,29 +0,0 @@ -:orphan: - -Troubleshooting push notifications -================================== - -If you did not receive a push notification when :doc:`testing push notifications `, use the following procedure to troubleshoot: - -1. In **System Console > Environment > Logging > File Log Level**, select **DEBUG** in order to watch for push notifications in the server log. - -2. Delete your mobile application, and reinstall it. - -3. Log in with "Account A" and **confirm you want to receive push notifications** when prompted by the mobile app. - -4. Go to **Profile** > **Security** > **View and Logout of Active Sessions** to confirm that there is a session for the native mobile app matching your login time. - -5. Repeat the procedure for :doc:`testing push notifications `. - -6. If no push notification displays, go to **System Console** > **Server Logs**, then select **Reload**. Look at the bottom of the logs for a message similar to: - -``[2016/04/21 03:16:44 UTC] [DEBG] Sending push notification to 608xyz0... wi msg of '@accountb: Hello'`` - - - If the log message displays, it means a message was sent to the HPNS server and was not received by your mobile app. Please `create a support ticket `_ with the subject "HPNS issue" for help from Mattermost's Support team. - - If the log message does not display, it means no mobile push notification was sent to “Account A”. Please repeat the process starting at step 2 and double-check each step. - -.. important:: - - To conserve disk space, once your push notification issue is resolved, go to **System Console > Environment > Logging > File Log Level**, then select **ERROR** to switch your logging detail level from **DEBUG** to **Errors Only**. - -If push notifications are not being delivered on the mobile device, confirm that you're logged in to the **Native** mobile app session through **Profile > Security > View and Log Out of Active Sessions**. Otherwise, the `DeviceId` won't get registered in the `Sessions` table and notifications won't be delivered. \ No newline at end of file diff --git a/source/deploy/mobile-troubleshoot.rst b/source/deploy/mobile-troubleshoot.rst deleted file mode 100644 index 85a3ac960f6..00000000000 --- a/source/deploy/mobile-troubleshoot.rst +++ /dev/null @@ -1,100 +0,0 @@ -Troubleshooting mobile apps -=========================== - -I keep getting a message "Cannot connect to the server. Please check your server URL and internet connection." --------------------------------------------------------------------------------------------------------------- - -First, confirm that your server URL has no typos and that it includes ``http://`` or ``https://`` according to the server deployment configuration. - -If the server URL is correct, there could be an issue with the SSL certificate configuration. - -To check your SSL certificate set up, test it by visiting a site such as `SSL Labs `__. If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included. - -Please note that the apps cannot connect to servers with self-signed certificates, consider using :ref:`Let's Encrypt ` instead. - -Login with ADFS/Office365 is not working ----------------------------------------- - -In line with Microsoft guidance we recommend `configuring intranet forms-based authentication for devices that do not support WIA `_. - -I see a “Connecting…” bar that does not go away ------------------------------------------------ - -If your app is working properly, you should see a grey “Connecting…” bar that clears or says “Connected” after the app reconnects. - -If you are seeing this message all the time, and your internet connection seems fine, ask your server administrator if the server uses NGINX or another webserver as a reverse proxy. If so, they should check that it is configured correctly for :ref:`supporting the websocket connection for APIv4 endpoints `. - -I’m not receiving push notifications on my device -------------------------------------------------- - -Please see our documentation on :doc:`troubleshooting push notifications `. - -All my outbound connections need to go through a proxy. How can I connect to the Mattermost Hosted Push Notification Service? ------------------------------------------------------------------------------------------------------------------------------ - -You can set up an internal server to proxy the connection out of their network to the Mattermost Hosted Push Notification Service (HPNS) by following the steps below: - -1. Make sure your proxy server is properly configured to support SSL. Confirm it works by checking the URL at https://www.digicert.com/help/. -2. Setup a proxy to forward requests to ``https://push.mattermost.com``. -3. In Mattermost set **System Console** > **Notification Settings** > **Mobile Push** > **Enable Push Notifications** in prior versions or **System Console > Environment > Push Notification Server > Enable Push Notifications** in versions after 5.12 to "Manually enter Push Notification Service location" -4. Enter the URL of your proxy in the **Push Notification Server** field. - -.. Note:: Depending on how your proxy is configured you may need to add a port number and create a URL like ``https://push.internalproxy.com:8000`` mapped to ``https://push.mattermost.com`` - -Build gets stuck at ``bundleReleaseJsAndAssets`` ------------------------------------------------- - -As a workaround, you can bundle the ``js`` manually first with - -.. code-block:: sh - - react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/ - -and then ignore the gradle task with - -.. code-block:: sh - - ./gradlew assembleRelease -x bundleReleaseJsAndAssets - -No image previews available in the mobile app ---------------------------------------------- - -This can happen if the server running Mattermost has its mime types not set up correctly. -A server running Linux has this file located in ``/etc/mime.types``. This might vary depending on your specific OS and distribution. - -Some distributions also ship without ``mailcap`` which can result in missing or incorrectly configured mime types. - -Messages with emojis aren't being sent from the Mobile App ----------------------------------------------------------- - -This can occur if the server running Mattermost is configured with an incorrect character set. To resolve this issue, in the ``config.json`` file under ``SqlSettings``, ensure that the ``DataSource`` key is configured correctly, then restart the Mattermost server. - -For example: - -.. code-block:: text - - "SqlSettings": { - "DataSource": "@/mattermost?charset=utf8mb4,utf8", - [...] - } - -See our :ref:`Configuration Settings ` documentation for details on configuring the connection string to the master database. - -None of these solve my problem! -------------------------------- - -For more troubleshooting help, `open a new topic in our forums `__ with steps to reproduce your issue. If you're an Enterprise Edition subscriber, you may open a support ticket in the `Enterprise Edition Support portal `_. - -To help us narrow down whether it’s a server configuration issue, device specific issue, or an issue with the app, please try the following things and include the results in your support request: - -**Connect to another server** - -1. Create an account at https://community.mattermost.com -2. Erase your mobile application and reinstall it -3. In your mobile app, enter the server URL https://community.mattermost.com and then your login credentials to see if the connection is working - -**Connect with another device** - -If you have another mobile device available, try connecting with that to see if your issue still reproduces. - -If you don’t have another device available, check with other teammates to see if they are having the same issue. diff --git a/source/deploy/consider-mobile-vpn-options.rst b/source/deploy/mobile/consider-mobile-vpn-options.rst similarity index 55% rename from source/deploy/consider-mobile-vpn-options.rst rename to source/deploy/mobile/consider-mobile-vpn-options.rst index c90dee7d831..a69fa6b3050 100644 --- a/source/deploy/consider-mobile-vpn-options.rst +++ b/source/deploy/mobile/consider-mobile-vpn-options.rst @@ -1,14 +1,7 @@ -Consider mobile VPN options -=========================== - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - - -Connect to your private network Mattermost instance ---------------------------------------------------- +Mobile VPN options +=================== -You need to set up a way to connect to your private network Mattermost instance, using an external proxy with encrypted transport through HTTPS and WSS network connections. +To connect to your private network Mattermost instance, you need to set up a way to connect to your private network Mattermost instance, using an external proxy with encrypted transport through HTTPS and WSS network connections. Depending on your security policies, we recommend deploying Mattermost behind a VPN and using a `per-app VPN <#id3>`_ with your EMM provider, or a mobile VPN client. @@ -24,12 +17,12 @@ A Virtual Private Network (VPN) allows a device outside a firewall to access con We recommend one of two options: `per-app VPN <#id3>`_ or a `device VPN <#id4>`_ to secure your deployment. Both options are compatible with most EMM providers. -We also recommend you review the following commonly-asked questions about data security on mobile devices: +We also recommend you review the following :doc:`commonly-asked questions ` about data security on mobile devices: -- :ref:`How data is handled on a device after an account is deleted? ` -- :ref:`What post metadata is sent in mobile push notifications? ` -- :ref:`What are my options for securing the Mobile apps? ` -- :ref:`What are my options for securing push notifications? ` +- How data is handled on a device after an account is deleted? +- What post metadata is sent in mobile push notifications? +- What are my options for securing the Mobile apps? +- What are my options for securing push notifications? Per-app VPN ~~~~~~~~~~~ @@ -49,7 +42,7 @@ Connect via corporate proxy server Review the following commonly-asked questions about connecting through a corporate proxy server: -- :ref:`How do I receive mobile push notifications if my IT policy requires the use of a corporate proxy server? ` -- :ref:`Deploy Mattermost with connection restricted post-proxy relay in DMZ or a trusted cloud environment ` -- :ref:`Whitelist Mattermost push notification proxy to bypass your corporate proxy server ` -- :ref:`Run App Store versions of the Mattermost Mobile apps ` \ No newline at end of file +- :ref:`How do I receive mobile push notifications if my IT policy requires the use of a corporate proxy server? ` +- :ref:`Deploy Mattermost with connection restricted post-proxy relay in DMZ or a trusted cloud environment ` +- :ref:`Whitelist Mattermost push notification proxy to bypass your corporate proxy server ` +- :ref:`Run App Store versions of the Mattermost Mobile apps ` \ No newline at end of file diff --git a/source/deploy/mobile-appconfig.rst b/source/deploy/mobile/deploy-mobile-apps-using-emm-provider.rst similarity index 73% rename from source/deploy/mobile-appconfig.rst rename to source/deploy/mobile/deploy-mobile-apps-using-emm-provider.rst index 340dcec82e1..8f19e456bcc 100644 --- a/source/deploy/mobile-appconfig.rst +++ b/source/deploy/mobile/deploy-mobile-apps-using-emm-provider.rst @@ -1,22 +1,26 @@ -AppConfig for EMM solutions with Mattermost mobile apps -======================================================= +Deploy using an EMM provider +============================= -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: +You can enhance mobile security by deploying the Mattermost mobile app with `Enterprise Mobility Management (EMM) `__ and :doc:`Mattermost AppConfig ` compatibility to secure mobile endpoints with management application configuration. -What is AppConfig? ------------------- +You can use an EMM to: -AppConfig is a standard approach for app configuration and management introduced by the AppConfig Community, a group of leading EMM providers and app developers who have come together to make it easier for developers and customers to drive mobility in business. The community's mission is to streamline the adoption and deployment of mobile enterprise applications by providing a standard approach to app configuration and management, building upon the extensive app security and configuration frameworks available in the OS. +- Enforce users to download the Mattermost pre-built or custom apps managed by your organization. +- Set default server url address. +- Restrict users from changing servers. +- Enforce security policies. -AppConfig provides an easy way to configure enterprise mobile applications with any of the EMM providers listed on the `AppConfig website `__. +An EMM provider pushes Mattermost Mobile apps to EMM-enrolled devices. This approach is recommended for organizations that typically use EMM solutions to deploy Mobile apps to meet security and compliance policies. -Mattermost mobile apps can be configured in your EMM solution using AppConfig with the apps on the public app stores (Google Play and Apple App Store), or as an "in-house app" you compile yourself. +Manage app configuration using AppConfig +---------------------------------------- -.. _appconfig-table: +AppConfig is our recommended approach for app configuration and management. It was introduced by the `AppConfig Community `__, a group of leading EMM providers and app developers who have come together to make it easier for developers and customers to drive mobility in business. + +AppConfig provides an easy way to configure enterprise mobile apps with any EMM providers listed on the `AppConfig website `__. Using AppConfig, you can manage default settings and security controls on public app stores and custom-built mobile clients. For example, you can pre-configure your Mattermost server URL and username. Mattermost AppConfig values ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following table shows all the configuration options that can be sent from the EMM provider of your choice to the Mattermost mobile apps. You can also :download:`download an XML template ` of the configuration file for use with your EMM provider. @@ -51,7 +55,7 @@ The following table shows all the configuration options that can be sent from th +------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+--------+---------------+------------------+-------------+--------------------------+ Other AppConfig settings ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ As part of AppConfig, EMM administrators can set the following additional configuration options for the Mattermost mobile apps: @@ -61,3 +65,26 @@ As part of AppConfig, EMM administrators can set the following additional config 4. **Remotely Wipe App:** Use the EMM tool to distribute the app to devices as a managed application so it can be remotely wiped. If the app was previously installed, mark it so the EMM converts the app to a managed app. Other configurations may be available depending on your EMM provider. + +.. important:: + - Mattermost only supports the AppConfig standard for securing Mattermost mobile apps via an EMM provider due to incompatibilities with app wrapping and React Native applications. Different EMM vendors refer to “wrapping” in different ways, but it ultimately comes down to unpacking the mobile client bundle, injecting additional SDKs, and re-packaging/re-signing. React Native is the technology used to develop the Mattermost mobile apps. + - Mattermost doesn’t support app wrapping, and Mattermost mobile apps won't function properly when using app wrapping (e.g., Websockets for real-time messaging will break). Use app wrapping/containerization technology at your own risk. + - A Mattermost Enterprise subscription plan (or a legacy Enterprise Edition license) is required to request assistance or troubleshooting help from `Mattermost Customer Support `__ when building and deploying custom mobile apps. Customers on other Mattermost subscription plans can develop and deploy custom mobile apps, but can't request technical support assistance through Mattermost Customer Support. + - With the release of Mattermost mobile app v2.0, mobile app v1.55 becomes the official :doc:`extended support mobile release `, and will be supported for an extended timeframe. + +Enroll devices +-------------- + +When building your own custom versions or deploying the pre-built Mattermost Mobile apps, consider your organization’s mobile policy: + +- Can users bring their own device (BYOD) If so, what devices will be used? +- Are devices company-owned and company-issued? +- Are both options supported? +- What operating systems do you want to start testing? + +Once you know what possible device configurations you’ll be supporting, consider creating a sample configuration, then running validation tests against each configuration item. + +Generate and assign device profiles +----------------------------------- + +Generate and assign a device profile for device-wide configurations through the EMM provider. \ No newline at end of file diff --git a/source/deploy/mobile/distribute-custom-mobile-apps.rst b/source/deploy/mobile/distribute-custom-mobile-apps.rst new file mode 100644 index 00000000000..17d7d2604d0 --- /dev/null +++ b/source/deploy/mobile/distribute-custom-mobile-apps.rst @@ -0,0 +1,56 @@ +Distribute a custom mobile app +================================ + +To control the look and feel of the Mattermost mobile app requires building your own mobile apps, :doc:`hosting your own push proxy service `, and managing your own app distribution. + +.. note:: + + - Mattermost Enterprise customers are eligible for support guidance on distributing their own custom mobile apps. + - With the release of Mattermost mobile app v2.0, mobile app v1.55 becomes the official :doc:`extended support mobile release `, and v1.55 will continue to be supported for an extended timeframe. + +Key considerations +------------------- + +The Mattermost Mobile App is an open source project. Customizing Mattermost mobile apps requires a fork of the source code. Your team will be responsible for maintaining that fork, as well as keeping that fork updated with any changes made by Mattermost. + +Building your own mobile apps will present some challenges, including: + +- Installing the necessary developer tools (such as Nodejs, XCode Developer Tools, Android SDKs, as well as others). +- Obtaining and providing certificates for your custom Mattermost mobile apps*. +- Signing your custom Mattermost mobile apps*. +- Distributing your Mobile app to your users. + +This means that you manage the maintenance of your custom Mattermost mobile apps, such as rebuilding and incorporating feature and/or security updates. If this isn't done regularly, your applications won't match the functionality of our publicly-available applications, and could be incompatible with future versions of Mattermost Server. + +This process can be complicated and can greatly increase deployment time, not only initially, but whenever the mobile apps need to be updated. We recommend having your development team `review the Mattermost Mobile Apps developer documentation `__ to ensure they understand the scale and requirements of taking this path. This documentation provides guidance on building, compiling, signing, and white-labeling Mattermost Mobile apps. + +URL schema limitations +~~~~~~~~~~~~~~~~~~~~~~ + +If you are building your own version of Mattermost's mobile client, you need to be aware of the following limitations: + +- To allow users to simultaneously run the App Store versions of Mattermost, in addition to the custom company version, you will need to adapt the URL schemes used for the app in the build, as well as configure those schemes on the server using :ref:`App Custom URL Schemes ` +- Be aware that the ``bundleid`` for the application should not include ``rnbeta``. +- The same change would be required in a custom build of the Mattermost desktop app. +- The mobile and desktop custom clients would no longer be able to log into other Mattermost servers (unless they had the same custom app schema configuration change applied). + +Deployment options +------------------ + +When you decide to build your own Mattermost mobile apps, you have multiple ways to deploy them to your organization. + +Our recommend approach is to submit your app to an Enterprise App Store. Once your custom app is added to your own enterprise App Store, your users can download it from the store directly or from an EMM catalog. + +Alternatively, use `an Enterprise Mobile Management (EMM) provider ` to push the mobile app to the user’s device, and use the AppConfig standard to enforce a selection of app-specific controls. Or, you can use `another distribution method <#using-another-distribution-method>`__, such as a file sharing platform. + +You can also submit your app to `public app stores <#using-public-app-stores>`__. This is the same process Mattermost uses to make Mattermost mobile apps available for everyone. However, before your app can be listed on the public app stores, you need to submit it to the public app stores for review and approval. + +- As part of the submission process, you need to identify an update strategy that accounts for the release of new versions of Mattermost mobile apps that includes reviewing compatibility requirements, validating mobile app versions connecting to the server, and updating Mattermost server. +- We highly recommend you update your custom Mattermost mobile apps to incorporate any security or service releases. +- Prior to distribution, check any compatibility requirements for the mobile apps and the Mattermost server. +- Not all provided updates are compatible with all previous versions of Mattermost server. Updating only Mattermost mobile apps or updating the mobile apps before Mattermost Server can result in incompatibility issues. + +Custom whitelabeling +-------------------- + +Ensure you select a unique app name that helps users distinguish your version from others, such as " Collaboration". See our `Brand and Visual Design Guidelines `__ in our company Handbook for details. \ No newline at end of file diff --git a/source/deploy/mobile/host-your-own-push-proxy-service.rst b/source/deploy/mobile/host-your-own-push-proxy-service.rst new file mode 100644 index 00000000000..e418f109a94 --- /dev/null +++ b/source/deploy/mobile/host-your-own-push-proxy-service.rst @@ -0,0 +1,30 @@ +Host your own push proxy service +================================= + +Customers building their own custom mobile apps must host their own push proxy service using one of the following methods: + +- Compile your own MPNS from the `open source repository `__. +- Use the `pre-compiled version of MPNS available on GitHub `__. + +See our `developer documentation `__ on working with the Mattermost Push Notification Service. + +Enable MPNS +~~~~~~~~~~~ + +1. Go to **System Console > Environment > Push Notification Server**. +2. Under **Enable Push Notifications**, select **Manually enter Push Notification Service location**. +3. Enter the location of your MPNS in the **Push Notification Server** field, then select **Save**. +4. (Optional) Customize mobile push notification contents. Most deployments choose to include the full message content sent in the notification payload. + + a. Go to **System Console > Site Configuration > Notifications**. + b. Under **Push Notification Contents**, select the type of information to include in push notifications, then select **Save**. + +.. note:: + + - We recommend that your instance of the MPNS be behind your firewall inside your private network, or in your DMZ, in a way that the Mattermost server can access it. + - The MPNS does not connect with Mattermost mobile apps directly; the MPNS parses and forwards push notifications from the Mattermost server to the Apple Push Notification Service (APNS) or the Firebase Cloud Messaging (FCM). + - The MPNS must be able to communicate with the Apple Push Notification Service over HTTP/2. If an outbound proxy appliance is deployed between the MPNS and APNS, ensure it supports HTTP/2. + - Ensure you use encrypted TLS connections between your MPNS and Apple Push Notification Service, between your MPNS and Google FCM, and between your MPNS and your Mattermost server. + - You must ensure that the push proxy can be reached on the correct port. The default port is 8086. + - As part of the process of building the applications, you'll need to sign the applications. You must also obtain the appropriate certificate for both Android and iOS. If this isn't done, the applications won't be able to interact with your instance of the MPNS. Once this is complete, you can proceed with the deployment of your MPNS instance. + - We strongly recommend that you subscribe to `Mattermost Security Bulletins `__. When you're notified of security updates for the MPNS, apply them promptly. diff --git a/source/deploy/mobile/mobile-app-deployment.rst b/source/deploy/mobile/mobile-app-deployment.rst new file mode 100644 index 00000000000..8ffafe5d9bd --- /dev/null +++ b/source/deploy/mobile/mobile-app-deployment.rst @@ -0,0 +1,34 @@ +Mobile App Deployment +====================== + +The Mattermost mobile app is available for iPhone and Android devices, and provides a native experience on the go, ensuring you can stay connected and productive from anywhere. + +Learn more about :ref:`mobile app software requirements `, :doc:`available releases and server compatibility `, :doc:`what's changed across releases `, and :doc:`commonly asked questions `. + +Download +-------- + +Download and install the Mattermost mobile app from the Apple App Store (iOS) or Google Play Store (Android). When new mobile app releases become available, your mobile app is automatically updated. + +If you prefer to manage distribution of the mobile app to your users, we recommend using an :doc:`EMM provider ` to maintain full control over the distribution process, as well as enforce or restrict specific security policies. See the deployment options below for details. + +Deployment options +------------------ + +Learn what’s required to build and deploy Mattermost mobile apps. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + /deploy/mobile/deploy-mobile-apps-using-emm-provider.rst + /deploy/mobile/distribute-custom-mobile-apps.rst + /deploy/mobile/host-your-own-push-proxy-service.rst + /deploy/mobile/consider-mobile-vpn-options.rst + /deploy/mobile/mobile-faq.rst + +* :doc:`Distribute custom mobile apps ` +* :doc:`Host your own push proxy service ` +* :doc:`Mobile VPN options ` +* :doc:`Mobile apps FAQ ` \ No newline at end of file diff --git a/source/deploy/mobile-faq.rst b/source/deploy/mobile/mobile-faq.rst similarity index 88% rename from source/deploy/mobile-faq.rst rename to source/deploy/mobile/mobile-faq.rst index de1167dfa9d..842294935d2 100644 --- a/source/deploy/mobile-faq.rst +++ b/source/deploy/mobile/mobile-faq.rst @@ -1,39 +1,55 @@ Mobile apps FAQ =============== -What versions of Mattermost support the mobile v2 app? ------------------------------------------------------- +Can I connect to multiple Mattermost servers using the mobile apps? +------------------------------------------------------------------- -We strongly recommend running the latest version of the Mattermost Server and the Mattermost Push Notification Service (MPNS) as they contain the most recent features and applicable security updates. If this isn’t possible, we encourage you to be on the most recent :ref:`Extended Support Release version ` of Mattermost Server. The extended support releases contain critical feature updates that will ensure compatibility in a number of areas, including, but not limited to, the Mattermost Push Notification Service (MPNS). +Yes, using Mattermost mobile app v2.0. Mobile v1.x only supports connecting to one server at a time. -See our :ref:`Supported Devices/Mobile Device Requirements ` documentation for basic mobile device requirements, and our :doc:`Supported Mattermost Server Versions ` documentation for details on Mattermost Server minimum requirements. +What data is stored? +--------------------- -Can I connect to multiple Mattermost servers using the mobile apps? -------------------------------------------------------------------- +The data that can be found on the device depends solely on whether or not the user is logged in to the Mattermost server, and is independent of the state of the device's connection or the state of the app. While logged in, anything that the user is normally allowed to see is eligible for storage on the device, which includes the following content: -Yes when using Mattermost mobile app v2.0. Mobile v1.x only supports connecting to one server at a time. +- Messages +- Files and images that are attached to messages +- Profile pictures, usernames, and email addresses of people in the currently open channel -Is there a tablet version of the mobile apps? ---------------------------------------------- +In addition, metadata that the app uses for keeping track of its operations is also cached. The metadata includes user IDs, channel IDs, team IDs, and message IDs. + +Currently, cache cannot be reset remotely on connected mobile devices. -Mattermost Classic mobile apps support tablets. +What about push notifications? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Can the permanent sidebar on tablet devices be disabled? --------------------------------------------------------- +Push notification storage is managed by the operating system on the device. Mattermost can be configured to send limited amounts of information that does not include the message text or channel name, and it can also be configured to not send push notifications at all. + +Where is the data stored and how is that data protected? +--------------------------------------------------------- + +The data is stored in the app's local storage. It's protected by the security measures that a device normally provides to the apps that are installed on it. -The permanent sidebar is on by default for tablet-sized devices, but can be disabled from **Settings > Display > Sidebar > Permanent Sidebar**. When disabled, the sidebar behaves similarly to mobile devices where the user must open it using the button in the top-left corner of the screen. +How long is the data stored? +---------------------------- -How is data handled on mobile devices after a user account is deactivated? --------------------------------------------------------------------------- +Data is stored until the user logs out, or until it is purged during normal cache management. Deactivating a user account forces a logout and subsequent purging of data from the device. + +How is data handled after a user account is deactivated? +-------------------------------------------------------- App data is wiped from the device when a user logs out of the app. If the user is logged in when the account is deactivated, then within one minute of deactivation the system logs the user out. Thereafter all app data is wiped from the device. +If file attachments are enabled on the server, users can download files that are attached to messages and store them on their local file system. After they are downloaded, the files are outside the control of the app and can remain on the device indefinitely. + +Are messages pre-loaded? +------------------------- + +No. Messages are sent to the device on demand. They are not pre-loaded in anticipation of users scrolling up or switching channels. + Do I need to compile the mobile apps to host my own push notification server? ------------------------------------------------------------------------------ -Yes. To host your own push notification server, you'll need to compile the mobile apps. See :doc:`documentation ` to learn how to compile your own mobile apps. - -.. _push-faq: +Yes. To host your own push notification server, you'll need to compile the mobile apps. See :doc:`documentation ` to learn how to compile your own mobile apps. How do push notifications work? ------------------------------- @@ -60,7 +76,7 @@ This means if you use the Mattermost apps from the Apple App Store or Google Pla 4. Either APNS or FCM receives the push notification message from MPNS over TLS, and then relays the message to the user's iOS or Android device to be displayed. .. note:: - + The use of push notifications with iOS and Android applications will require a moment where the contents of push notifications are visible and unencrypted by a server controlled by either Apple or Google. This is standard for any iOS or Android app. For this reason, there is an option available in Mattermost Enterprise to omit the contents of Mattermost messages from push notifications, or to configure message contents to be fetched from the server when notifications reach the device. See our :ref:`Configuration Settings ` documentation for details. Is TLS v1.3 supported? @@ -163,11 +179,11 @@ The following options are available for securing your push notification service: 4. Securing the Mattermost Apple App Store and Google Play apps: - - When using Mattermost mobile apps from the App Store and Google Play, purchase an annual subscription to Mattermost Enterprise or Professional to use Mattermost's :ref:`Hosted Push Notification Service (HPNS) `. + - When using Mattermost mobile apps from the App Store and Google Play, purchase an annual subscription to Mattermost Enterprise or Professional to use Mattermost's :ref:`Hosted Push Notification Service (HPNS) `. .. note:: - For configuration details, see guides for :doc:`deploying the Mattermost App Store and Google Play apps ` and :doc:`deploying your own version of the apps `. + For configuration details, see guides for :doc:`deploying the Mattermost mobile app ` and :doc:`deploying your own version of the apps `. Why do I sometimes see a delay in receiving a push notification? ---------------------------------------------------------------- @@ -188,14 +204,14 @@ How do I deploy Mattermost with Enterprise Mobility Management (EMM) providers? Mattermost enables customers with high privacy and custom security requirements to deploy mobile app and push notification services using keys that they alone control. -:doc:`Learn more about using AppConfig for EMM providers `. +:doc:`Learn more about using AppConfig for EMM providers `. How do I host the Mattermost push notification service? ------------------------------------------------------- -First, you can use the :doc:`Mattermost Hosted Push Notification Service (HPNS) `. Organizations can also `host their own push proxy server instead `_. This is applicable when you want to: +First, you can use the :ref:`Mattermost Hosted Push Notification Service (HPNS) `. Organizations can also :doc:`host their own push proxy server ` instead. This is applicable when you want to: -1. Customize the `Mattermost mobile apps `_; +1. Customize the Mattermost mobile apps; 2. Deploy your own push notification service, or 3. Repackage the mobile apps with BlueCedar or AppDome (both of which are not officially supported but have been successfully deployed by some organizations). @@ -301,7 +317,7 @@ In a proxy-aware configuration, a pre-proxy relay accepts messages from the `Mat See a sample architectural overview below: -.. image:: ../images/mobile-pre-proxy-relay.png +.. image:: ../../images/mobile-pre-proxy-relay.png :alt: The Mattermost push notification service is designed to send traffic directly to the Apple Push Notification Service (APNS) and Google Fire Cloud Messaging (FCM) services. However, if your organization requires a corporate proxy to scan and audit all outbound traffic, you can deploy Mattermost in a proxy-aware configuration with a pre-proxy relay. The relay accepts messages from the Mattermost Push Proxy, and forwards them to a corporate proxy that enforces your internal IT requirements before delivering the notification to a mobile device. This configuration requires a trusted root certificate. This enables the **pre-proxy relay** to act as the APNS and to forward the request to its final destination via your corporate proxy, not requiring the APNS traffic to be proxy-aware. The APNS traffic is redirected to the pre-proxy relay via ``/etc/hosts`` entry. The entry uses a trusted CA that signs a certificate for the Mattermost Push Proxy to trust the pre-proxy relay. See the Apple Developer documentation on `user notifications `_ for more information. @@ -321,7 +337,7 @@ Ths **post-proxy relay** `can be configured using the Mattermost Push Proxy inst In place of a DMZ, you can also host in a trusted cloud environment such as AWS or Azure depending on your internal approvals and policies. -.. image:: ../images/mobile-post-proxy-relay.png +.. image:: ../../images/mobile-post-proxy-relay.png :alt: The Mattermost push notification service is designed to send traffic directly to the Apple Push Notification Service (APNS) and Google Fire Cloud Messaging (FCM) services. However, if your organization doesn't support HTTP/2 requests to send push notifications to mobile devices, you can deploy a post-proxy relay to take messages form the Mattermost server, transform it from the incompatible format, and relay it to its final destination. The post-proxy relay can be configured using connection restrictions to meet your custom security and compliance requirements. Whitelist Mattermost push notification proxy to bypass your corporate proxy server @@ -337,11 +353,11 @@ You will need to `whitelist one subdomain and one port from Apple `_ or `Google Play Store `_ and connect with the :doc:`Mattermost Hosted Push Notification Service (HPNS) ` through your corporate proxy. +You can use the mobile applications hosted by Mattermost in the `Apple App Store `_ or `Google Play Store `_ and connect with the :ref:`Mattermost Hosted Push Notification Service (HPNS) ` through your corporate proxy. .. note:: - The use of hosted applications by Mattermost :doc:`can be deployed with Enterprise Mobility Management solutions via AppConfig ` but wrapping is not supported. See the :ref:`product documentation ` for details. + The use of hosted applications by Mattermost :doc:`can be deployed with Enterprise Mobility Management solutions via AppConfig ` but wrapping is not supported. See the :ref:`product documentation ` for details. How the ``deviceId`` behaves ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/deploy/mobile/mobile-troubleshooting.rst b/source/deploy/mobile/mobile-troubleshooting.rst new file mode 100644 index 00000000000..3c67446511d --- /dev/null +++ b/source/deploy/mobile/mobile-troubleshooting.rst @@ -0,0 +1,147 @@ +Mobile deployment troubleshooting +================================== + +I keep getting a message "Cannot connect to the server. Please check your server URL and internet connection." +-------------------------------------------------------------------------------------------------------------- + +First, confirm that your server URL has no typos and that it includes ``http://`` or ``https://`` according to the server deployment configuration. + +If the server URL is correct, there could be an issue with the SSL certificate configuration. + +To check your SSL certificate set up, test it by visiting a site such as `SSL Labs `__. If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included. + +Please note that the apps cannot connect to servers with self-signed certificates, consider using :ref:`Let's Encrypt ` instead. + +Login with ADFS/Office365 is not working +---------------------------------------- + +In line with Microsoft guidance we recommend `configuring intranet forms-based authentication for devices that do not support WIA `_. + +I see a “Connecting…” bar that does not go away +----------------------------------------------- + +If your app is working properly, you should see a grey “Connecting…” bar that clears or says “Connected” after the app reconnects. + +If you are seeing this message all the time, and your internet connection seems fine, ask your server administrator if the server uses NGINX or another webserver as a reverse proxy. If so, they should check that it is configured correctly for :ref:`supporting the websocket connection for APIv4 endpoints `. + +All my outbound connections need to go through a proxy. How can I connect to the Mattermost Hosted Push Notification Service? +----------------------------------------------------------------------------------------------------------------------------- + +You can set up an internal server to proxy the connection out of their network to the Mattermost Hosted Push Notification Service (HPNS) by following the steps below: + +1. Make sure your proxy server is properly configured to support SSL. Confirm it works by checking the URL at https://www.digicert.com/help/. +2. Setup a proxy to forward requests to ``https://push.mattermost.com``. +3. In Mattermost set **System Console** > **Notification Settings** > **Mobile Push** > **Enable Push Notifications** in prior versions or **System Console > Environment > Push Notification Server > Enable Push Notifications** in versions after 5.12 to "Manually enter Push Notification Service location" +4. Enter the URL of your proxy in the **Push Notification Server** field. + +.. Note:: + + Depending on how your proxy is configured you may need to add a port number and create a URL like ``https://push.internalproxy.com:8000`` mapped to ``https://push.mattermost.com`` + +Build gets stuck at ``bundleReleaseJsAndAssets`` +------------------------------------------------ + +As a workaround, you can bundle the ``js`` manually first with + +.. code-block:: sh + + react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/ + +and then ignore the gradle task with + +.. code-block:: sh + + ./gradlew assembleRelease -x bundleReleaseJsAndAssets + +No image previews available in the mobile app +--------------------------------------------- + +This can happen if the server running Mattermost has its mime types not set up correctly. +A server running Linux has this file located in ``/etc/mime.types``. This might vary depending on your specific OS and distribution. + +Some distributions also ship without ``mailcap`` which can result in missing or incorrectly configured mime types. + +Messages with emojis aren't being sent from the Mobile App +---------------------------------------------------------- + +This can occur if the server running Mattermost is configured with an incorrect character set. To resolve this issue, in the ``config.json`` file under ``SqlSettings``, ensure that the ``DataSource`` key is configured correctly, then restart the Mattermost server. + +For example: + +.. code-block:: text + + "SqlSettings": { + "DataSource": "@/mattermost?charset=utf8mb4,utf8", + [...] + } + +See our :ref:`Configuration Settings ` documentation for details on configuring the connection string to the master database. + +Testing mobile push notifications +---------------------------------- + +Make sure to configure push notifications for your :doc:`pre-built mobile apps `, or for :doc:`your custom built mobile apps `. + +Then use the following instructions to confirm push notifications are working properly. + +1. Log in to your mobile app with an account on your Mattermost Server, which we’ll refer to as “Account A”. + +2. (iOS) When the app asks whether you wish to receive notifications, **confirm you want to receive notifications**. + + .. image:: ../../images/mobile_push_prompt.png + :alt: Mattermost prompts you to confirm whether you want to allow mobile push notifications. To test mobile push notifications, you must select Allow. + :width: 300 px + +3. Confirm push notifications are enabled for “Account A”. + + A. Go to the notification settings menu in the mobile app. + + .. image:: ../../images/mobile_notification_settings.gif + :alt: Access notification settings by selecting your profile picture to access Settings > Notifications. + :width: 300 px + + B. Check that the mobile push notifications are set to send. + + .. image:: ../../images/mobile_push_send_for.png + :alt: Select Push Notifications to confirm when mobile push notifications will be sent. + :width: 300 px + + .. image:: ../../images/mobile_push_send_when.png + :alt: Specify whether all new messages or only mentions and direct messages send push notifications. + :width: 300 px + +4. Have “Account A” put the app to background or close the app. + +5. Using a browser, log in to “Account B” on the same Mattermost Server. + +6. Open a direct message with “Account A”, and send a message. + +7. A push notification with the message should appear on the mobile device of “Account A”. + +Troubleshooting push notifications +---------------------------------- + +If you did not receive a push notification when testing push notifications, use the following procedure to troubleshoot: + +1. In **System Console > Environment > Logging > File Log Level**, select **DEBUG** in order to watch for push notifications in the server log. + +2. Delete your mobile application, and reinstall it. + +3. Log in with "Account A" and **confirm you want to receive push notifications** when prompted by the mobile app. + +4. Go to **Profile** > **Security** > **View and Logout of Active Sessions** to confirm that there is a session for the native mobile app matching your login time. + +5. Retest push notifications. + +6. If no push notification displays, go to **System Console** > **Server Logs**, then select **Reload**. Look at the bottom of the logs for a message similar to: + +``[2016/04/21 03:16:44 UTC] [DEBG] Sending push notification to 608xyz0... wi msg of '@accountb: Hello'`` + + - If the log message displays, it means a message was sent to the HPNS server and was not received by your mobile app. Please `create a support ticket `_ with the subject "HPNS issue" for help from Mattermost's Support team. + - If the log message does not display, it means no mobile push notification was sent to “Account A”. Please repeat the process starting at step 2 and double-check each step. + +.. important:: + + To conserve disk space, once your push notification issue is resolved, go to **System Console > Environment > Logging > File Log Level**, then select **ERROR** to switch your logging detail level from **DEBUG** to **Errors Only**. + +If push notifications are not being delivered on the mobile device, confirm that you're logged in to the **Native** mobile app session through **Profile > Security > View and Log Out of Active Sessions**. Otherwise, the `DeviceId` won't get registered in the `Sessions` table and notifications won't be delivered. \ No newline at end of file diff --git a/source/deploy/postgres-migration-assist-tool.rst b/source/deploy/postgres-migration-assist-tool.rst index 03fde09813e..16db4005f92 100644 --- a/source/deploy/postgres-migration-assist-tool.rst +++ b/source/deploy/postgres-migration-assist-tool.rst @@ -40,7 +40,7 @@ Usage .. important:: - Please make sure you have the necessary environment to perform the migration. Ensure that the MySQL and PostgreSQL databases are running and accessible. To set up a PostgreSQL instance, see the :doc:`prepare your Mattermost database ` documentation for details. + Please make sure you have the necessary environment to perform the migration. Ensure that the MySQL and PostgreSQL databases are running and accessible. To set up a PostgreSQL instance, see the :doc:`prepare your Mattermost database ` documentation for details. Step 1 - Check the MySQL database schema ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/deploy/postgres-migration.rst b/source/deploy/postgres-migration.rst index c6833336b17..b7e78a333d7 100644 --- a/source/deploy/postgres-migration.rst +++ b/source/deploy/postgres-migration.rst @@ -4,7 +4,7 @@ Migration guidelines from MySQL to PostgreSQL .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -From Mattermost v8.0, :ref:`PostgreSQL ` is our database of choice for Mattermost to enhance the platform’s performance and capabilities. Recognizing the importance of supporting the community members who are interested in migrating from a MySQL database, we have taken proactive measures to provide guidance and best practices. +From Mattermost v8.0, :ref:`PostgreSQL ` is our database of choice for Mattermost to enhance the platform’s performance and capabilities. Recognizing the importance of supporting the community members who are interested in migrating from a MySQL database, we have taken proactive measures to provide guidance and best practices. .. toctree:: :maxdepth: 1 diff --git a/source/install/setting-up-aws-elastic-beanstalk-docker.rst b/source/deploy/server/containers/install-aws-beanstalk.rst similarity index 68% rename from source/install/setting-up-aws-elastic-beanstalk-docker.rst rename to source/deploy/server/containers/install-aws-beanstalk.rst index 58cd52a763f..e46a7b2eea3 100644 --- a/source/install/setting-up-aws-elastic-beanstalk-docker.rst +++ b/source/deploy/server/containers/install-aws-beanstalk.rst @@ -1,13 +1,6 @@ -AWS Elastic Beanstalk Docker setup -================================== +You can deploy Mattermost server in **Preview Mode** on AWS Elastic Beanstalk using a Docker container. This is a great option for exploring functionality, testing, and development purposes, as it allows you to quickly set up a Mattermost instance without needing to manage the underlying infrastructure. This deployment method shouldn't be used in production environments. -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -The following instructions use Docker to install Mattermost in *Preview Mode* for exploring product functionality. This configuration should not -be used in production. - -The Elastic Beanstalk application creation process used here is the easy *Getting Started* approach which combines Application and Environment creation in the same flow. +The Elastic Beanstalk application creation process below combines Application and Environment creation in a single workflow: 1. From your `AWS console `__ select **Elastic Beanstalk**. 2. Select the **Create Application** button on the Elastic Beanstalk home page. @@ -19,18 +12,12 @@ The Elastic Beanstalk application creation process used here is the easy *Gettin 8. For **Application code**, select **Upload your code**. 9. Download the ``Dockerrun.aws.json`` file from https://raw.githubusercontent.com/mattermost/mattermost-docker-preview/master/Dockerrun.aws.json. -10. Set a unique **Version Label**, choose **Local File**, then select **Choose file** button to browse for the downloaded file in the previous step. You should see a *File successfully uploaded* message. +10. Set a unique **Version Label**, choose **Local File**, then select **Choose file** button to browse for the downloaded file in the previous step. You should see a **File successfully uploaded** message. 11. Select **Create Application**. It may take a few minutes for Beanstalk to launch your environment. If the launch is successful, you will see a see a large green checkmark and the **Health status** displayed in green. 12. Test your environment by selecting the domain link next to your application name at the top of the dashboard. Alternatively, enter the domain into your browser in the form of ``http://.elasticbeanstalk.com``. You can also map your own domain if you prefer. When everything is working correctly, the domain navigates you to the Mattermost Login page. Enjoy exploring Mattermost! -Configuration Settings ----------------------- - -See :doc:`Configuration Settings ` documentation to customize your deployment. - -(Recommended) Enable Email --------------------------- +**(Recommended) Enable Email** -The default Docker instance for Mattermost is designed for product evaluation, and sets ``SendEmailNotifications=false`` so the product can function without enabling email. To see the product's full functionality, enabling SMTP email is recommended. +The default Docker instance for Mattermost is designed for product evaluation, and sets ``SendEmailNotifications=false`` so the product can function without enabling email. To see the product's full functionality, we recommend :doc:`enabling SMTP email `. -.. include:: ../configure/smtp-email.rst \ No newline at end of file +See :doc:`Configuration Settings ` documentation for more configuration and customization options for your deployment. \ No newline at end of file diff --git a/source/install/install-docker.rst b/source/deploy/server/containers/install-docker.rst similarity index 50% rename from source/install/install-docker.rst rename to source/deploy/server/containers/install-docker.rst index 59ac44f4762..cdd957b0aa6 100644 --- a/source/install/install-docker.rst +++ b/source/deploy/server/containers/install-docker.rst @@ -1,49 +1,23 @@ -Deploy Mattermost via Docker -============================== +This guide provides step-by-step instructions for deploying Mattermost using Docker containers. -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +.. warning:: -.. important:: - This deployment method is not recommended for production environments. If you're looking to deploy a production Mattermost instance, we recommend using managed container services like AWS ECS, Azure Container Apps, or Google Cloud Run. These services provide better scalability, reliability, and maintenance features suited for production workloads. + - Mattermost server deployment using Docker is officially supported on Linux operating systems only. + - macOS and Windows Docker deployments are supported for testing and development purposes only. + - Docker is not ideal for High Availability (HA) because it lacks key features including automatic failover, shared storage, and load balancing. Docker also has challenges managing multiple nodes and recovering from failures. We recommend :doc:`deploying on Kubernetes ` for HA for these features to ensure reliability. -Install Docker ---------------- +**Step 1: Install Docker** If you don't have Docker installed, follow the instructions below based on your operating system. You'll need `Docker Engine `__ and `Docker Compose `_ (release 1.28 or later). -.. tab:: macOS - - Follow the `Install Docker Engine on Mac `_ documentation. - -.. tab:: Windows 10 - - Follow the `Install Docker Engine on Windows `_ documentation. - -.. tab:: Ubuntu - - Follow the `Install Docker Engine on Ubuntu `_ documentation. - - .. important:: - Please ensure that you follow the `optional post-installation steps `_ when installing Docker on Ubuntu! - -.. tab:: Fedora - - Follow the `Install Docker Engine on Fedora `_ documentation. - -.. _Deploy Mattermost on Docker: +**Step 2: Deploy Mattermost on Docker** -Deploy Mattermost on Docker (Quick Start) ------------------------------------------ - -This section provides a quick start guide for deploying Mattermost on Docker. Leveraging `Docker Compose `_, this deployment solution is designed to get Mattermost up and running quickly. +This section provides a quick start guide for deploying Mattermost on Docker by leveraging `Docker Compose `_. .. note:: - The deployment configuration results in two separate containers: a container for the database and a container for the application. An optional third container results when using NGINX for reverse proxy. - - Encountering issues with your Docker deployment? See the :ref:`Docker deployment troubleshooting ` documentation for details. - -To deploy Mattermost on Docker: + - Encountering issues with your Docker deployment? See the :doc:`Docker deployment troubleshooting ` documentation for details. 1. In a terminal window, clone the repository and enter the directory. @@ -58,10 +32,10 @@ To deploy Mattermost on Docker: cp env.example .env -.. important:: + .. important:: - - At a minimum, you must edit the ``DOMAIN`` value in the ``.env`` file to correspond to the domain for your Mattermost server. - - We recommend configuring the `Support Email `_ via ``MM_SUPPORTSETTINGS_SUPPORTEMAIL``. This is the email address your users will contact when they need help. + - At a minimum, you must edit the ``DOMAIN`` value in the ``.env`` file to correspond to the domain for your Mattermost server. + - We recommend configuring the `Support Email `_ via ``MM_SUPPORTSETTINGS_SUPPORTEMAIL``. This is the email address your users will contact when they need help. 3. Create the required directories and set their permissions. @@ -132,38 +106,31 @@ To deploy Mattermost on Docker: 6. Create your first Mattermost system admin user, :doc:`invite more users `, and explore the Mattermost platform. -Configure SSO With GitLab (Optional) -------------------------------------- +**Configure SSO With GitLab (Optional)** -If you want to use SSO with GitLab, and you're using a self-signed certificate, you have to add the PKI chain for your authority. This is required to avoid the ``Token request failed: certificate signed by unknown authority`` error. - -To add the PKI chain, uncomment this line in your ``.env`` file, and ensure it points to your ``pki_chain.pem`` file: +To use SSO with GitLab with a self-signed certificate, you have to add the PKI chain for your authority. This is required to avoid the ``Token request failed: certificate signed by unknown authority`` error. + +To add the PKI chain, uncomment the following line in your ``.env`` file, and ensure it points to your ``pki_chain.pem`` file: .. code-block:: sh #GITLAB_PKI_CHAIN_PATH=/pki_chain.pem -Then uncomment this line in your ``docker-compose.yml`` file, and ensure it points to the same ``pki_chain.pem`` file: +Then uncomment the following line in your ``docker-compose.yml`` file, and ensure it points to the same ``pki_chain.pem`` file: .. code-block:: sh # - ${GITLAB_PKI_CHAIN_PATH}:/etc/ssl/certs/pki_chain.pem:ro -Upgrade from ``mattermost-docker`` ------------------------------------ +**Upgrade from mattermost-docker** -Visit the `mattermost/docker `_ GitHub repository to access the official Docker deployment solution for Mattermost. - -.. note:: - - The `mattermost-docker `__ GitHub repository is deprecated. +The `mattermost-docker `__ GitHub repository is deprecated. Visit the `mattermost/docker `_ GitHub repository to access the official Docker deployment solution for Mattermost. To migrate from an existing ``mattermost/mattermost-prod-app`` image, we recommend migrating to either ``mattermost/mattermost-enterprise-edition`` or ``mattermost/mattermost-team-edition`` images, which are the official images supported by Mattermost. These images support PostgreSQL v11+ databases, which we know has been a long-running challenge for the community, and you will not lose any features or functionality by moving to these new images. For additional help or questions, please refer to `this issue `__. -Install a different version of Mattermost --------------------------------------------- +**Install a different version of Mattermost** 1. Shut down your deployment. @@ -173,11 +140,7 @@ Install a different version of Mattermost 4. Redeploy Mattermost. -Troubleshooting deployment --------------------------- - -Docker -~~~~~~ +**Troubleshooting your Docker deployment** If deploying on an M1 Mac and encountering permission issues in the Docker container, `redo the third step <#create-the-required-directores-and-set-their-permissions>`__ and skip this command: @@ -197,24 +160,59 @@ To remove all data and settings for your Mattermost deployment: sudo rm -rf ./volumes -PostgreSQL -~~~~~~~~~~~ +**Troubleshooting PostgreSQL** For quick start deployments, you can change the Postgres username and/or password (recommended) in the ``.env`` file. If your database is managed externally, you'll need to change the password in your database management tool. Then, update the ``.env`` file with the new credentials. -TLS & NGINX -~~~~~~~~~~~~ +**Troubleshooting TLS & NGINX** For an in-depth guide to configuring the TLS certificate and key for Nginx, please refer to `this document in the repository `__. -Further help -~~~~~~~~~~~~~ +**Trial Mattermost using Docker Preview** + +Looking for a way to evaluate Mattermost on a single local machine using Docker? We recommend using the `Mattermost Docker Preview Image `_ to install Mattermost in Preview Mode. -If you encounter other problems while installing Mattermost, please refer to our :doc:`troubleshooting guide `. +.. important:: + + - This local image is self-contained (i.e., it has an internal database and works out of the box). Dropping a container using this image removes data and configuration as expected. You can see the :doc:`configuration settings ` documentation to learn more about customizing your trial deployment. + - **Preview Mode** shouldn't be used in a production environment, as it uses a known password string, contains other non-production configuration settings, has email disabled, keeps no persistent data (all data lives inside the container), and doesn't support upgrades. + - If you are planning to use the calling functionality in **Preview Mode** on a non-local environment, you should ensure that the server is running on a secure (HTTPs) connection and that the :ref:`network requirements ` to run calls are met. + +1. Install `Docker `__. + +2. Once you have Docker, run the following command in a terminal window: + + .. code-block:: sh + + docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview + +3. When Docker is done fetching the image, navigate to ``http://localhost:8065/`` in your browser to preview Mattermost. +4. Select **Don't have an account** in the top right corner of the screen to create an account for your preview instance. If you don't see this option, ensure that the :ref:`Enable open server ` configuration setting is enabled. This setting is disabled for self-hosted Mattermost deployments by default. +5. Log in to your preview instance with your user credentials. + +**Troubleshooting your preview deployment** + +The **Preview Mode** Docker instance for Mattermost is designed for product evaluation, and sets ``SendEmailNotifications=false`` so the product can function without enabling email. See the :doc:`Configuration Settings ` documentation to customize your deployment. + +To update your Mattermost preview image and container, you must first stop and delete your existing **mattermost-preview** container by running the following commands: -Trial Mattermost using Docker Preview --------------------------------------- +.. code-block:: sh + + docker pull mattermost/mattermost-preview + docker stop mattermost-preview + docker rm mattermost-preview + +Once the new image is pulled and the container is stopped and deleted you need to run the ``docker run`` command from above. + +.. important:: + On Linux, include ``sudo`` in front of all ``docker`` commands. -Looking for a way to evaluate Mattermost in using Docker? We recommend using the `Mattermost Docker Preview Image `_ to install Mattermost in Preview Mode. +To access a shell inside the container, run the following command: + +.. code-block:: sh + + docker exec -ti mattermost-preview /bin/bash + +.. note:: -See the :doc:`trial Mattermost using Docker ` documentation for details. + See the :doc:`deployment troubleshooting ` documentation for resolutions to common deployment issues. \ No newline at end of file diff --git a/source/deploy/server/deploy-containers.rst b/source/deploy/server/deploy-containers.rst new file mode 100644 index 00000000000..7e1dd9bcdb1 --- /dev/null +++ b/source/deploy/server/deploy-containers.rst @@ -0,0 +1,101 @@ +Deploy Mattermost using Containers +================================== + +You can deploy Mattermost Server using container technologies for exploring functionality, testing, and development purposes, as it allows you to quickly set up a Mattermost instance without needing to manage the underlying infrastructure. +This deployment method shouldn't be used in production environments as it doesn't support clustered deployments or High Availability (HA) configurations out-of-the-box. + +Choose your preferred container platform below for specific deployment instructions: + +.. tab:: Docker + + .. include:: containers/install-docker.rst + +.. tab:: AWS Elastic Beanstalk + + .. include:: containers/install-aws-beanstalk.rst + +Secure your Mattermost deployment +--------------------------------- + +Deploying Mattermost using Docker containers can be made secure with proper configurations for HTTPS and reverse proxying. +This guide outlines the steps to set up TLS and an NGINX reverse proxy for your Mattermost deployment, ensuring secure communication between users and your server. + +1. Set Up an NGINX Container to serve as the reverse proxy. You can use NGINX either as a separate container or installed on the host machine. +2. Bind Volumes for NGINX Configuration and TLS Certificates: + + - Bind Docker volumes for NGINX configuration files and TLS certificates to ensure persistent and secure storage of these assets. + - Use permission restrictions on host directories where sensitive files such as TLS keys are stored. + +3. Create the NGINX Configuration File by designing a robust ``nginx.conf`` file to configure reverse proxying and HTTPS. Here's a basic example: + + .. code-block:: nginx + + server { + listen 443 ssl; + server_name your-domain.com; + + ssl_certificate /etc/nginx/certs/fullchain.pem; + ssl_certificate_key /etc/nginx/certs/privkey.pem; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!aNULL:!MD5; + + location / { + proxy_pass http://mattermost:8065; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto https; + } + } + +Verify the configuration with ``nginx -t`` before applying. + +4. Obtain TLS Certificates: + + - Use Let's Encrypt for free, automated certificates. Tools like Certbot can help automate the process. + - Alternatively, purchase certificates from a trusted certificate authority (CA) and ensure proper setup of intermediate and root certificate chains. + + Keep private keys secure and avoid storing them directly inside Docker images. + +5. Connect Containers Using Docker Networking: + + - Use Docker's networking features to isolate and link containers. + - Create a custom Docker bridge network to ensure secure communication. For example: + + .. code-block:: sh + + docker network create mattermost-network + + - Launch the Mattermost and NGINX containers on the same network: + + .. code-block:: sh + + docker network connect mattermost-network mattermost + docker network connect mattermost-network nginx + +6. Point your domain to the server IP address: + + Ensure your domain (e.g., your-domain.com) points to the public IP address of your server. If your IP is dynamic, consider setting up Dynamic DNS (DDNS) for seamless connectivity. + +7. After placing the certificates and updating the configuration, restart the NGINX container: + +8. Use logs (docker logs nginx) to troubleshoot and validate the container’s operation. + +9. Verify HTTPS Access by visiting ``https://your-domain.com`` in a web browser to confirm Mattermost is running securely over HTTPS. + +10. Use tools such as SSL Labs : https://www.ssllabs.com/ssltest/ to validate the quality of your TLS setup. + +11. Enable HTTP Strict Transport Security (HSTS) in your NGINX configuration to prevent downgrade attacks. + +12. Use NGINX rate-limiting features to restrict abusive traffic, such as excessive requests: + +Additionally, consider: + +- Use Docker's security features such as Seccomp profiles and AppArmor to secure your container runtime. +- Avoid running containers with elevated privileges ``--privileged`` and utilize user namespaces. +- Always use trusted images (e.g., official NGINX and Mattermost images) to prevent exposure to vulnerabilities in third-party images. +- Update Mattermost, NGINX, and Docker to their latest versions regularly to ensure patches for known vulnerabilities are applied. +- Set up proper firewall rules to restrict unauthorized access and monitor traffic using tools like Fail2Ban or Wazuh. + +By following these steps, your Mattermost deployment using Docker containers will be accessible securely over HTTPS with efficient proxying through NGINX. Implementing the additional security recommendations will further protect your environment against evolving threats. \ No newline at end of file diff --git a/source/deploy/server/deploy-kubernetes.rst b/source/deploy/server/deploy-kubernetes.rst new file mode 100644 index 00000000000..1135626095f --- /dev/null +++ b/source/deploy/server/deploy-kubernetes.rst @@ -0,0 +1,69 @@ +Deploy Mattermost on Kubernetes +=============================== + +Mattermost server can be deployed on various Kubernetes platforms, providing a scalable and robust infrastructure for your team communication needs. This guide covers deployment options for major cloud providers and general Kubernetes installations. + +Choose your preferred platform below for specific deployment instructions: + +.. tab:: Azure + + .. include:: kubernetes/deploy-k8s-aks.rst + +.. tab:: Other Kubernetes + + .. include:: kubernetes/deploy-k8s.rst + +Secure your Mattermost deployment +--------------------------------- + +Deploying Mattermost in a Kubernetes environment allows you to harness Kubernetes-native features for scalability, security, and ease of management. By using an Ingress resource in combination with an ingress controller, you can enable secure HTTPS access to Mattermost while managing routing and TLS certificates effectively. + +1. Deploy an ingress controller, such as the `NGINX Ingress Controller `_, in your Kubernetes cluster. +2. Define an Ingress resource to route external traffic to your Mattermost service. Below is an example Ingress manifest: + + .. code-block:: yaml + + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: mattermost-ingress + annotations: + nginx.ingress.kubernetes.io/ssl-redirect: "true" + nginx.ingress.kubernetes.io/proxy-body-size: "10m" # Customize client body size limit + nginx.ingress.kubernetes.io/proxy-read-timeout: "60" # Customize request timeout + spec: + tls: + - secretName: mattermost-tls # Reference to the TLS secret + rules: + - host: + http: + paths: + - path: / + pathType: ImplementationSpecific + backend: + service: + name: mattermost-service # Name of your Mattermost service + port: + number: 80 + +3. Secure HTTPS access by using TLS certificates. You can either: + + - Provide your own TLS certificate and private key. + - Automate TLS certificate issuance and management using `cert-manager `_. If you are providing your own TLS certificate, create a Kubernetes secret to store it. + - Ensure the Ingress resource references the secret name (mattermost-tls) in its tls section. + +4. Save your Ingress and TLS YAML manifests to files (e.g., ``ingress.yaml`` and ``tls.yaml``) and apply them to your cluster using Kubernetes command-line tools. + +Configure DNS by ensuring your domain name ``your-domain.com`` is properly pointed to the external IP address of your cluster or ingress controller. You can verify this using tools like nslookup or dig. + +5. After applying the Ingress, verify HTTPS Access by navigating to your domain (e.g., ``https://your-domain.com``) in a web browser to verify HTTPS access. If you encounter issues, check ingress controller logs (``kubectl logs -n ``, DNS records, and TLS configurations. + +6. Enable HSTS and Additional Security in your Ingress annotations. + +Additionally, consider: + +- Enforcing a minimum TLS version (e.g., TLS 1.2). +- Deploying a Web Application Firewall (WAF) for additional protection, if supported by your ingress controller. +- Limiting access using Kubernetes Network Policies. + +By following these steps, your Mattermost deployment in Kubernetes will be securely accessible over HTTPS using TLS. With an NGINX Ingress controller managing routing and proxying, and proper security practices in place, you'll have a robust setup ready for production use. \ No newline at end of file diff --git a/source/deploy/server/deploy-linux.rst b/source/deploy/server/deploy-linux.rst new file mode 100644 index 00000000000..c3420e2f089 --- /dev/null +++ b/source/deploy/server/deploy-linux.rst @@ -0,0 +1,36 @@ +Deploy Mattermost on Linux +========================== + +Mattermost Server can be deployed on various Linux distributions, providing a flexible and robust platform for smaller teams and non-commercial customers. We don't recommend deploying Mattermost Server and database on a single system for production use, but it is a good option for development and testing purposes. + +This page covers deployment options for major Linux distributions and installation methods. Choose your preferred platform below for specific deployment instructions: + +.. tab:: Ubuntu + + .. include:: linux/deploy-ubuntu.rst + +.. tab:: RHEL/CentOS + + .. include:: linux/deploy-rhel.rst + +.. tab:: Generic Linux + + .. include:: linux/deploy-tar.rst + +.. tab:: Omnibus Package + + .. include:: linux/deploy-omnibus.rst + +Secure your Mattermost deployment +--------------------------------- + +Configuring TLS and setting up an NGINX proxy ensures secure communication between clients and your Mattermost server. This setup allows you to serve HTTPS traffic while proxying requests to Mattermost. You don’t need TLS enabled within Mattermost itself as NGINX will handle HTTPS traffic. + +1. Install NGINX on the host server. See the :doc:`set up NGINX proxy ` documentation for details. +2. Obtain a TLS certificate from a trusted certificate authority (CA) or use a self-signed certificate for testing purposes. +3. Configure NGINX with TLS certificates to serve HTTPS traffic. NGINX serves as a proxy, forwarding requests to the Mattermost application running locally or on a separate server. + +.. note:: + + - Your Mattermost Server deployments requires a PostgreSQL database. See the :ref:`database preparation ` documentation for details on this prerequisite. + - See the :doc:`deployment troubleshooting ` documentation for resolutions to common deployment issues. \ No newline at end of file diff --git a/source/deploy/server/docker-troubleshooting.rst b/source/deploy/server/docker-troubleshooting.rst new file mode 100644 index 00000000000..851162e6dab --- /dev/null +++ b/source/deploy/server/docker-troubleshooting.rst @@ -0,0 +1,44 @@ +Docker deployment troubleshooting +==================================== + +Permission issues on M1 Mac +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you're deploying the Mattermost server using Docker on an M1 Mac and encountering permission issues in the Docker container, re-create the required directories and set their permissions, then skip the following command because it causes the deploy to stop working. + +.. code-block:: sh + + sudo chown -R 2000:2000 ./volumes/app/mattermost + +If you're experiencing issues deploying on Docker generally, ensure the docker daemon is enabled and running: + +.. code-block:: sh + + sudo systemctl enable --now docker + +To remove all data and settings for your Mattermost deployment: + +.. code-block:: sh + + sudo rm -rf ./volumes + +TLS and NGINX issues +~~~~~~~~~~~~~~~~~~~~ + +For an in-depth guide to configuring the TLS certificate and key for NGINX, please refer to `this document in the repository `__. + +Install a different version of Mattermost +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Shut down your deployment. + +2. Run ``git pull`` to fetch any recent changes to the repository, paying attention to any potential ``env.example`` changes. + +3. Adjust the ``MATTERMOST_IMAGE_TAG`` in the ``.env`` file to point your desired `enterprise `__ or `team `__ image version. + +4. Redeploy Mattermost. + +Upgrading from ``mattermost-docker`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For an in-depth guide to upgrading from the deprecated `mattermost-docker repository `__, please refer to `this document `__. For additional help, please refer to `this issue `__. \ No newline at end of file diff --git a/source/deploy/image-proxy.rst b/source/deploy/server/image-proxy.rst similarity index 78% rename from source/deploy/image-proxy.rst rename to source/deploy/server/image-proxy.rst index 90ee4f2884b..4353aa0cbad 100644 --- a/source/deploy/image-proxy.rst +++ b/source/deploy/server/image-proxy.rst @@ -1,15 +1,9 @@ -.. _image-proxy: +(Optional) Use an Image proxy +============================== -Image proxy -=========== - -.. include:: ../_static/badges/allplans-selfhosted.rst +.. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -Using an image proxy means that all requests for images made by Mattermost clients will go through the proxy instead of contacting third-party servers directly. This helps protect user privacy by preventing third-party servers from tracking who views an image. This also prevents the use of tracking pixels (invisible images that do the same thing without the user even seeing an image). - -Certain proxy servers also provide a layer of caching which can make loading images faster and more reliable. This caching also helps preserve posts by protecting them from dead images. - When enabled, the image proxy needs to be publicly accessible to both the Mattermost client and server. Mattermost clients will use the image proxy to load all external images. The Mattermost server will use the image proxy when possible, but will not use it when requesting content that may not be an image, such as for `image previews of plaintext URLs `_. @@ -40,6 +34,6 @@ For example, if the image proxy is located at ``https://image-proxy.mattermost.c - **Remote Image Proxy URL**: ``https://image-proxy.mattermost.com`` - **Remote Image Proxy Options**: ``CAMO_KEY``, which is the secret string used for the sample ``atmos/camo`` deployment. -.. image:: ../images/image-proxy.png +.. image:: ../../images/image-proxy.png :alt: Enable and configure an atmos/camo image proxy in the System Console by going to Environment > Image Proxy, specifying atmos/camo as the proxy type, providing the URL of the remote image proxy server, and by specifying the CAMO_KEY secret string. diff --git a/source/deploy/server/kubernetes/deploy-k8s-aks.rst b/source/deploy/server/kubernetes/deploy-k8s-aks.rst new file mode 100644 index 00000000000..b0ede0e826b --- /dev/null +++ b/source/deploy/server/kubernetes/deploy-k8s-aks.rst @@ -0,0 +1,100 @@ +You can use a supported `Azure Marketplace Container Offer `__ to install Mattermost on your existing Azure infrastructure. + +.. important:: + + You are responsible for Azure costs associated with any infrastructure you spin up to host a Mattermost server, and Azure credits cannot be applied towards the purchase of a Mattermost license. + +**Infrastructure pre-requisites** + +Deploying Mattermost on Azure AKS requires the following database and cluster prerequisites. + +- **PostgreSQL v13.0+ database**: Mattermost requires a pre-existing PostgreSQL database within your infrastructure. We recommend using `Azure Database for PostgreSQL - Flexible Server `_. Deploy one by following `this Microsoft quick start guide `_. We recommend using Private Access for your database. +- **Running AKS cluster**: Mattermost Azure Container Offer requires a pre-existing Kubernetes Cluster with an Ingress Controller pre-installed. We recommend creating a new AKS cluster with the `AGIC add-on enabled `_. Follow `this tutorial `_ to create a new AKS cluster with the add-on enabled. + +.. note:: + + - Connectivity should be already in place between the AKS cluster and the PostgreSQL database. + - Any pre-installed Ingress Controller within the cluster that supports the Ingress Kubernetes resource and TLS termination should work out of the box. + +**Deployment pre-requisites** + +Deploying Mattermost on Azure AKS requires the following deployment prerequisites. + +- **Valid DNS name and TLS certificates**: Mattermost relies on strong TLS certification in order to provide all the features to users. You need to have access to a DNS zone and be able to provide a valid TLS key and certificate for the Ingress Controller. +- **Mattermost License and AKS Capacity**: (Mattermost Enterprise only) If your deployment option is for more than ``100 users``, you must have more than 2 nodes on your AKS cluster to support High Availability, and you must provide a valid Mattermost License file. Providing a license is optional at this stage. You can enable a **30 day** Mattermost trial once the server is deployed. + +**Installation steps** + +The installation process includes deploying Mattermost and updating the server. + +**Step 1: Deploy Mattermost** + +1. Navigate to our `Azure Marketplace Container Offer `_ and get the offer. Alternatively, you can go to the ``Extensions + Applications`` section of your AKS cluster and install the Mattermost offering from there. Visit the `Microsoft cluster extensions documentation `_ to learn more. + +2. Choose the **Resource Group** and the **Region** of your installed AKS and PostgreSQL database. + + .. image:: /_static/images/azure/basics.png + :alt: An example of the Azure AKS Project details screen. + +3. Choose your AKS cluster. + + .. image:: /_static/images/azure/aks-cluster.png + :alt: An example of the Azure AKS cluster setup screen. + +4. Fill in the details for your PostgreSQL database. + + .. image:: /_static/images/azure/postgreSQL.png + :alt: An example of the Azure AKS Database setup screen. + +.. note:: + + - Connectivity should be already in place between the AKS cluster and the database. + - Database should already exist and the user specified must have full access. + +5. Adjust deployment details. + + .. image:: /_static/images/azure/deployment-details.png + :alt: An example of the Azure AKS Deployment Details setup screen. + +.. note:: + You can define a Deployment size to automatically adjust the installation. A valid Mattermost license is required for deployments of more than 100 users. + +6. Configure Mattermost installation hostname and Ingress details. The AGIC add-on is used in the following example to show the ingress annotations required. + + .. code-block:: yaml + + kubernetes.io/ingress.class: azure/application-gateway + appgw.ingress.kubernetes.io/ssl-redirect: "true" + +7. Upload yor own TLS certificates at this stage to take advantage of all Mattermost features. + + .. image:: /_static/images/azure/networking-details.png + :alt: An example of the Azure AKS Networking Details setup screen. + +8. Ensure that everything is running. You should be able to check the installed plugin from the **AKS Extensions + Applications** page under the **Settings** menu. + + a. When the deployment is complete, obtain the hostname or IP address of your Mattermost deployment using the following command: + + .. code-block:: sh + + kubectl -n mattermost-operator get ingress + + b. Get the resulting IP address from the ``ADDRESS`` column, and use your domain registration service to create a DNS record. + c. You should be good to go. + +Learn more about managing your Mattermost server by visiting the :doc:`Managing Mattermost ` documentation. + +**Step 2: Upgrade Mattermost** + +1. Visit the ``Extensions + Applications`` section of your AKS cluster where your Mattermost installation is deployed. +2. You can enable minor version auto upgrades since these are not updating Mattermost version +3. Expand the ``Configurarion Settings`` table and add the below configuration and the version you want to install as a value. + + .. code:: + + global.azure.mattermost.version + + .. image:: /_static/images/global-azure-mattermost-version.png + :alt: An example of using custom Mattermost version. + +4. Select **Save** and wait for the upgrade. \ No newline at end of file diff --git a/source/deploy/server/kubernetes/deploy-k8s.rst b/source/deploy/server/kubernetes/deploy-k8s.rst new file mode 100644 index 00000000000..23593802001 --- /dev/null +++ b/source/deploy/server/kubernetes/deploy-k8s.rst @@ -0,0 +1,237 @@ +You can use the Mattermost Kubernetes Operator to deploy Mattermost on Kubernetes using S3-compatible storage and a managed database service. While the operator supports a range of configurations, we strongly recommend using a cloud-native approach for production environments. + +**Prerequisites** + +Before you begin, ensure you have the following: + +* A functioning Kubernetes cluster (see the `Kubernetes setup guide `__). Your cluster should be running a `supported Kubernetes version `__. +* The `kubectl` command-line tool installed on your local machine (see the `kubectl installation guide `__). +* A fundamental understanding of Kubernetes concepts, such as deployments, pods, and applying manifests. +* Sufficient Kubernetes resources allocated based on your expected user load. Consult the `Mattermost Kubernetes Operator <#install-the-mattermost-operator>`__ documentation for resource requirements at different scales. + +**Installation steps** + +The installation process involves setting up necessary operators and then deploying Mattermost itself. + +**Step 1: Install the NGINX Ingress Controller** + +Follow the instructions in the `Kubernetes deployment documentation `_ to install the NGINX ingress controller on your Kubernetes cluster. Mattermost recommends installing the Nginx Operator via helm, regardless of platform you are installing to. + +**Step 2: Install the Mattermost Operator** + +The Mattermost Kubernetes Operator can be installed using Helm. + +1. Install Helm (version 3.13.0 or later). See the `Helm quickstart documentation `_ for installation instructions. + +2. Add the Mattermost Helm repository: + + .. code-block:: sh + + helm repo add mattermost https://helm.mattermost.com + +3. Create a file named ``config.yaml`` and populate it with the contents of the `Mattermost operator values file `_. This file allows for customization of the operator. + +4. Create a namespace for the Mattermost Operator: + + .. code-block:: sh + + kubectl create ns mattermost-operator + +5. Install the Mattermost Operator. If you don't specify a version, the latest version of the Mattermost Operator will be installed. + + .. code-block:: sh + + helm install mattermost/mattermost-operator -n + + For example: + + .. code-block:: sh + + helm install mattermost-operator mattermost/mattermost-operator -n mattermost-operator + + To use your custom ``config.yaml`` file: + + .. code-block:: sh + + helm install mattermost-operator mattermost/mattermost-operator -n mattermost-operator -f config.yaml + +**Step 3: Deploy Mattermost** + +.. note:: + + - A Mattermost Enterprise license is required for multi-server deployments. + - For single-server deployments without an Enterprise license, add ``Replicas: 1`` to the ``spec`` section in step 2 below. See the :doc:`high availability documentation ` for more on highly-available deployments. + +1. **(Mattermost Enterprise only)** Create a Mattermost license secret. Create a file named ``mattermost-license-secret.yaml`` with the following content, replacing ``[LICENSE_FILE_CONTENTS]`` with your actual license: + + .. code-block:: yaml + + apiVersion: v1 + kind: Secret + metadata: + name: my-mattermost-license + type: Opaque + stringData: + license: + +2. Create a Mattermost installation manifest file named ``mattermost-installation.yaml``. File names in this guide are suggestions; you can use different names. Use the following template, adjusting the values as needed: + + .. code-block:: yaml + + apiVersion: installation.mattermost.com/v1beta1 + kind: Mattermost + metadata: + name: # Example: mm-example-full + spec: + size: # Example: 5000users + ingress: + enabled: true + host: # Example: example.mattermost-example.com + annotations: + kubernetes.io/ingress.class: nginx + version: # Example: 9.3.0 + licenseSecret: "" # If you created a license secret, put the name here + + Key fields in the manifest include: + + * ``metadata.name``: The name of your Mattermost deployment in Kubernetes. + * ``spec.size``: The size of your installation (e.g., "100users", "1000users", etc.). + * ``spec.ingress.host``: The DNS name for your Mattermost installation. + * ``spec.version``: The Mattermost version. See the :doc:`server version archive ` for available versions. + * ``spec.licenseSecret``: The name of the Kubernetes secret containing your license (required for Enterprise). + + For a full list of configurable fields, see the `example manifest `_ and the `Custom Resource Definition `_. + +3. Create a file named ``mattermost-database-secret.yaml`` for database credentials. This secret must be in the same namespace as the Mattermost installation. + + .. code-block:: yaml + + apiVersion: v1 + data: + DB_CONNECTION_CHECK_URL: + DB_CONNECTION_STRING: + MM_SQLSETTINGS_DATASOURCEREPLICAS: + kind: Secret + metadata: + name: my-postgres-connection + type: Opaque + + Example for AWS Aurora with PostgreSQL: + + .. code-block:: yaml + + apiVersion: v1 + data: + DB_CONNECTION_CHECK_URL: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK + DB_CONNECTION_STRING: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK + MM_SQLSETTINGS_DATASOURCEREPLICAS: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLXJvLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK + kind: Secret + metadata: + name: my-postgres-connection + type: Opaque + +**Step 4: Create the Filestore Secret** + +Create a file named ``mattermost-filestore-secret.yaml`` to store the credentials for your object storage service (e.g., AWS S3, MinIO). This secret must be created in the same namespace where you intend to install Mattermost. The file should contain the following YAML structure: + +.. code-block:: yaml + + apiVersion: v1 + kind: Secret + metadata: + name: # Choose a descriptive name (e.g., my-s3-credentials) + type: Opaque + data: + accesskey: + secretkey: + +.. csv-table:: + :header: "Key", "Description", "Required" + + "accesskey", "Base64-encoded access key for your storage service.", "Yes" + "secretkey", "Base64-encoded secret key for your storage service.", "Yes" + "metadata.name", "The name of the Kubernetes secret.", "Yes" + +.. important:: + + The ``accesskey`` and ``secretkey`` values must be **base64-encoded**. Do not enter the raw keys directly. Use a command-line tool or online encoder to generate the base64 strings. + + **Example (AWS S3):** + + .. code-block:: yaml + + apiVersion: v1 + kind: Secret + metadata: + name: my-s3-credentials + type: Opaque + data: + accesskey: QUNDRVNTX0tFWQo= # Example: Replace with your actual encoded key + secretkey: U1VQRVJfU0VDUkVUX0tFWQo= # Example: Replace with your actual encoded key + +**Step 5: Configure the Mattermost Installation Manifest** + +1. Modify the ``mattermost-installation.yaml`` file (created in step 2) to connect Mattermost to your external database and object storage. Refer to the supported fields for guidance on where to add these configurations within the YAML structure. + +2. Connect to the database: + + a. Add the following to the ``spec`` section of your manifest: + + .. code-block:: yaml + + spec: + database: + external: + secret: # The name of the database secret (e.g., my-postgres-connection) + +3. Connect to Object Storage: + + a. Add the following to the ``spec`` section of your manifest: + + .. code-block:: yaml + + spec: + fileStore: + external: + url: # The URL of your storage service (e.g., s3.amazonaws.com) + bucket: # The name of your storage bucket + secret: # The name of the filestore secret (e.g., my-s3-credentials) + +4. If you are using Amazon S3, it's recommended to enable server-side encryption (SSE) and SSL. Add the following environment variables to the ``mattermostEnv`` section: + +TBD + + +**Review Mattermost Resource Status** + +After a Mattermost installation has been created with the Operator, you can review its status with the following: + +.. code-block:: sh + + kubectl -n [namespace] get mattermost + +The ``kubectl describe`` command can be used to obtain more information about the Mattermost server pods: + +.. code-block:: sh + + kubectl -n [namespace] describe pod + +**Follow logs** + +The following command can be used to follow logs on any kubernetes pod: + +.. code-block:: sh + + kubectl -n [namespace] logs -f [pod name] + +If the ``-n [namespace]`` is omitted, then the default namespace of the current context is used. We recommend specifying the namespace based on your deployment. + +This command can be used to review the Mattermost Operator or Mattermost server logs as needed. + +.. note:: + + - If you're new to Kubernetes or prefer a managed solution, consider using a service like `Amazon EKS `_, `Azure Kubernetes Service `_, `Google Kubernetes Engine `_, or `DigitalOcean Kubernetes `_.- While this guidance focuses on using external, managed services for your database and file storage, the Mattermost Operator *does* offer the flexibility to use other solutions. For example, you could choose to deploy a PostgreSQL database within your Kubernetes cluster using the CloudNative PG operator (or externally however you wish), or use a self-hosted MinIO instance for object storage. + - While using managed cloud services is generally simpler to maintain and our recommended approach for production deployments, using self-managed services like MinIO for storage and CloudNative PG for PostgreSQL are also valid options if you have the expertise to manage them. + - If you choose to use self-managed components, you'll need to adapt the instructions accordingly, pointing to your internal services instead. + - To customize your production deployment, refer to the :doc:`configuration settings documentation `. + - If you encounter issues during deployment, consult the :doc:`deployment troubleshooting guide `. \ No newline at end of file diff --git a/source/install/installing-mattermost-omnibus.rst b/source/deploy/server/linux/deploy-omnibus.rst similarity index 51% rename from source/install/installing-mattermost-omnibus.rst rename to source/deploy/server/linux/deploy-omnibus.rst index 5e2cf2d93f9..e09f6ad5d5a 100644 --- a/source/install/installing-mattermost-omnibus.rst +++ b/source/deploy/server/linux/deploy-omnibus.rst @@ -1,21 +1,7 @@ -Install Mattermost Omnibus -========================== - .. raw:: html
-
-

- - Available on all plans -

-

- - Self-hosted deployments -

-
-

Minimum system requirements:

    @@ -34,17 +20,27 @@ Install Mattermost Omnibus
-Mattermost Omnibus packages together all required components: the Enterprise Edition of Mattermost (free version), PostgreSQL database, and NGINX as the application proxy. It uses a custom CLI (``mmomni``) and ansible recipes to configure and connect these components. +Mattermost Omnibus packages together all required components: the :ref:`free version Mattermost Enterprise `, a PostgreSQL database, and NGINX as the application proxy. It uses a custom CLI (``mmomni``) and ansible recipes to configure and connect these components. **Omnibus supports Ubuntu distributions only.** -.. note:: +This Mattermost deployment includes 4 steps: add the Mattermost PPA repositories, install Mattermost Omnibus, and set up Omnibus, and update Omnibus. + +**Step 1: Add the Mattermost PPA repositories** + +.. important: + + The GPG public key has changed. You can `import the new public key `_ or run the automatic Mattermost PPA repository setup script provided below. Depending on your setup, additional steps may also be required, particularly for installations that didn't rely on the repository setup script. We recommend deleting the old key from ``/etc/apt/trusted.gpg.d`` before adding the apt repository. + + - For Ubuntu Focal - 20.04 LTS: - Omnibus supports Ubuntu distributions only. + ``sudo apt-key del A1B31D46F0F3A10B02CF2D44F8F2C31744774B28`` -Add the Mattermost PPA repositories ------------------------------------ + ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo apt-key add`` -.. include:: common-gpg-public-key-changed.rst - :start-after: :nosearch: + - For Ubuntu Jammy - 22.04 LTS and Ubuntu Noble - 24.04 LTS: + + ``sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg`` + + ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null`` In a terminal window, run the following repository setup command: @@ -59,35 +55,33 @@ This command sets up all required repositories and configures: - Certbot for SSL certificate management - Mattermost Omnibus repository -Install Mattermost Omnibus ---------------------------- +**Step 2: Install Mattermost Omnibus** -When installing Mattermost Omnibus, SSL is enabled by default to provide a secure connection between the Mattermost server and the Mattermost client. To install with SSL, run the following command: +1. When installing Mattermost Omnibus, SSL is enabled by default to provide a secure connection between the Mattermost server and the Mattermost client. To install with SSL, run the following command: .. code-block:: sh // Install Mattermost Omnibus with SSL enabled sudo apt install mattermost-omnibus -y -You're prompted to specify a domain name and email address that will be used to generate the SSL certificate, and deliver related communications. +.. tip:: -Just looking to try out Mattermost? Run the following command to install Omnibus without SSL: + Just looking to try out Mattermost? Run the following command to install Omnibus without SSL: -.. code-block:: sh + .. code-block:: sh - // Install Mattermost Omnibus without SSL - sudo MMO_HTTPS=false apt install mattermost-omnibus -y + // Install Mattermost Omnibus without SSL + sudo MMO_HTTPS=false apt install mattermost-omnibus -y -After all the packages are installed, Omnibus runs ansible scripts that configure all the platform components and starts the server. +2. You're prompted to specify a domain name and email address that will be used to generate the SSL certificate, and deliver related communications. -Next steps: +3. After all the packages are installed, Omnibus runs ansible scripts that configure all the platform components and starts the server. -1. Open a browser and navigate to your Mattermost domain either by domain name (e.g. ``mymattermostserver.com``), or by the server's IP address if you're not using a domain name. +4. Open a browser and navigate to your Mattermost domain either by domain name (e.g. ``mymattermostserver.com``), or by the server's IP address if you're not using a domain name. -2. Create your first Mattermost user, invite more users, and explore the Mattermost platform. +5. Create your first Mattermost user, invite more users, and explore the Mattermost platform. -Configure Mattermost Omnibus ------------------------------ +**Step 3: Configure Mattermost Omnibus** .. note:: @@ -97,9 +91,7 @@ Unlike traditional Mattermost installations, Omnibus stores its configuration di To modify Mattermost server settings within an Omnibus environment (with the exception of those listed below), you'll need to utilize the ``mmctl`` command-line tool. Specifically, the ``mmctl --local config edit`` command allows you to make the necessary adjustments. For detailed instructions and options, refer to the :doc:`mmctl ` documentation. -Please note that certain configuration parameters, such as the Mattermost server port, must remain unchanged to ensure optimal Omnibus functionality. - -The following parameters must be configured directly using the ``mmomni.yml`` file: +Please note that certain configuration parameters, such as the Mattermost server port, must remain unchanged to ensure optimal Omnibus functionality. The following parameters must be configured directly using the ``mmomni.yml`` file: * ``db_user``: The PostgreSQL database user. This value is generated during the Omnibus installation and should not be changed. * ``db_password``: The PostgreSQL database password. This value is generated during the Omnibus installation and should not be changed. @@ -113,21 +105,19 @@ The following parameters must be configured directly using the ``mmomni.yml`` fi After modifying the ``mmomni.yml`` configuration file, run ``mmomni reconfigure`` to apply the changes, and then restart the Mattermost server with ``systemctl restart mattermost``. -Update Mattermost Omnibus -------------------------- +**Step 4: Update Mattermost Omnibus** -Mattermost Omnibus is integrated with the apt package manager. When a new Mattermost version is released, run the following command to download and update your Mattermost instance: +Mattermost Omnibus is integrated with the apt package manager. -.. code-block:: sh +Before updating Mattermost , we strongly recommend stopping the Mattermost server by running the command ``sudo systemctl stop mattermost``. - sudo apt update && sudo apt upgrade +Run the following command to download and update your Mattermost instance (along with any other packages): -.. note:: +.. code-block:: sh - When you run the ``sudo apt upgrade`` command, Mattermost will be updated along with any other packages. Before running the ``apt`` command, we strongly recommend stopping the Mattermost server by running the command ``sudo systemctl stop mattermost``. + sudo apt update && sudo apt upgrade -Backup and restore ------------------- +**Backup and restore** The Mattermost Omnibus CLI tool ``mmomni`` simplifies server and domain migration, as well as backup and restore. You can easily create snapshots of your entire Mattermost server, including all content, users, plugins, configurations, and databases. These snapshots can be restored to the same server or a different one. @@ -144,37 +134,23 @@ To restore the contents of your Mattermost server, run the following two command mmomni restore /tmp/mm_backup_datetime.tgz mmomni reconfigure -Remove Mattermost Omnibus -------------------------- +**Remove Mattermost Omnibus** -If you want to remove Mattermost and Mattermost Omnibus completely for any reason, you can run the following command: +Run the following command to remove Mattermost and Mattermost Omnibus completely: .. code-block:: sh sudo apt remove --purge mattermost mattermost-omnibus -Frequently asked questions --------------------------- - -Can I use a license with Omnibus? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes. Mattermost Omnibus bundles the free, unlicensed Mattermost Enterprise Edition, and Enterprise features are unlocked when you purchase and upload a license. - -Can I use an Omnibus server as part of a cluster? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Frequently asked questions** -No, Omnibus is designed to be a self-contained single server Mattermost platform. It expects all the necessary components to be on the same server. +Can I use a license with Omnibus? **Yes.** Mattermost Omnibus bundles the free, unlicensed Mattermost Enterprise Edition, and Enterprise features are unlocked when you purchase and upload a license. -Does the SSL Certificate automatically renew? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Can I use an Omnibus server as part of a cluster? **No.** Omnibus is designed to be a self-contained single server Mattermost platform. It expects all the necessary components to be on the same server. -Yes. The SSL certificate automatically updated and renewed. Omnibus installs the certbot package to manage the certificate, and it comes with a cron job that you can find at /etc/cron.d/certbot that automatically launches the renewal process. +Does the SSL Certificate automatically renew? **Yes.** The SSL certificate automatically updated and renewed. Omnibus installs the certbot package to manage the certificate, and it comes with a cron job that you can find at /etc/cron.d/certbot that automatically launches the renewal process. -How do I fix an EXPKEYSIG error on upgrades? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the rare case that you encounter an ``EXPKEYSIG`` error when upgrading, this indicates that your certificate is expired. To obtain a new certificate, run the following commands: +How do I fix an EXPKEYSIG error on upgrades? **This error indicates that your certificate is expired.** Run the following commands to obtain a new certificate: .. code-block:: sh @@ -182,33 +158,17 @@ In the rare case that you encounter an ``EXPKEYSIG`` error when upgrading, this sudo curl -o- https://deb.packages.mattermost.com/pubkey.gpg | sudo apt-key add - sudo apt update -Can I use a custom NGINX template? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes. Mattermost Omnibus supports using a custom NGINX template to generate its configuration. - -To use this feature, you need to copy and modify the original template located at ``/opt/mattermost/mmomni/ansible/playbooks/mattermost.conf`` to a new location. Then, you can either use the variables and internal logic already bundled in the template and modify the parts that you need, or use a fully static configuration instead. - -After the template has been customized, add an ``nginx_template`` property to the ``/etc/mattermost/mmomni.yml`` configuration file, and then run ``mmomni reconfigure``. The reconfigure process will use the new template to generate the NGINX final configuration. You can check the contents of the ``/etc/nginx/conf.d/mattermost.conf`` file to validate that the changes were applied successfully. +Can I use a custom NGINX template? **Yes.** Mattermost Omnibus supports using a custom NGINX template to generate its configuration. -.. note:: - - Please use caution when using this feature. Making changes to the custom template can cause the reconfigure process to fail, or the generated NGINX configuration to be invalid. +- To use this feature, you need to copy and modify the original template located at ``/opt/mattermost/mmomni/ansible/playbooks/mattermost.conf`` to a new location. +- **Use caution when using this feature.** Making changes to the custom template can cause the reconfigure process to fail, or the generated NGINX configuration to be invalid. +- Then, you can either use the variables and internal logic already bundled in the template and modify the parts that you need, or use a fully static configuration instead. +- After the template has been customized, add an ``nginx_template`` property to the ``/etc/mattermost/mmomni.yml`` configuration file, and then run ``mmomni reconfigure``. The reconfigure process will use the new template to generate the NGINX final configuration. You can check the contents of the ``/etc/nginx/conf.d/mattermost.conf`` file to validate that the changes were applied successfully. What ``mmomni`` commands are available? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ``mmomni backup``: Takes a complete snapshot of your Mattermost server and places the backup file in a specified file location. - - ``mmomni restore``: Restores specified backup file to your Mattermost server. - - ``mmomni reconfigure``: Reruns the process that changes domain, SSL, or any Omnibus-specified restrictions such as the ability to upload plugins. It also applies any changes made to the mmomni.yml configuration file. - - ``mmomni status``: Shows current status of all Omnibus components. - -- ``mmomni tail``: Runs a join tail of logs of all Omnibus components. - -Where can I get help? -~~~~~~~~~~~~~~~~~~~~~ - -If you have any problems installing Mattermost Omnibus, see the :doc:`troubleshooting guide ` for common error messages, or `join the Mattermost user community for troubleshooting help `__. +- ``mmomni tail``: Runs a join tail of logs of all Omnibus components. \ No newline at end of file diff --git a/source/deploy/server/linux/deploy-rhel.rst b/source/deploy/server/linux/deploy-rhel.rst new file mode 100644 index 00000000000..61642e66b07 --- /dev/null +++ b/source/deploy/server/linux/deploy-rhel.rst @@ -0,0 +1,240 @@ +.. raw:: html + +
+ +
+

Minimum system requirements:

+
    +
  • Operating System: Enterprise Linux 7+, Oracle Linux 6+, Oracle Linux 7+ +
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
    • +
  • Database: PostgreSQL v13+
    • +
  • Network: +
      +
    • Application 80/443, TLS, TCP Inbound
      • +
    • Administrator Console 8065, TLS, TCP Inbound
      • +
    • SMTP port 10025, TCP/UDP Outbound
      • +
    +
    • +
+
+ +
+ +You can deploy Mattermost Server using our ``rpm`` signed packages available through the Mattermost Yum repository. + +This Mattermost deployment includes 4 steps: download, install Matermost server, set up the server, and update the server. + +**Step 1: Download the latest Mattermost Server tarball** + +In a terminal window, ssh onto the system that will host the Mattermost Server. + +Using ``wget``, download the Mattermost Server release you want to install. + +.. tab:: Latest release + + .. code-block:: sh + + wget https://releases.mattermost.com/10.6.1/mattermost-10.6.1-linux-amd64.tar.gz + +.. tab:: Current ESR + + .. code-block:: sh + + wget https://releases.mattermost.com/10.5.2/mattermost-10.5.2-linux-amd64.tar.gz + +.. tab:: Older releases + + If you are looking for an older release, Enterprise and Team Edition releases can be found in our :doc:`version archive ` documentation. + +**Step 2: Install Mattermost server** + +1. Ahead of installing the Mattermost Server, we recommend updating all your repositories and, where required, update existing packages by running the following commands: + + .. code-block:: sh + + sudo dnf update + sudo dnf upgrade + +2. After any updates, and any system reboots, are complete, install the Mattermost Server by extracting the tarball, creating users and groups, and setting file/folder permissions. + + a. First extract the tarball: + + .. code-block:: sh + + tar -xvzf mattermost*.gz + + b. Now move the entire folder to the ``/opt`` directory (or whatever path you require): + + .. code-block:: sh + + sudo mv mattermost /opt + +.. note:: + + If you choose a custom path, ensure this alternate path is used in all steps that follow.` + +3. Create the default storage folder. By default the Mattermost Server uses ``/opt/mattermost/data`` as the folder for files. This can be changed in the System Console during setup (even using alternative storage such as S3): + + .. code-block:: sh + + sudo mkdir /opt/mattermost/data + +4. Set up a user and group called ``mattermost``: + + .. code-block:: sh + + sudo useradd --system --user-group mattermost + +.. note:: + + If you choose a custom user and group name, ensure it is used in all the steps that follow. + +5. Set the file and folder permissions for your installation: + + .. code-block:: sh + + sudo chown -R mattermost:mattermost /opt/mattermost + +6. Give the ``mattermost`` group write permissions to the application folder: + + .. code-block:: sh + + sudo chmod -R g+w /opt/mattermost + +You will now have the latest Mattermost Server version installed on your system. Starting and stopping the Mattermost Server is done using ``systemd``. + +7. Create the systemd unit file: + + .. code-block:: sh + + sudo touch /lib/systemd/system/mattermost.service + +8. As root, edit the systemd unit file to add the following lines: + + .. code-block:: text + + [Unit] + Description=Mattermost + After=network.target + + [Service] + Type=notify + ExecStart=/opt/mattermost/bin/mattermost + TimeoutStartSec=3600 + KillMode=mixed + Restart=always + RestartSec=10 + WorkingDirectory=/opt/mattermost + User=mattermost + Group=mattermost + LimitNOFILE=49152 + + [Install] + WantedBy=multi-user.target + +9. Save the file and reload systemd using ``sudo systemctl daemon-reload``. Mattermost Server is now installed and is ready for setup. + +**Step 3: Set up the server** + +Before you start the Mattermost Server, you need to edit the configuration file. A default configuration file is located at ``/opt/mattermost/config/config.json``. We recommend taking a backup of this default config ahead of making changes: + +.. code-block:: sh + + sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json + +Configure the following properties in this file: + +* Under ``SqlSettings``, set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations. +* Under ``SqlSettings``, set ``DataSource`` to ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ```` and ``mattermost`` with your database name. +* Under ``ServiceSettings``, set ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``). + +.. note:: + + We recommend configuring the `Support Email `_ under ``SupportSettings``, set ``"SupportEmail"``. This is the email address your users will contact when they need help. + +After modifying the ``config.json`` configuration file, you can now start the Mattermost server: + +.. code-block:: sh + + sudo systemctl start mattermost + +Verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that’s returned by the Mattermost Server. + +The final step, depending on your requirements, is to run sudo ``systemctl enable mattermost.service`` so that Mattermost will start on system boot. If you don't receive an error when starting Mattermost after the previous step, you are good to go. If you did receive an error, continue on. + +.. important:: + + **Modify SELinux settings**: When deploying Mattermost from RHEL9, which has SELinux running with enforceing mode enabled by default, additional configuration is required. + + - SELinux is a security module that provides access control security policies. It's enabled by default on RHEL and CentOS systems. SELinux can block access to files, directories, and ports, which can cause issues when starting Mattermost. To resolve these issues, you'll need to set the appropriate SELinux contexts for the Mattermost binaries and directories, and allow Mattermost to bind to ports. + - Ensure that SELinux is enabled and in enforcing mode by running the ``sestatus`` command. If it's ``enforcing``, you'll need to configure it properly. + - Set bin contexts for ``/opt/mattermost/bin``: SELinux enforces security contexts for binaries. To label the Mattermost binaries as safe, you'll need to set them to the below SELinux context. + + .. code-block:: sh + + sudo semanage fcontext -a -t bin_t "/opt/mattermost/bin(/.*)?" + sudo restorecon -RF /opt/mattermost/bin + + Now, try starting Mattermost again with + + .. code-block:: sh + + sudo systemctl start mattermost + + If you don't receive an error, verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that's returned by the Mattermost Server. You're all set! + + + If on starting Mattermost you receive an error, before moving on, check for the existence of a file in ``/opt/mattermost/logs`` - if ``mattermost.log`` exists in that directory, it's more likely you're dealing with a configuration issue in ``config.json``. Double check the previous steps before continuing + + Try different contexts for ``/opt/mattermost``: SELinux enforces security contexts for files and directories. To label your Mattermost directory as safe, you'll need to set an appropriate SELinux context. + + 1. Check current context by running ``ls -Z /opt/mattermost``. When you see something like ``drwxr-xr-x. root root unconfined_u:object_r:default_t:s0 mattermost`` returned, the ``default_t`` indicates that SELinux doesn't know what this directory is for. + 2. Set a safe context by assigning a SELinux type that's compatible with web services or applications by running ``sudo semanage fcontext -a -t httpd_sys_content_t "/opt/mattermost(/.*)?"``. A common one is ``httpd_sys_content_t``, used for serving files. Ensure you match the directory and its contents recursively. Run the ``sudo restorecon -R /opt/mattermost`` to apply the changes. + + Allow Mattermost to bind to ports: When Mattermost needs specific ports (e.g., 8065), ensure that SELinux allows it by allowing Mattermost to bind to ports. Run the ``sudo semanage port -l | grep 8065`` command, and if the port's not listed, you'll need to add it by running ``sudo semanage port -a -t http_port_t -p tcp 8065``, replacing the ``8065`` with the required port. + + Handle custom policies: If Mattermost requires actions that SELinux blocks, you'll need to generate a custom policy. + + 1. Check for SELinux denials first in the logs by running ``sudo ausearch -m avc -ts recent``, or by checking the audit log: ``sudo cat /var/log/audit/audit.log | grep denied``. + + 2. If needed, generate a policy module by installing ``audit2allow`` to generate policies automatically. + + .. code-block:: sh + + sudo yum install -y policycoreutils-python-utils + sudo grep mattermost /var/log/audit/audit.log | audit2allow -M mattermost_policy + sudo semodule -i mattermost_policy.pp + + Test the configuration: Restart Mattermost to confirm the configuation works as expected by running ``sudo systemctl restart mattermost``. In the case of failures, revisit the logs to identify other SELinux-related issues. + + Need Mattermost working quickly for testing purposes? + + - You can change SELinux to permissive mode by running the ``sudo setenforce 0``. command where policies aren't enforced, only logged. + - This command changes the SELinux mode to "permissive". While in permissive mode, policies aren't enforced, and violations are logged instead of being blocked. This can be helpful for debugging and troubleshooting issues related to SELinux policies. + - Ensure you re-enable enforcing mode once context is working as needed by running the ``sudo setenforce 1`` command. + + See the following SELinux resources for additional details: + + - `SELinux User's and Administrator's Guide `_ + - `SELinux Project Wiki `_ + - `Introduction to SELinux `_ + - `A Sysadmin's Guide to SELinux: 42 Answers to the Big Questions `_ + - `Mastering SELinux: A Comprehensive Guide to Linux Security `_ + +**Step 3: Update the server** + +Updating your Mattermost Server installation when using the tarball requires several manual steps. See the :doc:`upgrade Mattermost Server ` documentation for details. + +**Remove Mattermost** + +To remove the Mattermost Server, you must stop the Mattermost Server, back up all important files, and then run this command: + +.. code-block:: sh + + sudo rm /opt/mattermost + +.. note:: + + Depending on your configuration, there are several important folders in ``/opt/mattermost`` to backup. These are ``config``, ``logs``, ``plugins``, ``client/plugins``, and ``data``. We strongly recommend you back up these locations before running the ``rm`` command. + +You may also remove the Mattermost systemd unit file and the user/group created for running the application. \ No newline at end of file diff --git a/source/deploy/server/linux/deploy-tar.rst b/source/deploy/server/linux/deploy-tar.rst new file mode 100644 index 00000000000..1c4a6fddb06 --- /dev/null +++ b/source/deploy/server/linux/deploy-tar.rst @@ -0,0 +1,175 @@ +.. raw:: html + +
+ +
+

Minimum system requirements:

+
    +
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
    • +
  • Database: PostgreSQL v13+
    • +
  • Network: +
      +
    • Application 80/443, TLS, TCP Inbound
      • +
    • Administrator Console 8065, TLS, TCP Inbound
      • +
    • SMTP port 10025, TCP/UDP Outbound
      • +
    +
    • +
+
+ +
+ +You can install the Mattermost Server on any 64-bit Linux system using the tarball. This is the most flexible installation method, but it comes with the highest effort, typically favored by advanced system administrators. + +This Mattermost deployment includes 3 steps: download, install Mattermost server, and set up the server. + +**Step 1: Download** + +In a terminal window, ssh onto the system that will host the Mattermost Server. + +Using ``wget``, download the Mattermost Server release you want to install. + +.. tab:: Latest release + + .. code-block:: sh + + wget https://releases.mattermost.com/10.6.1/mattermost-10.6.1-linux-amd64.tar.gz + +.. tab:: Current ESR + + .. code-block:: sh + + wget https://releases.mattermost.com/10.5.2/mattermost-10.5.2-linux-amd64.tar.gz + +.. tab:: Older releases + + If you are looking for an older release, Enterprise and Team Edition releases can be found in our :doc:`version archive ` documentation. + +**Step 2: Install Mattermost server** + +Install the Mattermost Server by extracting the tarball, creating users and groups, and setting file/folder permissions. + +1. First extract the tarball: + + .. code-block:: sh + + tar -xvzf mattermost*.gz + +2. Move the entire folder to the ``/opt`` directory (or whatever path you require): + + .. code-block:: sh + + sudo mv mattermost /opt + +.. note:: + + If you choose a custom path, ensure this alternate path is used in all steps that follow. + +3. Create the default storage folder. By default the Mattermost Server uses ``/opt/mattermost/data`` as the folder for files. This can be changed in the System Console during setup (even using alternative storage such as S3). + + .. code-block:: sh + + sudo mkdir /opt/mattermost/data + +4. Set up a user and group called ``mattermost``: + + .. code-block:: sh + + sudo useradd --system --user-group mattermost + +.. note:: + + If you choose a custom user and group name, ensure it is used in all the steps that follow. + +5. Set the file and folder permissions for your installation: + + .. code-block:: sh + + sudo chown -R mattermost:mattermost /opt/mattermost + +6. Give the ``mattermost`` group write permissions to the application folder: + + .. code-block:: sh + + sudo chmod -R g+w /opt/mattermost + +You will now have the latest Mattermost Server version installed on your system. Starting and stopping the Mattermost Server is done using ``systemd``. + +7. Create the systemd unit file: + + .. code-block:: sh + + sudo touch /lib/systemd/system/mattermost.service + +8. As root, edit the systemd unit file to add the following lines: + + .. code-block:: text + + [Unit] + Description=Mattermost + After=network.target + + [Service] + Type=notify + ExecStart=/opt/mattermost/bin/mattermost + TimeoutStartSec=3600 + KillMode=mixed + Restart=always + RestartSec=10 + WorkingDirectory=/opt/mattermost + User=mattermost + Group=mattermost + LimitNOFILE=49152 + + [Install] + WantedBy=multi-user.target + +.. note:: + + If you are installing the Mattermost server on the same system as your database, you may want to add both ``After=postgresql.service`` and ``BindsTo=postgresql.service`` to the ``[Unit]`` section of the systemd unit file. + +9. Save the file and reload systemd using ``sudo systemctl daemon-reload``. Mattermost Server is now installed and is ready for setup. + +**Step 3: Set up the server** + +Before you start the Mattermost Server, you need to edit the configuration file. A default configuration file is located at ``/opt/mattermost/config/config.json``. We recommend taking a backup of this default config ahead of making changes: + +.. code-block:: sh + + sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json + +Configure the following properties in this file: + +* Under ``SqlSettings``, set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations. +* Under ``SqlSettings``, set ``DataSource`` to ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ```` and ``mattermost`` with your database name. +* Under ``ServiceSettings``, set ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``). + +We recommend configuring the `Support Email `_ under ``SupportSettings``, set ``"SupportEmail"``. This is the email address your users will contact when they need help. + +After modifying the ``config.json`` configuration file, you can now start the Mattermost server: + +.. code-block:: sh + + sudo systemctl start mattermost + +Verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that’s returned by the Mattermost Server. + +The final step, depending on your requirements, is to run sudo ``systemctl enable mattermost.service`` so that Mattermost will start on system boot. + +**Step 4: Update the server** + +Updating your Mattermost Server installation when using the tarball requires several manual steps. See the :doc:`upgrade Mattermost Server ` documentation for details. + +**Remove Mattermost** + +To remove the Mattermost Server for any reason, you must stop the Mattermost Server, back up all important files, and then run this command: + +.. code-block:: sh + + sudo rm - rf /opt/mattermost + +.. note:: + + Depending on your configuration, there are several important folders in ``/opt/mattermost`` to backup. These are ``config``, ``logs``, ``plugins``, ``client/plugins``, and ``data``. We strongly recommend you back up these locations before running the ``rm`` command. + +You may also remove the Mattermost systemd unit file and the user/group created for running the application. \ No newline at end of file diff --git a/source/deploy/server/linux/deploy-ubuntu.rst b/source/deploy/server/linux/deploy-ubuntu.rst new file mode 100644 index 00000000000..c24995bc970 --- /dev/null +++ b/source/deploy/server/linux/deploy-ubuntu.rst @@ -0,0 +1,125 @@ +.. raw:: html + +
+ +
+

Minimum system requirements:

+
    +
  • Operating System: 20.04 LTS, 22.04 LTS, 24.04 LTS +
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
    • +
  • Database: PostgreSQL v13+
    • +
  • Network: +
      +
    • Application 80/443, TLS, TCP Inbound
      • +
    • Administrator Console 8065, TLS, TCP Inbound
      • +
    • SMTP port 10025, TCP/UDP Outbound
      • +
    +
    • +
+
+ +
+ +You can deploy Mattermost server using our ``.deb`` signed packages using the Mattermost PPA (Personal Package Archive). This is the quickest way to install a Mattermost Server that provides automatic updates. This install method is used for both single and clustered installations, as you can tools like Packer for a clustered deployment. + +.. tip:: + + Alternatively, an **Omnibus Package** deployment bundles together all required components to greatly reduce setup and ongoing maintenance, including Mattermost Server, a PostgreSQL database, NGINX as the application proxy, a custom CLI, and ansible recipes to configure and connect these components. + +This Mattermost deployment includes 4 steps: add the PPA repository, install Mattermost server, configure the server, and update the server. + +**Step 1: Add the Mattermost Server PPA repository** + +.. important:: + + The GPG public key has changed. You can `import the new public key `_ or run the automatic Mattermost PPA repository setup script provided below. Depending on your setup, additional steps may also be required, particularly for installations that didn't rely on the repository setup script. We recommend deleting the old key from ``/etc/apt/trusted.gpg.d`` before adding the apt repository. + + - For Ubuntu Focal - 20.04 LTS: + + ``sudo apt-key del A1B31D46F0F3A10B02CF2D44F8F2C31744774B28`` + + ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo apt-key add`` + + - For Ubuntu Jammy - 22.04 LTS and Ubuntu Noble - 24.04 LTS: + + ``sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg`` + + ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null`` + +In a terminal window, run the following repository setup command to add the Mattermost Server repositories: + +.. code-block:: sh + + curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost + +This command configures the repositories needed for a PostgreSQL database, configures an NGINX web server to act as a proxy, configures certbot to issue and renew the SSL certificate, and configures the Mattermost Omnibus repository so that you can run the install command. + +**Step 2: Instal Mattermost server** + +Ahead of installing the Mattermost Server, it's good practice to update all your repositories and, where required, update existing packages by running the following command: + +.. code-block:: sh + + sudo apt update + +After any updates and system reboots are complete, you can install the Mattermost Server by running: + +.. code-block:: sh + + sudo apt install mattermost -y + +You now have the latest Mattermost Server version installed on your system. + +The installation path is ``/opt/mattermost``. The package will have added a user and group named ``mattermost``. The required systemd unit file has also been created but will not be set to active. + +.. note:: + + Since the signed package from the Mattermost repository is used for mulitple installation types, we don't add any dependencies in the systemd unit file. If you are installing the Mattermost server on the same system as your database, you may want to add both ``After=postgresql.service`` and ``BindsTo=postgresql.service`` to the ``[Unit]`` section of the systemd unit file. + +**Step 3: Configure the server** + +Before you start the Mattermost Server, you need to edit the configuration file. A sample configuration file is located at ``/opt/mattermost/config/config.defaults.json``. + +Rename this configuration file with correct permissions: + +.. code-block:: sh + + sudo install -C -m 600 -o mattermost -g mattermost /opt/mattermost/config/config.defaults.json /opt/mattermost/config/config.json + +Configure the following properties in this file: + +* Under ``SqlSettings``, set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations. +* Under ``SqlSettings``, set ``DataSource`` to ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ```` and ``mattermost`` with your database name. +* Under ``ServiceSettings``, set ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``). + +We recommend configuring the `Support Email `_ under ``SupportSettings``, set ``"SupportEmail"``. This is the email address your users will contact when they need help. + +After modifying the ``config.json`` configuration file, you can now start the Mattermost Server: + +.. code-block:: sh + + sudo systemctl start mattermost + +Verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that's returned by the Mattermost Server. + +The final step, depending on your requirements, is to run ``sudo systemctl enable mattermost.service`` so that Mattermost will start on system boot. + +.. note:: + + The value of the ``sslmode`` property in the ``DataSource`` configuration is entirely dependent on your native environment. Please consult the native environment setup documentation for guidance on its value. The available options for ``sslmode`` are ``disable`` or ``require``. For example, if you are using Amazon Lightsail as your data source, you must set ``sslmode`` to ``require`` to successfully connect to the database. + +**Step 4: Update the server** + +When a new Mattermost version is released, run: ``sudo apt update && sudo apt upgrade`` to download and update your Mattermost instance. + +.. note:: + + When you run the ``sudo apt upgrade`` command, ``mattermost-server`` will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the ``apt`` command using ``sudo systemctl stop mattermost``. + +**Remove Mattermost** + +Run the following command to remove the Mattermost Server: + +.. code-block:: sh + + sudo apt remove --purge mattermost \ No newline at end of file diff --git a/source/deploy/server/preparations.rst b/source/deploy/server/preparations.rst new file mode 100644 index 00000000000..05a0c6e0765 --- /dev/null +++ b/source/deploy/server/preparations.rst @@ -0,0 +1,210 @@ +Prepare your Mattermost Server environment +=========================================== + +This guide outlines the key preparation steps required before installing the Mattermost Server, focusing on setting up the database and file storage systems. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Review software and hardware requirements + (Recommended) Set up an NGINX proxy + (Recommended) Configure Mattermost Calls + (Recommended) Enable Mattermost Copilot + (Optional) Set up TLS + (Optional) Use an image proxy + (Optional) Configure CloudFront to host Mattermost static assets + (Optional) Use an outbound proxy + (Optional) Use sockets to set up the database + +Database preparation +-------------------- + +Mattermost requires a PostgreSQL database (version 13 or higher). While MySQL was previously supported, PostgreSQL is now the recommended and preferred database. + +.. important:: + + - PostgreSQL v13+ is required for Mattermost server installations. :doc:`MySQL database support ` is being deprecated starting with Mattermost v11. See the :doc:`PostgreSQL migration ` documentation for guidance on migrating from MySQL to PostgreSQL. + - Learn how to :doc:`use sockets to set up the database `. + +1. Create an PostgreSQL server instance: + + .. tab:: AWS + + .. code-block:: sh + + sudo apt update + sudo apt install postgresql + + .. tab:: Azure + + .. code-block:: sh + + sudo apt update + sudo apt install postgresql + + .. tab:: Ubuntu/Debian + + .. code-block:: sh + + sudo apt update + sudo apt install postgresql + + .. tab:: RHEL/CentOS + + .. code-block:: sh + + sudo dnf install postgresql-server + sudo postgresql-setup --initdb + +2. Create the Mattermost database and user: + + a. Access PostgreSQL by running: + + .. code-block:: sh + + sudo -u postgres psql + + b. Create the database: + + .. code-block:: sql + + CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0; + + c. Create the Mattermost user with a secure password: + + .. code-block:: sql + + CREATE USER mmuser WITH PASSWORD 'mmuser-password'; + + d. Grant database access to the user: + + .. code-block:: sql + + GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser; + + e. If using PostgreSQL v15.x or later, additional grants are required: + + .. code-block:: sql + + ALTER DATABASE mattermost OWNER TO mmuser; + GRANT USAGE, CREATE ON SCHEMA PUBLIC TO mmuser; + +3. Configure PostgreSQL for remote connections (if database is on a separate server): + + a. Edit ``postgresql.conf`` to allow remote connections: + + .. tab:: Ubuntu/Debian + + Edit ``/etc/postgresql/{version}/main/postgresql.conf``: + + .. code-block:: text + + listen_addresses = '*' + + .. tab:: RHEL/CentOS + + Edit ``/var/lib/pgsql/{version}/data/postgresql.conf``: + + .. code-block:: text + + listen_addresses = '*' + + b. Configure client authentication by editing ``pg_hba.conf``: + + Add the following line, replacing ``{mattermost-server-IP}``: + + .. code-block:: text + + host all all {mattermost-server-IP}/32 md5 + +.. important:: + + If you are upgrading a major version of Postgres, ensure that ``ANALYZE VERBOSE`` is run on the database post upgrade. This is required to re-populate the ``pg_statistics`` table used to generate optimal query plans. Database performance may suffer if this step is skipped. + +File storage preparation +------------------------- + +Mattermost requires a file storage system for storing user files, images, and attachments. You have several options, including: + +- S3-compatibile object storage (recommended) +- local file storage + +S3-compatible object storage (Recommended) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For production environments, we recommend using S3-compatible object storage such as: + +- Amazon S3 +- MinIO +- Digital Ocean Spaces +- Other S3-compatible services + +When using S3 storage, you'll need: + +1. A bucket created specifically for Mattermost +2. Access credentials (Access Key and Secret Key) +3. Appropriate bucket policies configured +4. The following information for configuration: + + - Bucket name + - Region (if applicable) + - Access Key + - Secret Key + - Endpoint URL (for non-AWS S3 services) + +Local file storage +~~~~~~~~~~~~~~~~~~ + +For simple deployments, you can use local file storage. However, we don't recommend this for production environments or multi-node deployments. + +1. Create a directory for file storage: + + .. code-block:: sh + + sudo mkdir -p /opt/mattermost/data + +2. Set appropriate permissions: + + .. code-block:: sh + + sudo chown -R mattermost:mattermost /opt/mattermost/data + +(Optional) Use an image proxy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using an :doc:`image proxy ` means that all requests for images made by Mattermost clients will go through the proxy instead of contacting third-party servers directly. This helps protect user privacy by preventing third-party servers from tracking who views an image. This also prevents the use of tracking pixels (invisible images that do the same thing without the user even seeing an image). + +Certain proxy servers also provide a layer of caching which can make loading images faster and more reliable. This caching also helps preserve posts by protecting them from dead images. + +Network preparation +-------------------- + +Ensure the following ports are available: + +- Application ports: 80/443 (TCP) for HTTP/HTTPS +- Database port: 5432 (TCP) for PostgreSQL +- SMTP port: 10025 (TCP/UDP) for outbound email + +System requirements +-------------------- + +Ensure your system meets these minimum requirements: + +- Operating System: 64-bit Linux distribution +- Hardware: 1 vCPU/core with 2GB RAM (supports up to 1,000 users) +- Storage: Minimum 10GB available space +- Database: PostgreSQL v13+ +- Network: Reliable internet connection with sufficient bandwidth + +See the :doc:`software and hardware requirements ` documentation for additional requirements. + +Next steps +----------- + +Once you've completed these preparation steps, you can proceed with installing the Mattermost server. Choose your preferred installation method: + +- :doc:`Deploy with Kubernetes ` +- :doc:`Deploy with Containers ` +- :doc:`Deploy on Linux ` \ No newline at end of file diff --git a/source/install/prepare-mattermost-mysql-database.rst b/source/deploy/server/prepare-mattermost-mysql-database.rst similarity index 97% rename from source/install/prepare-mattermost-mysql-database.rst rename to source/deploy/server/prepare-mattermost-mysql-database.rst index 8dc305e208c..eaac5dd5921 100644 --- a/source/install/prepare-mattermost-mysql-database.rst +++ b/source/deploy/server/prepare-mattermost-mysql-database.rst @@ -3,12 +3,12 @@ Prepare your Mattermost MySQL database ====================================== -.. include:: ../_static/badges/allplans-selfhosted.rst +.. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: .. important:: - - PostgreSQL is our preferred database of choice. See the :ref:`database software ` documentation for details on database version support, and see the :doc:`Migrate from MySQL to PostgreSQL ` documentation for details on migrating from MySQL to PostgreSQL. + - PostgreSQL is our preferred database of choice. See the :ref:`database software ` documentation for details on database version support, and see the :doc:`Migrate from MySQL to PostgreSQL ` documentation for details on migrating from MySQL to PostgreSQL. - MySQL 8.0.22 contains an `issue with JSON column types `__ changing string values to integers which is preventing Mattermost from working properly. Users are advised to avoid this database version. Set up the Mattermost MySQL database @@ -251,8 +251,6 @@ Migrate from Bitnami to a self-hosted Mattermost deployment If you're planning a migration from Bitnami to a self-hosted Mattermost installation with a MySQL database, read these notes in our migration guide: :ref:`Migrating from Bitnami `. - - Downgrade Mattermost v6.0 to v5.38 ----------------------------------- diff --git a/source/deploy/server/server-architecture.rst b/source/deploy/server/server-architecture.rst new file mode 100644 index 00000000000..266a3bb1c02 --- /dev/null +++ b/source/deploy/server/server-architecture.rst @@ -0,0 +1,96 @@ +Server architecture reference +============================== + +The following diagrams detail suggested architecture configurations of :ref:`high availability Mattermost deployments ` at different scales. Hardware and infrastructure requirements will vary significantly based on usage and policies. See the :doc:`scaling for enterprise ` documentation for reference architecture guidance at scale, including hardware and infrastructure requirements. + +Reference architectures +------------------------ + +High availability in Mattermost consists of running redundant Mattermost application servers, redundant database servers, and redundant load balancers so that failure of any one of these components does not interrupt operation of the system. Upon failure of one component, the remaining application servers, database servers, and load balancers must be sized and configured to carry the full load of the system. If this requirement is not met, an outage of one component can result in an overload of the remaining components, causing a complete system outage. + +.. important + + Mattermost does not support high availability deployments spanning multiple datacenters. All nodes in a high availability cluster must reside within the same datacenter to ensure proper functionality and performance. + +You can apply most configuration changes and dot release security updates without interrupting service, provided that you update the system components in the correct sequence. Changes to configuration settings that require a server restart, and server version upgrades that involve a change to the database schema, require a short period of downtime. Downtime for a server restart is around 5 seconds. For a database schema update, downtime can be up to 30 seconds. + +Designed for scale +------------------ + +Mattermost is designed to be able to handle a large number of concurrent users, and the architecture can be scaled up or down as needed. The architecture is also designed to be flexible, allowing for the addition of new components or services as needed. The following diagrams show the recommended architecture for Mattermost deployments at 5,000, 10,000, 25,000, and 50,000 users. The diagrams are organized by user count and include a general diagram and AWS and Azure versions of each diagram. See the :doc:`scaling for enterprise ` documentation for more information on scaling Mattermost deployments. + +- Each generalized diagram represents a full High Availability deployment across all critical components. The proxy, database, file storage, and Elasticsearch layers can be replaced by cloud services. +- Each AWS diagram represents a full High Availability deployment on Amazon Web Services making full use of the available services. +- Each Azure diagram represents a full High Availability deployment on Microsoft Azure making full use of the available services. +- Push proxy can be replaced by the Mattermost :ref:`hosted push notification service `. + +.. tab:: 5000 users + + **General** + + .. image:: /images/MattermostDeployment5kUsers.png + :class: bg-white + + **AWS** + + .. image:: /images/MattermostDeployment5kaws.png + :class: bg-white + + **Azure** + + .. image:: /images/MattermostDeployment5kAzure.png + :class: bg-white + +.. tab:: 10,000 users + + **General** + + .. image:: /images/MattermostDeployment10kUsers.png + :class: bg-white + + **AWS** + + .. image:: /images/MattermostDeployment10kaws.png + :class: bg-white + + **Azure** + + .. image:: /images/MattermostDeployment10kAzure.png + :class: bg-white + +.. tab:: 25,000 users + + **General** + + .. image:: /images/MattermostDeployment25kUsers.png + :class: bg-white + + **AWS** + + .. image:: /images/MattermostDeployment25kaws.png + :class: bg-white + + **Azure** + + .. image:: /images/MattermostDeployment25kAzure.png + :class: bg-white + +.. tab:: 50,000 users + + **AWS** + + .. image:: /images/MattermostDeployment50kaws.png + :class: bg-white + + **Azure** + + .. image:: /images/MattermostDeployment50kAzure.png + :class: bg-white + +Database with Virtual IPs +-------------------------- + +We recommend the following configuration for Highly-Available databases through virtual IPs. + +.. image:: /images/DatabasewithVIPs.png + :class: bg-white \ No newline at end of file diff --git a/source/deploy/server/server-deployment-planning.rst b/source/deploy/server/server-deployment-planning.rst new file mode 100644 index 00000000000..fa055002488 --- /dev/null +++ b/source/deploy/server/server-deployment-planning.rst @@ -0,0 +1,117 @@ +Server deployment planning +========================== + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Preparations + Deploy with Kubernetes + Deploy with Containers + Deploy with Linux + Architecture reference + Scale for enterprise + +This section provides comprehensive guidance on deploying and managing your Mattermost server. Mattermost is a flexible, high-performance messaging platform built with Go and React, designed to provide secure team collaboration at scale. + +Core technology stack +---------------------- + +Mattermost's architecture is built on modern, reliable technologies: + +* **Backend**: Written in Go, providing high performance and concurrent processing +* **Frontend**: React-based web application and mobile apps +* **Database**: PostgreSQL for primary data storage +* **Search**: Elasticsearch (optional) for advanced search capabilities +* **File Storage**: Local filesystem or cloud storage (S3, MinIO) for media and attachments +* **Caching**: Built-in support for Redis for enhanced performance + +Deployment options +------------------- + +Mattermost offers several deployment options to suit your organization's needs: + +1. :doc:`Kubernetes (Recommended) ` + + Our recommended approach for production deployments offers: + + * Scalability and high availability + * Automated updates and rollbacks + * Infrastructure as code + * Built-in monitoring and logging + * Easy integration with existing DevOps workflows + +2. :doc:`Container-Based Deployment ` + + Docker containers are suitable for smaller deployments that offer: + + * Simplified installation and updates + * Consistent environments + * Easy dependency management + +3. :doc:`Traditional Linux Installation ` + + A direct installation on Linux servers offers: + + * Simple, straightforward setup + * Full control over the installation + * For situations where containers aren't preferred + +Prerequisites +-------------- + +Before deploying Mattermost, ensure you have reviewed the :doc:`software and hardware requirements `, and have: + +* A supported Linux distribution +* Database server (PostgreSQL 13+) +* Reverse proxy (NGINX recommended) +* SSL/TLS certificates for secure communication +* Adequate storage for files and database +* Network access and firewall configurations +* System requirements met based on expected user load + +Plan your deployment +---------------------- + +When planning your Mattermost deployment, consider the following when choosing the deployment method that best aligns with your organization's requirements, technical expertise, and infrastructure capabilities: + +* Expected user count and growth +* High availability requirements +* Backup and disaster recovery needs +* Integration with existing systems +* Security and compliance requirements +* Monitoring and maintenance strategy + +The following server, desktop, and mobile application sections provide detailed instructions for each deployment approach. + +Minimum database version policy +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To make planning easier and ensure your Mattermost deployment remains fast and secure, we are introducing a policy for updating the minimum supported version of PostgreSQL. The oldest supported PostgreSQL version Mattermost supports will match the oldest version supported by the PostgreSQL community. This ensures you benefit from the latest features and security updates. + +This policy change takes effect from Mattermost v10.6, where the minimum PostgreSQL version required will be PostgreSQL 13. This aligns with the PostgreSQL community's support policy, which provides 5 years of support for each major version. + +.. note:: + + Mattermost v10.6 is not an :ref:`Extended Support Release (ESR) `. Going forward, this database version support policy will only apply to ESR releases. + +When a PostgreSQL version reaches its end of life (EOL), Mattermost will require a newer version starting with the next scheduled ESR release. This means the following future PostgreSQL minimum version increases as follows: + ++-----------------------------------------------------------+------------------+--------------------------------+ +| **Mattermost Version** | **Release Date** | **Minimum PostgreSQL Version** | ++===========================================================+==================+================================+ +| :ref:`v9.11 ESR ` | 2024-8-15 | 11.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| :ref:`v10.5 ESR ` | 2025-2-15 | 11.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| :ref:`v10.6 ` | 2025-3-15 | 13.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| v10.11 ESR | 2025-8-15 | 13.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| v11.5 ESR ``*`` | 2026-2-15 | 14.x (EOL 2026-11-12) | ++-----------------------------------------------------------+------------------+--------------------------------+ + +``*`` Forcasted release version and date. + +Customers will have 9 months to plan, test, and upgrade their PostgreSQL version before the new requirement takes effect. This policy aims to provide clarity and transparency so you can align database upgrades with the Mattermost release schedule. Contact a `Mattermost Expert `_. to discuss your options. diff --git a/source/install/setting-up-socket-based-mattermost-database.rst b/source/deploy/server/setting-up-socket-based-mattermost-database.rst similarity index 54% rename from source/install/setting-up-socket-based-mattermost-database.rst rename to source/deploy/server/setting-up-socket-based-mattermost-database.rst index 90ce1263609..729ffe4df79 100644 --- a/source/install/setting-up-socket-based-mattermost-database.rst +++ b/source/deploy/server/setting-up-socket-based-mattermost-database.rst @@ -1,29 +1,23 @@ -Using sockets for database -========================== +(Optional) Using sockets for database +====================================== -.. include:: ../_static/badges/allplans-selfhosted.rst +.. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -Mattermost requires a database back-end, and PostgreSQL is our database of choice. In this document let's understand how -you can use sockets for setting up the database. - -- Install and configure PostgreSQL. -- Choose between TCP or UNIX Socket, and jump to the corresponding section. +You can use sockets for setting up the database. Choose between TCP or UNIX Socket. With TCP socket --------------- -- Create the new user while connecting to the server as ``postgres`` user - (you will be prompted for a password for the new user): +1. Create the new user while connecting to the server as ``postgres`` user (you will be prompted for a password for the new user): ``sudo -u postgres createuser -P mmuser`` -- Create the Mattermost database, owned by ``mmuser`` user: +2. Create the Mattermost database, owned by ``mmuser`` user: ``sudo -u postgres createdb -O mmuser mattermostdb`` -- In the connections and authentications section, set the ``listen_address`` list - line per your needs: +3. In the connections and authentications section, set the ``listen_address`` list line per your needs: .. code-block:: sh @@ -32,7 +26,7 @@ With TCP socket You can use '*' to listen on all available addresses. -- Then add a line like the following to the authentication config: +4. Then add a line like the following to the authentication config: .. code-block:: sh @@ -41,7 +35,7 @@ With TCP socket # IPv4 local connections: host all all ip_address/32 md5 -- Run the setup using: +5. Run the setup using: .. code-block:: sh @@ -50,27 +44,27 @@ With TCP socket With Unix socket ---------------- -- Create the new user while connecting to the server as ``postgres`` user: +1. Create the new user while connecting to the server as ``postgres`` user: .. code-block:: sh sudo -u postgres createuser mattermost -- Create the Mattermost database, owned by ``mattermost`` user: +2. Create the Mattermost database, owned by ``mattermost`` user: .. code-block:: sh sudo -u postgres createdb -O mattermost mattermostdb -- Setup the Unix socket by adding the following line to ``/var/lib/postgres/data/pg_hba.conf``: +3. Set up the Unix socket by adding the following line to ``/var/lib/postgres/data/pg_hba.conf``: .. code-block:: sh local mattermostdb mattermost peer -- Restart postgresql.service. +4. Restart postgresql.service. -- Run the setup using: +5. Run the setup using: .. code-block:: sh @@ -79,12 +73,11 @@ With Unix socket Configuring Mattermost ---------------------- -- Mattermost is configured in ``/etc/webapps/mattermost/config.json``. - Strings need to be quoted. +Mattermost is configured in ``/etc/webapps/mattermost/config.json``. Strings need to be quoted. - Set ``DriverName`` to ``postgres``. - Set ``DataSource``: +- Set ``DataSource``: - TCP socket: ``postgres://mmuser:mmuser_password@127.0.0.1:5432/mattermostdb?sslmode=disable&connect_timeout=10`` - Unix socket: ``postgres:///mattermostdb?host=/run/postgresql``, where ``mattermostdb`` is the name of the database and ``/run/postgresql`` is the directory containing the Unix socket. \ No newline at end of file diff --git a/source/install/setup-nginx-proxy.rst b/source/deploy/server/setup-nginx-proxy.rst similarity index 87% rename from source/install/setup-nginx-proxy.rst rename to source/deploy/server/setup-nginx-proxy.rst index 3b4b910a511..3a80e84819e 100644 --- a/source/install/setup-nginx-proxy.rst +++ b/source/deploy/server/setup-nginx-proxy.rst @@ -1,15 +1,23 @@ -Set up an NGINX proxy -===================== +(Recommended) Set up an NGINX proxy +=================================== -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +A proxy server is a server (a computer system or an application) that acts as an intermediary for requests from clients seeking resources from other servers. Mattermost recommends using a proxy in front of Mattermost to increase security, performance and the ability to monitor and shape traffic connecting to Mattermost: + +- **Security:** A proxy server can manage Secure Socket Layer (TLS/SSL) encryption and set policy on how network traffic will be routed to the Mattermost server. +- **Performance:** In a High Availability configuration, the proxy server balances the network load across multiple Mattermost servers for optimized performance. A hardware proxy with dedicated devices for processing SSL encryption and decryption can also be used to increase performance. +- **Monitoring**: A proxy server can monitor connection traffic and record traffic in standard audit logs that common monitoring tools like Kibana and Splunk can consume and report on. Some of the events that can be captured include file uploads and downloads, which are not tracked by the Mattermost server logging process. + +Mattermost supports the `NGINX proxy `_ + +.. image:: ../../images/architecture_with_proxy.png + :alt: Mattermost architecture with NGINX proxy Install NGINX server -------------------- NGINX is a popular web server and is responsible for hosting some of the largest and highest-traffic sites on the internet. It's more resource-friendly than Apache in most cases, and can be used as a web server or reverse proxy. -In a production setting, we recommend using a proxy server for greater security and performance of Mattermost. +In a production setting, we recommend using a proxy server for greater security and performance of Mattermost: - SSL termination - HTTP to HTTPS redirect @@ -25,7 +33,6 @@ Install NGINX on Ubuntu Server Because NGINX is available in Ubuntu's default repositories, it's possible to install it from these repositories using the ``apt`` packaging system. First, update your local ``apt`` package index for access to the most recent package listings. Then, install ``nginx``: - .. code-block:: sh sudo apt update @@ -65,11 +72,11 @@ Now that you have your web server up and running, let's review some basic manage To stop your web server, use: ``sudo systemctl stop nginx`` To start the web server when it's stopped, use: ``sudo systemctl start nginx`` - + To stop and then start the service again, use: ``sudo systemctl restart nginx`` - + If you're simply making configuration changes, NGINX can often reload without dropping connections. To do this, use: ``sudo systemctl reload nginx`` - + By default, NGINX is configured to start automatically when the server boots. If this isn't what you want, you can disable this behavior using: ``sudo systemctl disable nginx`` To re-enable the service to start up at boot, use: ``sudo systemctl enable nginx`` @@ -95,12 +102,12 @@ NGINX is configured using a file in the ``/etc/nginx/sites-available`` directory SSL and HTTP/2 are enabled in the provided configuration example. - .. note:: +.. note:: - - If you're going to use Let's Encrypt to manage your SSL certificate, stop at step 3 and see the :ref:`NGINX HTTP/2 and SSL product documentation ` for details. - - You'll need valid SSL certificates in order for NGINX to pin the certificates properly. Additionally, your browser must have permissions to accept the certificate as a valid CA-signed certificate. - - Note that the IP address included in the examples in this documentation may not match your network configuration. - - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. + - If you're going to use Let's Encrypt to manage your SSL certificate, stop at step 3 and see the :ref:`NGINX HTTP/2 and SSL product documentation ` for details. + - You'll need valid SSL certificates in order for NGINX to pin the certificates properly. Additionally, your browser must have permissions to accept the certificate as a valid CA-signed certificate. + - Note that the IP address included in the examples in this documentation may not match your network configuration. + - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. .. code-block:: text @@ -196,9 +203,7 @@ SSL and HTTP/2 are enabled in the provided configuration example. 6. Restart NGINX by running ``sudo systemctl restart nginx``. -7. Verify that you can see Mattermost through the proxy by running ``curl https://localhost``. - - If everything is working, you will see the HTML for the Mattermost signup page. +7. Verify that you can see Mattermost through the proxy by running ``curl https://localhost``. If everything is working, you will see the HTML for the Mattermost signup page. 8. Restrict access to port 8065. @@ -219,7 +224,7 @@ You can use any certificate that you want, but these instructions show you how t .. note:: - If Let’s Encrypt is enabled, forward port 80 through a firewall, with :ref:`Forward80To443 ` ``config.json`` setting set to ``true`` to complete the Let’s Encrypt certification. See the `Let's Encrypt/Certbot documentation `_ for additional assistance. + If Let’s Encrypt is enabled, forward port 80 through a firewall, with :ref:`Forward80To443 ` ``config.json`` setting set to ``true`` to complete the Let’s Encrypt certification. See the `Let's Encrypt/Certbot documentation `_ for additional assistance. 1. Log in to the server that hosts NGINX and open a terminal window. @@ -227,10 +232,10 @@ You can use any certificate that you want, but these instructions show you how t .. note:: - - On Ubuntu this file is located at ``/etc/nginx/sites-available/``. If you don't have this file, run ``sudo touch /etc/nginx/sites-available/mattermost``. - - On CentOS/RHEL this file is located at ``/etc/nginx/conf.d/``. If you don't have this file, run ``sudo touch /etc/nginx/conf.d/mattermost``. - - The IP address included in the examples in this documentation may not match your network configuration. - - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. + - On Ubuntu this file is located at ``/etc/nginx/sites-available/``. If you don't have this file, run ``sudo touch /etc/nginx/sites-available/mattermost``. + - On CentOS/RHEL this file is located at ``/etc/nginx/conf.d/``. If you don't have this file, run ``sudo touch /etc/nginx/conf.d/mattermost``. + - The IP address included in the examples in this documentation may not match your network configuration. + - If you're running NGINX on the same machine as Mattermost, and NGINX resolves ``localhost`` to more than one IP address (IPv4 or IPv6), we recommend using ``127.0.0.1`` instead of ``localhost``. .. code-block:: text @@ -534,4 +539,4 @@ If you're running Let's Encrypt within Mattermost you'll see this error: {"level":"error","ts":1609092001.752515,"caller":"http/server.go:3088","msg":"http: TLS handshake error from ip:port: 429 urn:ietf:params:acme:error:rateLimited: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/","source":"httpserver"} -This means that you've attempted to generate a cert too many times. You can find more information `here `_. +This means that you've attempted to generate a cert too many times. You can find more information `here `_. \ No newline at end of file diff --git a/source/deploy/server/setup-tls.rst b/source/deploy/server/setup-tls.rst new file mode 100644 index 00000000000..927d97c3df4 --- /dev/null +++ b/source/deploy/server/setup-tls.rst @@ -0,0 +1,70 @@ +(Optional) Set up TLS +====================== + +You have two options if you want users to connect with HTTPS: + +:doc:`Install a proxy such as NGINX ` and then `set up TLS on the proxy <#Use-TLS-on-NGINX-as-a-proxy>`__. This is our recommended option if you have a large number of users (more than 200), or if you want to use a reverse proxy for other reasons, such as load balancing or caching. A proxy server delivers better performance and provides standard HTTP request logs. + +Alternatively, if you have fewer than 200 users, you can set up TLS on Mattermost server. This is the easiest option when you don't need to use a reverse proxy. + + - You can use `Let's Encrypt `__ to automatically install and set up the certificate. + - You can also specify your own certificate. + - You can use a self-signed certificate, but this is not recommended for production environments. + +Configure TLS on the Mattermost server +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. In **System Console > Environment > Web Server**: + + a. Change the **Listen Address** setting to ``:443``. + b. Change the **Connection Security** setting to ``TLS``. + c. Change the **Forward port 80 to 443** setting to ``true``. + +2. Activate the ``CAP_NET_BIND_SERVICE`` capability to allow Mattermost to bind to low ports: + + .. code-block:: sh + + sudo setcap cap_net_bind_service=+ep /opt/mattermost/bin/mattermost + +3. Install the security certificate. Use Let's Encrypt to automatically install and setup the certificate, or specify your own certificate. + +Use a Let's Encrypt certificate +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The certificate is retrieved the first time that a client tries to connect to the Mattermost server. Certificates are retrieved for any hostname a client tries to reach the server at. + +1. Change the **Use Let's Encrypt** setting to ``true``. +2. Restart the Mattermost server for these changes to take effect. + +.. note:: + + - If Let's Encrypt is enabled, forward port 80 through a firewall, with :ref:`Forward80To443 ` ``config.json`` setting set to ``true`` to complete the Let's Encrypt certification. + - Your Mattermost server must be accessible from the Let's Encrypt CA in order to verify your domain name and issue the certificate. Be sure to open your firewall and configure any reverse proxies to forward traffic to ports 80 and 443. More information can be found `at Let's Encrypt `_. + +Use your own certificate +~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Change the **Use Let's Encrypt** setting to ``false``. +2. Change the **TLS Certificate File** setting to the location of the certificate file. +3. Change the **TLS Key File** setting to the location of the private key file. +4. Restart the Mattermost server for these changes to take effect. + +.. note:: + + Password-protected certificates aren't supported. + +Use TLS on NGINX (as a proxy) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + Do not set up TLS on Mattermost before doing so for NGINX. It breaks the connection as the TLS prevents it from successfully communicating with the Mattermost server. + +- NGINX will act as a forward proxy to encrypt the traffic between the client and Mattermost server. After installing the SSL certificate, the incoming traffic will be handled via NGINX on port 443 exposed to the internet, proxy to the Mattermost server running on port 80. +- (Optional) Upstream encryption between NGINX to Mattermost server is allowed. +- Follow `NGINX's guide on setting up SSL Termination for TCP Upstream Servers `__. + +More helpful resources: + +- `NGINX's SSL blog `_ +- `NGINX's SSL guide `_ \ No newline at end of file diff --git a/source/install/trouble-postgres.rst b/source/deploy/server/trouble-postgres.rst similarity index 85% rename from source/install/trouble-postgres.rst rename to source/deploy/server/trouble-postgres.rst index a4ebf3319a4..80787237ea3 100644 --- a/source/install/trouble-postgres.rst +++ b/source/deploy/server/trouble-postgres.rst @@ -1,7 +1,7 @@ PostgreSQL installation troubleshooting ======================================= -From Mattermost v8.0, :ref:`PostgreSQL ` is our database of choice for Mattermost to enhance the platform’s performance and capabilities. +From Mattermost v8.0, :ref:`PostgreSQL ` is our database of choice for Mattermost to enhance the platform’s performance and capabilities. PostgreSQL v15 introduces changes that may affect compatibility with previous releases. If you're deploying a fresh installation of PostgreSQL v15, run this command: ``GRANT CREATE ON SCHEMA public TO PUBLIC`` to ensure that you can use Mattermost. @@ -25,3 +25,8 @@ CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_posts_message_txt_spanish ON posts U DROP INDEX CONCURRENTLY IF EXISTS idx_posts_message_txt; ALTER INDEX idx_posts_message_txt_spanish RENAME TO idx_posts_message_txt; ``` + +Change the PostgreSQL username and password +-------------------------------------------- + +We recommend changing the PostgreSQL username and password in the ``.env`` file. \ No newline at end of file diff --git a/source/install/trouble_mysql.rst b/source/deploy/server/trouble_mysql.rst similarity index 96% rename from source/install/trouble_mysql.rst rename to source/deploy/server/trouble_mysql.rst index 602c2f19133..83a51878c06 100644 --- a/source/install/trouble_mysql.rst +++ b/source/deploy/server/trouble_mysql.rst @@ -1,15 +1,12 @@ MySQL installation troubleshooting ================================== -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - Before you can run the Mattermost server, you must first install and configure a database. You can start Mattermost by navigating to the ``/opt/mattermost`` directory and entering the command ``sudo -u mattermost bin/mattermost``. If the Mattermost server can't connect to the database, it will fail to start. This section deals with MySQL database issues that you may encounter when you start up Mattermost for the first time. .. note:: - - Additional database tuning guidance is available for specific Mattermost releases. See the :doc:`important upgrade notes ` documentation for more details. - - See the :ref:`database configuration settings ` documentation for details on configuration options specific to MySQL databases. + - Additional database tuning guidance is available for specific Mattermost releases. See the :doc:`important upgrade notes ` documentation for more details. + - See the :ref:`database configuration settings ` documentation for details on configuration options specific to MySQL databases. How you install MySQL varies depending upon which Linux distribution you use. However, once MySQL is installed, the configuration instructions are the same. For all distributions you must create a ``mattermost`` database and a ``mattermost`` database user. Failure to create these database diff --git a/source/install/troubleshooting.rst b/source/deploy/server/troubleshooting.rst similarity index 82% rename from source/install/troubleshooting.rst rename to source/deploy/server/troubleshooting.rst index 21cd3320e00..3a1ea632c2a 100644 --- a/source/install/troubleshooting.rst +++ b/source/deploy/server/troubleshooting.rst @@ -1,78 +1,31 @@ -Troubleshooting Mattermost issues -================================= +General deployment troubleshooting +=================================== -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: +This document summarizes common deployment troubleshooting issues and resolutions. Some of these suggestions can be done directly, and others may need consultation from your network administrator. -This document summarizes common troubleshooting issues and techniques. +Start Mattermost at system boot +------------------------------- -Depending on the type of error or problem you're experiencing, refer to the sections below for troubleshooting guidance. If you're a new user, it might help to go over the installation steps again to confirm the process. - -If you have a :doc:`paid subscription to a Mattermost offering `, such as :ref:`Mattermost Professional ` or :ref:`Mattermost Enterprise `, you're entitled to open support tickets via our `online support portal `_. - -Additionally, peer-to-peer support is available for all Mattermost users in our `troubleshooting forum `_ and on our `community server `_. - -Important notes ---------------- - -- Do not manipulate the Mattermost database directly. Mattermost is designed to stop working if data integrity is compromised. -- Any manipulation of the database must be done using the built in command line tools. -- Start simple with the step-by-step install guides for your operating system. - -Deployment troubleshooting --------------------------- - -Docker deployments -~~~~~~~~~~~~~~~~~~ - -If you're deploying the Mattermost server using Docker on an M1 Mac and encountering permission issues in the Docker container, re-create the required directories and set their permissions, then skip the following command because it causes the deploy to stop working. +To have the Mattermost Server start at system boot, the systemd unit file needs to be enabled. Run the following command: .. code-block:: sh - sudo chown -R 2000:2000 ./volumes/app/mattermost + sudo systemctl enable mattermost.service -If you're experiencing issues deploying on Docker generally, ensure the docker daemon is enabled and running: +If your database is on the same system as your Mattermost Server, we recommend editing the default ``/lib/systemd/system/mattermost.service`` systemd unit file to add ``After=postgresql.service`` and ``BindsTo=postgresql.service`` to the ``[Unit]`` section. -.. code-block:: sh - - sudo systemctl enable --now docker +Run Mattermost without a proxy +------------------------------ -To remove all data and settings for your Mattermost deployment: +Mattermost binds to 443 instead of 8065. The Mattermost binary requires the correct permissions to do that binding. You must activate the ``CAP_NET_BIND_SERVICE`` capability to allow the new Mattermost binary to bind to ports lower than 1024 by running the following command: .. code-block:: sh - sudo rm -rf ./volumes - -Postgres issues -~~~~~~~~~~~~~~~ - -You can change the Postgres username and/or password (recommended) in the ``.env`` file. - -TLS and NGINX issues -~~~~~~~~~~~~~~~~~~~~~ + sudo setcap cap_net_bind_service=+ep ./mattermost/bin/mattermost -For an in-depth guide to configuring the TLS certificate and key for NGINX, please refer to `this document in the repository `__. - -Install a different version of Mattermost -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. Shut down your deployment. - -2. Run ``git pull`` to fetch any recent changes to the repository, paying attention to any potential ``env.example`` changes. - -3. Adjust the ``MATTERMOST_IMAGE_TAG`` in the ``.env`` file to point your desired `enterprise `__ or `team `__ image version. - -4. Redeploy Mattermost. - -Upgrading from ``mattermost-docker`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For an in-depth guide to upgrading from the deprecated `mattermost-docker repository `__, please refer to `this document `__. For additional help, please refer to `this issue `__. - -General troubleshooting ------------------------ +.. note:: -Some of these suggestions can be done directly, and others may need consultation from your network administrator. + We highly recommend using a proxy in front of Mattermost server for up to 200 concurrent users. If you have fewer than 200 concurrent users, you can :doc:`set up TLS `. If you're exceeding 200 concurrent users, you'll need :doc:`a proxy `, such as NGINX, in front of Mattermost to manage the traffic. Review Mattermost logs ---------------------- @@ -80,7 +33,7 @@ Review Mattermost logs You can access logs for Mattermost and use them for troubleshooting. These steps assume that you have appropriate :doc:`system admin permissions ` to do so. Mattermost Server logs ----------------------- +~~~~~~~~~~~~~~~~~~~~~~~ - Ensure that log files are being created: Navigate to **System Console > Environment > Logging**, confirm that **Output logs to file** is set to **true**. - You can obtain the path for the log files in **System Console > Environment > Logging > File Log Directory**. @@ -95,7 +48,7 @@ If filesystem access is not possible, navigate to **System Console > Reporting > You can find more on logging settings :ref:`here `. Mattermost Desktop App logs ---------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Access desktop app logs by going to **Help > Show logs** from the menu bar. @@ -106,17 +59,17 @@ Alternatively, you can access desktop app log files in the following directory: - **MacOS:** ``~/Library/Logs/Mattermost`` (DMG installation) OR ``~Library/Containers/Mattermost.Desktop/Data/Library/Logs/Mattermost`` (Appstore installation only) Mattermost web logs --------------------- +~~~~~~~~~~~~~~~~~~~~ The browser-based app does not produce additional log files. If the app has to be debugged, use the development tools integrated in your browser for action history. Mattermost Push Notification Service logs ------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Logging for the Mattermost Push Notification Service is handled via system log with logger and is appended to ``/var/log/syslog``. Review Mattermost environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- Put together a timeline to eliminate events prior to the error/problem occurring. For example, if you recently reconfigured your firewall and are now having connection issues it might be worth reviewing the settings or rolling back to see whether that resolves the problem. diff --git a/source/install/software-hardware-requirements.rst b/source/deploy/software-hardware-requirements.rst similarity index 70% rename from source/install/software-hardware-requirements.rst rename to source/deploy/software-hardware-requirements.rst index 142d456d557..1d7af7a35bd 100644 --- a/source/install/software-hardware-requirements.rst +++ b/source/deploy/software-hardware-requirements.rst @@ -9,11 +9,7 @@ This guide outlines minimum software and hardware requirements for deploying Mat Deployment overview ------------------- -Please see the :doc:`Mattermost Deployment Overview ` documentation for a summary of software systems whose requirements are described in this document. - -.. image:: ../images/network-diagram.svg - :alt: Mattermost network diagram shows how the components can be deployed. Includes optional configurations for scaling for larger enterprise organizations. - :class: bg-white +Please see the :doc:`Application architecture ` documentation for a summary of software systems and components whose requirements are described in this document. Software requirements --------------------- @@ -101,13 +97,44 @@ Database software Amazon Aurora equivalents of both PostgreSQL and MySQL are also supported. -See the :ref:`minimum supported version policy ` documentation for minimum PostgreSQL version support details, and see the :doc:`Migrate from MySQL to PostgreSQL ` product documentation to learn about migrating from MySQL to PostgreSQL. - .. important:: - MariaDB v10+ no longer functions as a MySQL drop-in replacement, and it's not supported for Mattermost due to the requirement of MySQL 5.7.12. Prior versions of MariaDB were not officially supported but may have functioned in older Mattermost releases. If you are running MariaDB now, migrating from MariaDB to the MySQL equivalent is recommended. + - MariaDB v10+ no longer functions as a MySQL drop-in replacement, and it's not supported for Mattermost due to the requirement of MySQL 5.7.12. Prior versions of MariaDB were not officially supported but may have functioned in older Mattermost releases. If you are running MariaDB now, migrating from MariaDB to the MySQL equivalent is recommended. + - Deployments requiring searching in Chinese, Japanese, and Korean languages require MySQL 5.7.6+ and the configuration of `ngram Full-Text parser `__. For searching two characters, you will also need to set ``ft_min_word_len`` and ``innodb_ft_min_token_size`` to ``2`` and restart MySQL. See `CJK discussion `__ for details. + +Minimum PostgreSQL database support policy +:::::::::::::::::::::::::::::::::::::::::: + +To make planning easier and ensure your Mattermost deployment remains fast and secure, we are introducing a policy for updating the minimum supported version of PostgreSQL. The oldest supported PostgreSQL version Mattermost supports will match the oldest version supported by the PostgreSQL community. This ensures you benefit from the latest features and security updates. + +This policy change takes effect from Mattermost v10.6, where the minimum PostgreSQL version required will be PostgreSQL 13. This aligns with the PostgreSQL community's support policy, which provides 5 years of support for each major version. + +.. note:: + + Mattermost v10.6 is not an :ref:`Extended Support Release (ESR) `. Going forward, this database version support policy will only apply to ESR releases. + +When a PostgreSQL version reaches its end of life (EOL), Mattermost will require a newer version starting with the next scheduled ESR release. This means the following future PostgreSQL minimum version increases as follows: + ++-----------------------------------------------------------+------------------+--------------------------------+ +| **Mattermost Version** | **Release Date** | **Minimum PostgreSQL Version** | ++===========================================================+==================+================================+ +| :ref:`v9.11 ESR ` | 2024-8-15 | 11.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| :ref:`v10.5 ESR ` | 2025-2-15 | 11.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| :ref:`v10.6 ` | 2025-3-15 | 13.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| v10.11 ESR | 2025-8-15 | 13.x | ++-----------------------------------------------------------+------------------+--------------------------------+ +| v11.5 ESR ``*`` | 2026-2-15 | 14.x (EOL 2026-11-12) | ++-----------------------------------------------------------+------------------+--------------------------------+ + +``*`` Forcasted release version and date. + +Customers will have 9 months to plan, test, and upgrade their PostgreSQL version before the new requirement takes effect. This policy aims to provide clarity and transparency so you can align database upgrades with the Mattermost release schedule. Contact a `Mattermost Expert `_. to discuss your options. -Deployments requiring searching in Chinese, Japanese, and Korean languages require MySQL 5.7.6+ and the configuration of `ngram Full-Text parser `__. For searching two characters, you will also need to set ``ft_min_word_len`` and ``innodb_ft_min_token_size`` to ``2`` and restart MySQL. See `CJK discussion `__ for details. +Database Search limitations +::::::::::::::::::::::::::::: Search limitations on PostgreSQL: diff --git a/source/deploy/transport-encryption.rst b/source/deploy/transport-encryption.rst new file mode 100644 index 00000000000..93e7eea9b42 --- /dev/null +++ b/source/deploy/transport-encryption.rst @@ -0,0 +1,474 @@ +Configuring transport encryption +================================= + +.. include:: ../_static/badges/ent-selfhosted.rst + :start-after: :nosearch: + +The components of the Mattermost setup are shown in the following diagram, including the transport encryption used. Aside from the encryption between the nodes of the Mattermost cluster, all transports rely on TLS encryption. + +.. note:: + + The transport between the Application servers is not used by default and requires additional setup steps. Enhancing the core product to include automatic encryption between cluster nodes is in progress and planned for a later release. + +.. image:: ../images/transport-encryption.png + :alt: Components of the Mattermost setup where all transports rely on TLS encryption. + +Configuring proxy to Mattermost transport encryption +----------------------------------------------------- + +.. include:: ../_static/badges/ent-selfhosted.rst + :start-after: :nosearch: + +Mattermost is able to encrypt the traffic between the proxy and the application server using TLS. + +Prerequisites +~~~~~~~~~~~~~~ + +- Operational Mattermost server or cluster. +- Authentication credentials for Mattermost user on application server. + +Example environment +~~~~~~~~~~~~~~~~~~~ + +In this scenario there is one Mattermost application server and one NGINX server, both running Ubuntu 20.04, with the following IPs: + +- **transport-encryption-mattermost1:** 10.10.250.146 +- **transport-encryption-nginx:** 10.10.250.107 + +Configuring NGINX +~~~~~~~~~~~~~~~~~~ + +On the NGINX server, connect to both servers with a sudo or root user. Open the Mattermost proxy configuration and search for the following line twice: + +.. code-block:: text + + proxy_pass http://backend; + +Change the protocol from ``http`` to ``https``: + +.. code-block:: text + + proxy_pass https://backend; + +Afterwards do not reload the NGINX server yet to minimize the downtime of the service. + +Configuring Mattermost +~~~~~~~~~~~~~~~~~~~~~~~ + +On the Mattermost server, change to the config directory of Mattermost and generate a self-signed certificate that will be used to encrypt the traffic between the proxy server and the application server. + +**Note:** Alternatively you can sign a certificate from your company's CA. + +.. code-block:: sh + + cd /opt/mattermost/config + openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes + chown root:mattermost *.pem + chmod 640 *.pem + + +Once complete, open the file ``config.json`` and modify the values ``ConnectionSecurity``, ``TLSCertFile`` and ``TLSKeyFile`` in the ``ServiceSettings`` section. + +**Before** + +.. code-block:: json + + { + "ServiceSettings": { + "SiteURL": "https://transport-encryption.dev.example.com", + "WebsocketURL": "", + "LicenseFileLocation": "", + "ListenAddress": ":8065", + "ConnectionSecurity": "", + "TLSCertFile": "", + "TLSKeyFile": "", + "...":"..." + }, + "...":"..." + } + + +**After** + +.. code-block:: json + + { + "ServiceSettings": { + "SiteURL": "https://transport-encryption.dev.example.com", + "WebsocketURL": "", + "LicenseFileLocation": "", + "ListenAddress": ":8065", + "ConnectionSecurity": "TLS", + "TLSCertFile": "/opt/mattermost/config/cert.pem", + "TLSKeyFile": "/opt/mattermost/config/key.pem", + "...":"..." + }, + "...":"..." + } + + +Restart the Mattermost server and ensure it's up and running: + +.. code-block:: sh + + sudo systemctl restart mattermost + systemctl status mattermost + +.. code-block:: text + + ● mattermost.service - Mattermost + Loaded: loaded (/lib/systemd/system/mattermost.service; static; vendor preset: enabled) + Active: active (running) since Mon 2019-10-28 16:45:29 UTC; 1h 15min ago + [...] + +Finally, on the **NGINX server**, reload the configuration to ensure that requests are sent on HTTPS: + +.. code-block:: sh + + sudo systemctl reload nginx + +Configuring database transport encryption +------------------------------------------ + +.. include:: ../_static/badges/ent-selfhosted.rst + :start-after: :nosearch: + +Mattermost is able to encrypt the traffic between the database and the application using TLS. This guide describes the setup steps for a single, separate MySQL server. + +Prerequisites +~~~~~~~~~~~~~~ + +- Operational Mattermost server or cluster. +- Operational MySQL server. +- Confirmed connectivity between Mattermost and MySQL server. +- Authentication credentials for Mattermost user on MySQL server. + +Example environment +~~~~~~~~~~~~~~~~~~~ + +In this scenario there is one Mattermost application server and one MySQL server, both running Ubuntu 20.04, with the following IPs: + +- **transport-encryption-mattermost1:** 10.10.250.146 +- **transport-encryption-mysql1:** 10.10.250.148 + +Configuring MySQL +~~~~~~~~~~~~~~~~~~ + +As a first step, connect to both servers with a sudo or root user. + +Execute the following command to prepare the server for SSL connections: + +.. code-block:: sh + + sudo mysql_ssl_rsa_setup --uid=mysql + +This generates self-signed certificates in ``/var/lib/mysql/`` that the MySQL server uses to encrypt the connection. If you would like to use certificates from your company CA, please follow the MySQL documentation for configuration steps. + +**Note:** Optionally, it can be enforced that all connections must be made via a local socket connection or TLS. To do this, open ``/etc/mysql/mysql.conf.d/mysqld.cnf`` and append the following line to the file: + +.. code-block:: text + + require_secure_transport = ON + +Any connection to the MySQL server must now be made with secure transport enabled. + +Last but not least, restart the server and confirm it is up and running: + + .. code-block:: sh + + systemctl restart mysql + systemctl status mysql + +.. code-block:: text + + ● mysql.service - MySQL Community Server + Loaded: loaded (/lib/systemd/system/mysql.service; enabled; vendor preset: enabled) + Active: active (running) since Fri 2019-10-18 16:41:25 UTC; 2s ago + Process: 8380 ExecStart=/usr/sbin/mysqld --daemonize --pid-file=/run/mysqld/mysqld.pid (code=exited, status=0/SUCCESS) + Process: 8360 ExecStartPre=/usr/share/mysql/mysql-systemd-start pre (code=exited, status=0/SUCCESS) + Main PID: 8382 (mysqld) + Tasks: 27 (limit: 2361) + CGroup: /system.slice/mysql.service + └─8382 /usr/sbin/mysqld --daemonize --pid-file=/run/mysqld/mysqld.pid + + Oct 18 16:41:25 transport-encryption-mysql1 systemd[1]: Stopped MySQL Community Server. + Oct 18 16:41:25 transport-encryption-mysql1 systemd[1]: Starting MySQL Community Server... + Oct 18 16:41:25 transport-encryption-mysql1 systemd[1]: Started MySQL Community Server. + +Configuring Mattermost +~~~~~~~~~~~~~~~~~~~~~~~ + +On the Mattermost server, open the file ``config.json`` and look for the ``DataSource`` value in the ``SqlSettings`` section. It should look similar to this: + +.. code-block:: text + + "DataSource": "mmuser:sad09zusaopdhsad123@tcp(10.10.250.148:3306)/mattermost?charset=utf8mb4,utf8\u0026writeTimeout=30s", + +At the end of the line, we can configure that TLS must be turned on with the ``tls`` flag which supports the following values: + +- true (Require TLS + a trusted certificate) +- false +- skip-verify (Require TLS + accept self-signed) +- preferred (Try TLS, fallback to unencrypted) + +In our case we need to use ``skip-verify`` since we use a self-signed certificate. The configuration setting will now look like this: + +.. code-block:: text + + "DataSource": "mmuser:sad09zusaopdhsad123@tcp(10.10.250.148:3306)/mattermost?charset=utf8mb4,utf8\u0026writeTimeout=30s&tls=skip-verify", + +If you're running Mattermost in a cluster, be sure to update the value on each node of the cluster. If you are using configuration in the database, be sure to update the ``systemd`` unit file and enable TLS for the configuration store. + +Once complete, restart the Mattermost server and ensure the system is operational: + +.. code-block:: sh + + sudo systemctl restart mattermost + systemctl status mattermost + +.. code-block:: text + + ● mattermost.service - Mattermost + Loaded: loaded (/lib/systemd/system/mattermost.service; static; vendor preset: enabled) + Active: active (running) since Fri 2019-10-18 16:47:08 UTC; 3s ago + Process: 3424 ExecStartPre=/opt/mattermost/bin/pre_start.sh (code=exited, status=0/SUCCESS) + Main PID: 3443 (mattermost) + Tasks: 20 (limit: 2361) + CGroup: /system.slice/mattermost.service + ├─3443 /opt/mattermost/bin/mattermost --config=mysql://mmuser:sad09zusaopdhsad123@tcp(10.10.250.148:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s&tls=skip-verify + └─3459 plugins/com.mattermost.nps/server/dist/plugin-linux-amd64 + + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8637397,"caller":"scheduler/worker.go:36","msg":"Worker started","worker":"Plugins"} + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8639545,"caller":"jobs/jobs_watcher.go:38","msg":"Watcher Started"} + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"info","ts":1571417228.8641603,"caller":"jobs/schedulers.go:72","msg":"Starting schedulers."} + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8645394,"caller":"app/web_hub.go:436","msg":"Hub for index 0 is starting with goroutine 3923"} + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8648505,"caller":"app/web_hub.go:436","msg":"Hub for index 1 is starting with goroutine 3924"} + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8656101,"caller":"web/static.go:31","msg":"Using client directory at /opt/mattermost/client"} + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"info","ts":1571417228.8681324,"caller":"commands/server.go:105","msg":"Sending systemd READY notification."} + Oct 18 16:47:08 transport-encryption-mattermost1 systemd[1]: Started Mattermost. + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.9003174,"caller":"jobs/schedulers.go:166","msg":"Next run time for scheduler","scheduler_name":"MigrationsSched + Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.9025588,"caller":"jobs/schedulers.go:166","msg":"Next run time for scheduler","scheduler_name":"PluginsSchedule + +Configuring cluster transport encryption +----------------------------------------- + +.. include:: ../_static/badges/ent-selfhosted.rst + :start-after: :nosearch: + +Mattermost is able to encrypt the messages sent within the cluster of a deployment using SSH tunneling. The guide walks through the deployment of this solution on Ubuntu 20.04, but it can be adapted for any Linux operating system. + +While this document only describes the configuration of a three-node cluster, it is by no means limited to that number. + +Prerequisites +~~~~~~~~~~~~~ + +- SSH port whitelisted between each node of the deployment. +- Active ufw/iptables on each node. +- Access to the root/sudo user of each node for configuration. +- A configured Mattermost cluster. +- Mattermost running with a dedicated service user. +- Mattermost service is stopped on each cluster node. + +.. note:: + Support on the application level is currently in development and, when available, will deprecate this document. + +Example environment +~~~~~~~~~~~~~~~~~~~ + +In this scenario there are three application nodes in our environment with the following hostname/IP mapping: + +- **transport-encryption-mattermost1:** 10.10.250.146 +- **transport-encryption-mattermost2:** 10.10.250.231 +- **transport-encryption-mattermost3:** 10.10.250.165 + +Preparations +~~~~~~~~~~~~~ + +- Connect to each Mattermost server with a sudo or root user. +- Make a note of the IP from each cluster member used for the internal communication. +- Ensure ``AllowTcpForwarding`` is enabled in ``/etc/ssh/sshd_config`` of each cluster node. + +SSH authentication +~~~~~~~~~~~~~~~~~~~ + +On each node, generate a SSH key-pair for the service account. In our scenario this is called ``mattermost``: + +.. code-block:: sh + + sudo -u mattermost ssh-keygen -t rsa + +.. code-block:: text + + Generating public/private rsa key pair. + Enter file in which to save the key (/home/mattermost/.ssh/id_rsa): + Enter passphrase (empty for no passphrase): + Enter same passphrase again: + Your identification has been saved in /home/mattermost/.ssh/id_rsa. + Your public key has been saved in /home/mattermost/.ssh/id_rsa.pub. + The key fingerprint is: + SHA256:redacted mattermost@transport-encryption-mattermost1 + + +The location of the SSH key itself is irrelevant if company policies require the usage of another storage location. + +Next, ensure that the SSH public key of each node is added to the ``authorized_keys`` file of the other nodes of the cluster. To do so, copy the contents of ``/home/mattermost/.ssh/id_rsa.pub`` of nodes 2 and 3, and add it to ``/home/mattermost/.ssh/authorized_keys`` of node 1. + +Repeat this step for each node of the cluster. As a result, each node should be able to establish an SSH connection to the other nodes of the cluster. + +.. note:: + + This service account can be separate from the service account already used for the Mattermost ``systemd`` service itself. It's important that this service account is allowed to create a SSH tunnel with port forwarding, but it doesn't require any additional permissions. + +ufw configuration +~~~~~~~~~~~~~~~~~ + +As a next step, allow SSH access from each of the other member nodes, e.g.: + +- mattermost1 allows from mattermost2 and mattermost3 +- mattermost2 allows from mattermost1 and mattermost3 +- mattermost3 allows from mattermost1 and mattermost2 + +To do so, we add an exception in the firewall. The commands for ``mattermost1`` look as follows: + +.. code-block:: sh + + sudo ufw allow from 10.10.250.231/32 to any port ssh + sudo ufw allow from 10.10.250.165/32 to any port ssh + sudo ufw status + +.. code-block:: text + + Rule added + Rule added + Status: active + + To Action From + -- ------ ---- + 22/tcp ALLOW 10.10.250.10 + 8065/tcp ALLOW Anywhere + 22/tcp ALLOW 10.10.250.231 + 22/tcp ALLOW 10.10.250.165 + + +Repeat the same steps on the other nodes, replacing the IPs with the ones from the other member nodes. Do so for each member node, excluding the node itself. + +Next, open ``/etc/ufw/after.rules`` and add the following block to the bottom of the file: + +.. code-block:: text + + *nat + :POSTROUTING ACCEPT [0:0] + :PREROUTING ACCEPT [0:0] + + -A OUTPUT -p tcp -d 10.10.250.231 --dport 8075 -j DNAT --to-destination 127.0.0.1:18075 + -A OUTPUT -p tcp -d 10.10.250.231 --dport 8074 -j DNAT --to-destination 127.0.0.1:18074 + -A OUTPUT -p tcp -d 10.10.250.165 --dport 8075 -j DNAT --to-destination 127.0.0.1:28075 + -A OUTPUT -p tcp -d 10.10.250.165 --dport 8074 -j DNAT --to-destination 127.0.0.1:28074 + + COMMIT + + +Two lines always belong to a single node, so in a deployment with four nodes: + +.. code-block:: text + + -A OUTPUT -p tcp -d ip_node_2 --dport 8075 -j DNAT --to-destination 127.0.0.1:18075 + -A OUTPUT -p tcp -d ip_node_2 --dport 8074 -j DNAT --to-destination 127.0.0.1:18074 + -A OUTPUT -p tcp -d ip_node_3 --dport 8075 -j DNAT --to-destination 127.0.0.1:28075 + -A OUTPUT -p tcp -d ip_node_3 --dport 8074 -j DNAT --to-destination 127.0.0.1:28074 + -A OUTPUT -p tcp -d ip_node_4 --dport 8075 -j DNAT --to-destination 127.0.0.1:38075 + -A OUTPUT -p tcp -d ip_node_4 --dport 8074 -j DNAT --to-destination 127.0.0.1:38074 + +Please be aware that the ports on the right side must be unique, so if you have a cluster of six nodes, use 8075 and 8074 with 1 to 5 in front of it. If the cluster is of bigger size, additional ports must be used. + +Ensure that your operating system has IP forwarding enabled using the following command: + +.. code-block:: sh + + sysctl -w net.ipv4.ip_forward=1 + +After that, reload the ufw rules and confirm that the iptable rules were successfully created: + +.. code-block:: sh + + iptables -t nat -L + +.. code-block:: text + + Chain PREROUTING (policy ACCEPT) + target prot opt source destination + + Chain INPUT (policy ACCEPT) + target prot opt source destination + + Chain OUTPUT (policy ACCEPT) + target prot opt source destination + DNAT tcp -- anywhere 10.10.250.231 tcp dpt:8075 to:127.0.0.1:18075 + DNAT tcp -- anywhere 10.10.250.231 tcp dpt:8074 to:127.0.0.1:18074 + DNAT tcp -- anywhere 10.10.250.165 tcp dpt:8075 to:127.0.0.1:28075 + DNAT tcp -- anywhere 10.10.250.165 tcp dpt:8074 to:127.0.0.1:28074 + +Repeat those steps for every node on the cluster. At the end of this section the following should be configured: + +- SSH access enabled in firewall from each cluster node to another. +- Per node 2 iptables rules for port 8074 and 8075. +- IP forwarding enabled. + +SSH configuration +~~~~~~~~~~~~~~~~~ + +As a next step, ensure that the SSH tunnels are created as part of the Mattermost service start. To do so, create a file called ``pre_start.sh`` in ``/opt/mattermost/bin`` on ``mattermost1``: + +.. code-block:: sh + + #!/bin/bash + ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 18075:10.10.250.231:8075 10.10.250.231 || true + ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 18074:10.10.250.231:8074 10.10.250.231 || true + ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 28075:10.10.250.165:8075 10.10.250.165 || true + ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 28074:10.10.250.165:8074 10.10.250.165 || true + +.. note:: + + - We're ignoring the error from the SSH connection itself in case a tunnel is already active. Otherwise the Mattermost server would fail to start. + - Please make sure to back up this script in case of a version upgrade. + +Afterwards, set the executable bit on the shell script: + +.. code-block:: sh + + chmod +x /opt/mattermost/bin/pre_start.sh + +Open the systemd unit file of Mattermost and search for ``Type=Notify``. After this, enter a ``ExecStartPre`` script that will be executed before Mattermost itself is started: + +.. code-block:: text + + [Service] + Type=notify + ExecStartPre=/opt/mattermost/bin/pre_start.sh + +Reload the systemd daemon afterwards: + +.. code-block:: sh + + systemctl daemon-reload + +Repeat the same steps on each of the member nodes and adapt the node IPs and amount of entries for your environment. + +Cluster start +~~~~~~~~~~~~~~ + +Once each node is configured, restart the service on each cluster and confirm that it's running using the command below: + +.. code-block:: sh + + systemctl start mattermost + systemctl status mattermost.service + +.. code-block:: text + + ● mattermost.service - Mattermost + Loaded: loaded (/lib/systemd/system/mattermost.service; static; vendor preset: enabled) + Active: active (running) since Fri 2019-10-04 19:44:20 UTC; 5min ago + Process: 16734 ExecStartPre=/opt/mattermost/bin/pre_start.sh (code=exited, status=0/SUCCESS) + +Next, open the Mattermost System Console and confirm that each node is reporting successfully in the High Availability section. diff --git a/source/deploy/use-prebuilt-mobile-apps.rst b/source/deploy/use-prebuilt-mobile-apps.rst deleted file mode 100644 index a860584cb9c..00000000000 --- a/source/deploy/use-prebuilt-mobile-apps.rst +++ /dev/null @@ -1,32 +0,0 @@ -Using Mattermost's pre-built mobile apps -======================================== - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -We strongly recommend using Mattermost’s pre-built mobile app. This approach is recommended for all Mattermost customers. - -Deployment options ------------------- - -When you decide to use the pre-built Mattermost mobile apps, you have two ways to distribute them: ask your users to download them, or distribute them through an Enterprise Mobile Management (EMM) provider. - -Using public app stores -~~~~~~~~~~~~~~~~~~~~~~~ - -Your users can download the Mattermost mobile app as an `iOS app `__ or an `Android app `__ from a public app store. When users launch the Mattermost Mobile App, they must enter the address of your Mattermost server to connect their mobile app to the server. - -Using an EMM provider -~~~~~~~~~~~~~~~~~~~~~ - -See our :doc:`Deploying Using an EMM Provider ` documentation to learn more about deploying Mattermost mobile apps through an EMM provider. - -Setting up push notifications ------------------------------ - -See our :doc:`Mobile Push Notifications ` documentation to learn about setting up push notifications for Mattermost pre-built mobile apps. - -Success! Your public app store deployment is complete ------------------------------------------------------ - -If you don't need the additional security provided via an EMM provider, your deployment is complete! Feel free to point your users to our :doc:`Mattermost ` end user product documentation to learn more. diff --git a/source/getting-started/architecture-overview.rst b/source/getting-started/architecture-overview.rst deleted file mode 100644 index ee416c5b80c..00000000000 --- a/source/getting-started/architecture-overview.rst +++ /dev/null @@ -1,220 +0,0 @@ -Architecture overview -===================== - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -This page provides an overview of the Mattermost architecture with reference architecture. For a more detailed deployment overview, :doc:`check out our deployment wiki `. - -.. toctree:: - :maxdepth: 2 - -Basics ------- - -At its core, Mattermost is a single-compiled Go binary that is exposed as a Restful JSON web server with Javascript and Go clients. See the Restful API docs `here `__. - -It is configured using :doc:`config/config.json ` and provides the following: - -- **Authentication client:** The functionality for users to log into Mattermost via email address and password in Team Edition. Mattermost Professional adds the ability for users to authenticate using Active Directory or LDAP, and Mattermost Enterprise adds the ability to authenticate using SAML SSO providers like ADFS, OneLogin, and Okta. -- **Authentication provider:** Enables the Mattermost server to authenticate to other services like GitLab and Zapier using OAuth 2.0. -- **Notification service:** Sends notifications via SMTP or a Push Notification Service for mobile applications. -- **Data management service:** Connects to supported databases and file storage solutions (local, network-attached storage, Amazon S3, etc), and manages the reading and writing of data between them. - -The binary talks to a database, typically PostgreSQL, and a filestore. See the :doc:`Migrate from MySQL to PostgreSQL ` product documentation for details on migrating from MySQL to PostgreSQL. - -.. image:: ../images/architecture_basics.png - -Push notification service -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Mattermost :doc:`hosted push notification service ` can be used to send push notifications to mobile clients. Team Edition users can deploy the service using the Mattermost :ref:`test push notification service ` or :ref:`host their own push notification service ` and :doc:`compile their mobile applications ` to use that service. - -Proxy -~~~~~ - -A proxy server is a server (a computer system or an application) that acts as an intermediary for requests from clients seeking resources from other servers. Mattermost recommends using a proxy in front of Mattermost to increase security, performance and the ability to monitor and shape traffic connecting to Mattermost: - -- **Security:** A proxy server can manage Secure Socket Layer (TLS/SSL) encryption and set policy on how network traffic will be routed to the Mattermost server. -- **Performance:** In a High Availability configuration, the proxy server balances the network load across multiple Mattermost servers for optimized performance. A hardware proxy with dedicated devices for processing SSL encryption and decryption can also be used to increase performance. -- **Monitoring**: A proxy server can monitor connection traffic and record traffic in standard audit logs that common monitoring tools like Kibana and Splunk can consume and report on. Some of the events that can be captured include file uploads and downloads, which are not tracked by the Mattermost server logging process. - -Mattermost provides documentation and support for the `NGINX proxy `_. For information on how to install and configure NGINX for your environment, see :doc:`our deployment guides `. Mattermost also unofficially supports other proxies including Apache 2. - -.. image:: ../images/architecture_with_proxy.png - -Communication protocols -~~~~~~~~~~~~~~~~~~~~~~~ - -There are also communication protocols (HTTPS and WS) that define the type of connection the user makes with the Mattermost server. - -**HTTPS Connection** (Secure Hypertext Transfer Protocol) - -- HTTPS connections to the Mattermost server render pages and provide access to core platform functionality, but do not include real-time interactivity (which is enabled by WSS connections). -- HTTPS is a secure, encrypted protocol and is highly recommended for production. Unencrypted HTTP connections may be used in initial testing and configuration, but should never be used in a production environment. - -**WSS Connection** (Secure WebSocket Protocol) - -Secure WebSocket (WSS) connections to the Mattermost Server enable real-time updates and notifications between clients and the server. - -If a WSS connection is not available and HTTPS is substituted, the system will appear to work but real-time updates and notifications will not. In this mode of operation, updates will only appear on a page refresh. WSS has a persistent connection to the Mattermost server when a client is connected, while HTTPS has an intermittent connection and only connects to the server when a page or file is requested. - -.. image:: ../images/architecture_with_protocol.png - -Mattermost services ports -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following table lists the Mattermost services ports for Mattermost Server, push proxy, and mobile app clients. System admins with clients that need to speak to the Mattermost server without a proxy can open specific firewall ports as needed. - -**Mattermost Server** - -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| Service Name | Config Setting | Port (default) | Protocol | Direction | Info | -+=============================================================+=======================================+===================================+===========+============+===============================================================+ -| HTTP/Websocket | ServiceSettings.ListenAddress | 8065/80/443 (TLS) | TCP | Inbound | External (no proxy) / Internal (with proxy) | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+ Usually this requires port 80 and 443 when running HTTPS. | -| | | | | | | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| Cluster | ClusterSettings.GossipPort | 8074 | TCP/UDP | Inbound | Internal | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| Metrics | MetricsSettings.ListenAddress | 8067 | TCP | Inbound | External (no proxy) / Internal (with proxy) | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| Database | SqlSettings.DataSource | 5432 (PostgreSQL) / 3306 (MySQL) | TCP | Outbound | Usually internal (recommended) | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| LDAP | LdapSettings.LdapPort | 389 | TCP/UDP | Outbound | | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| S3 Storage | FileSettings.AmazonS3Endpoint | 443 (TLS) | TCP | Outbound | | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| SMTP | EmailSettings.SMTPPort | 10025 | TCP/UDP | Outbound | | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ -| Push Notifications | EmailSettings.PushNotificationServer | 443 (TLS) | TCP | Outbound | | -+-------------------------------------------------------------+---------------------------------------+-----------------------------------+-----------+------------+---------------------------------------------------------------+ - -**Push Proxy** - -+---------------+-----------------+-----------------+-----------+------------+----------------------------------------------+ -| Service Name | Config Setting | Port (default) | Protocol | Direction | Info | -+===============+=================+=================+===========+============+==============================================+ -| Push Proxy | ListenAddress | 8066 | TCP | Inbound | External (no proxy) / Internal (with proxy) | -+---------------+-----------------+-----------------+-----------+------------+----------------------------------------------+ - -**Mobile Clients** - -In order to receive push notifications, your network must allow traffic on `port 5223 for iOS devices `_ and `ports 5228-5230 for Android `_. - -High Availability and scalability ---------------------------------- - -Mattermost Enterprise supports: - -1. Clustered Mattermost servers, which minimize latency by: - -- Storing static assets over a global CDN. -- Deploying multiple Mattermost servers to host API communication closer to the location of end users. - -They can also be used to handle scale and failure handoffs in disaster recovery scenarios. - -2. Database read replicas, where replicas can be: - -- Configured as a redundant backup to the active database server. -- Used to scale up the number of concurrent users. -- Deployed closer to the location of end users, reducing latency. - -Moreover, search replicas are also supported to handle search queries. - -.. image:: ../images/architecture_high_availability.png - -Reference architectures ------------------------ - -The following diagrams show the suggested architecture configurations enterprise deployments of Mattermost at different scales. These diagrams are meant as guidelines for typical Mattermost deployments. Hardware and infrastructure requirements can vary significantly based on usage and policies. - -There are two versions of each diagram. One is generalized while the other focuses on AWS. - -Each generalized diagram represents a full High Availability deployment across all critical components. The proxy, database, file storage, and Elasticsearch layers can be replaced by cloud services. Push proxy can be replaced by the Mattermost :doc:`HPNS `. - -Each AWS diagram represents a full High Availability deployment on Amazon Web Services making full use of the available services. Push proxy can optionally be deployed manually in place of HPNS. - -5,000 users on Enterprise - General -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment5kUsers.png - :class: bg-white - -5,000 users on Enterprise - AWS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment5kaws.png - :class: bg-white - -5,000 users on Enterprise - Azure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment5kAzure.png - :class: bg-white - -10,000 users on Enterprise - General -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment10kUsers.png - :class: bg-white - -10,000 users on Enterprise - AWS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment10kaws.png - :class: bg-white - -10,000 users on Enterprise - Azure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment10kAzure.png - :class: bg-white - -25,000 users on Enterprise - General -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment25kUsers.png - :class: bg-white - -25,000 users on Enterprise - AWS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment25kaws.png - :class: bg-white - -25,000 users on Enterprise - Azure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment25kAzure.png - :class: bg-white - -50,000 users on Enterprise - AWS -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment50kaws.png - :class: bg-white - -50,000 users on Enterprise - Azure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. image:: ../images/MattermostDeployment50kAzure.png - :class: bg-white - -Database with VIPs -~~~~~~~~~~~~~~~~~~ - -The following diagram is a suggested configuration for Highly-Available databases through virtual IPs. - -.. image:: ../images/DatabasewithVIPs.png - :class: bg-white - -Load testing -~~~~~~~~~~~~ - -Mattermost Enterprise Edition was `load tested `__ with 60,000 concurrent active users with: - -- Six Mattermost servers: m4.2xlarge (8 vCPU, 32 GB RAM) -- One MySQL database server with five read replicas: db.r4.2xlarge (8 vCPU, 61 GB RAM) -- Three load test runners (for running the loadtest) -- Three NGINX proxies diff --git a/source/getting-started/implementation-plan.rst b/source/getting-started/implementation-plan.rst deleted file mode 100644 index 746668b124b..00000000000 --- a/source/getting-started/implementation-plan.rst +++ /dev/null @@ -1,374 +0,0 @@ -Implementation plan -=================== - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -1 Introduction --------------- - -1.1 Purpose -~~~~~~~~~~~ - -Mattermost is an open source, private cloud alternative to proprietary SaaS collaboration solutions designed to offer organizations superior control, data sovereignty, configurability, freedom from lock-in, and enhanced security by keeping vital communications behind your firewall. You've chosen to implement Mattermost in our supported `editions and offerings:`_ - -.. _`editions and offerings:`: https://docs.mattermost.com/about/editions-and-offerings.html - -The purpose of this Implementation Plan is to: - -- Describe the solution to be deployed; -- Outline the process for implementing the solution (key personnel, tasks, schedule, etc.); -- Identify support required during the implementation process. - -2 System overview ------------------ - -This section provides a brief overview of the system to be implemented, including a description of the system and its organization. - -2.1 System description -~~~~~~~~~~~~~~~~~~~~~~ - -Mattermost is a collaboration solution designed to remove organizational friction. You're implementing Mattermost in order to: - -1. **[STATE REASON]** -2. **[STATE REASON]** -3. **[STATE REASON]** - -In this implementation, you are planning to deploy Mattermost to **[NUMBER OF USERS]** users on the following teams: - -1. **[TEAM 1]** -2. **[TEAM 2]** -3. **[TEAM 3]** - -2.2 System organization -~~~~~~~~~~~~~~~~~~~~~~~~ - -A Mattermost Enterprise implementation consists of the following system components: - -- **Mattermost Server** - - The Mattermost Server is a single binary that includes the RESTful JSON web service, authentication client, authentication provider, notification service, and data management service. The Mattermost Server can be deployed in stand-alone or high availability mode where two or more servers are clustered together using gossip protocol and a proxy server that routes traffic from client applications to healthy servers in the cluster. -- **Mattermost Database** - - A PostgreSQL database in stand-alone or high-availability configurations (master with read replicas). When choosing the database, consider the :ref:`inherent search limitations of the database type ` and whether :doc:`Elasticsearch ` is most appropriate for your deployment. See the :doc:`Migrate from MySQL to PostgreSQL ` product documentation for details on migrating from MySQL to PostgreSQL. -- **Mattermost Push Notification Service** - - Hosted or on-premise service that pushes notifications to Mattermost Android and Mattermost iOS mobile applications. -- **Mattermost Client Applications** - - Client applications are available for Mattermost for the following platforms: Android, iOS, Windows, OSX, and Linux (Beta). -- **Mattermost Web Client** - - Mattermost users can use their favorite Web browser to connect to their Mattermost server in place of the Mattermost mobile and desktop applications. -- **Proxy Server** - - The use of a proxy server (NGINX, Apache, HAProxy, ELB, etc.) is recommended with Mattermost to obtain the benefits of: SSL termination, HTTP to HTTPS redirection, port mapping :80 to :8065, and the creation of standard request logs. - -The following diagram is a high-level illustration of the Mattermost platform and how its various components interact with each other within a network: - -.. image:: ../images/network-diagram.svg - :alt: Mattermost network diagram shows how the various system components of the Mattermost platform interact with each other within a network deployment. - :class: bg-white - -**Reference**: https://docs.mattermost.com/deploy/deployment-overview.html - -A recommended installation of Mattermost Enterprise configured with a redundant, highly available, highly scalable mode, with application (Mattermost Server) and database High Availability features enabled, will require the following physical, or virtual, servers: - -+-------------------+---------+---------------+--------+----------+ -| Task | Qty | CPU | Memory | Storage | -+===================+=========+===============+========+==========+ -| Mattermost Server | 2 | 2 vCPUs/cores | 4 GB | 45-90 GB | -+-------------------+---------+---------------+--------+----------+ -| Database Server | 2 | 2 vCPUs/cores | 8 GB | 100 GB | -+-------------------+---------+---------------+--------+----------+ -| Proxy | 2 | 1 vCPUs/cores | 4 GB | 10 GB | -+-------------------+---------+---------------+--------+----------+ - -.. note:: - See the :ref:`Mattermost hardware sizing guidance ` documentation for details. - -2.3 Project references -~~~~~~~~~~~~~~~~~~~~~~ - -This section provides a bibliography of key project references and deliverables that have been produced before this point in the project development. - -- Mattermost Overview: https://docs.mattermost.com/about/product.html -- Mattermost Software/Hardware Requirements: https://docs.mattermost.com/install/software-hardware-requirements.html -- Mattermost Security Features: https://docs.mattermost.com/about/security.html -- Mattermost: https://docs.mattermost.com/guides/collaborate.html -- Collaborative playbooks: https://docs.mattermost.com/guides/repeatable-processes.html - -2.4 Glossary -~~~~~~~~~~~~ - -Provide a glossary of all terms and abbreviations used in the manual. If it is several pages in length, it may be placed in an appendix. - -3 Management overview ---------------------- - -The subsequent sections provide a brief description of the implementation and major tasks involved in this section. - -3.1 Description of implementation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -3.2 Team -~~~~~~~~ - -In this section, identify the System Proponent, the name of the responsible organization(s), and titles and telephone numbers of the staff who serve as points of contact for the system implementation. These points of contact could include the Project Manager. Program Manager, Security Manager. Database Administrator, Configuration Management Manager, or other managers with responsibilities relating to the system implementation. The site implementation representative for each field installation or implementation site should also be included, if appropriate. List all managers and staff with whom the implementation must be coordinated. - -3.2.1 Team members -^^^^^^^^^^^^^^^^^^ - -+----------+-----------------+----------------------+--------------+ -| Name | Title | Email | Phone | -+==========+=================+======================+==============+ -| Jane Doe | Project Manager | jane.doe@company.com | 111.111.1111 | -+----------+-----------------+----------------------+--------------+ -| | | | | -+----------+-----------------+----------------------+--------------+ -| | | | | -+----------+-----------------+----------------------+--------------+ - -3.3 Major tasks -~~~~~~~~~~~~~~~~ - -This section provides a brief description of each major task required for the implementation of the system. Add as many subsections as necessary to this section to describe all the major tasks adequately. The tasks described in this section are not site-specific, but generic or overall project tasks that are required to install hardware and software, prepare data, and verify the system. - -3.3.1 Create system architecture document -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The system architecture document is used to document the environments that Mattermost will be deployed to including: - -- The environment (development, staging, production, etc.) -- Server, or virtual machine, specifications -- IP addresses and DNS -- Network diagram - -**Reference**: https://docs.mattermost.com/deploy/deployment-overview.html - -3.3.2 Gather required software and documentation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Gather all of the software and documentation required for a successful implementation of the Mattermost platform and place it within the organization’s configuration management system. - -3.3.3 Prepare deployment environments -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Build out the required deployment environments (development, staging, production, etc.) and implement configuration management (using a tool like Chef, Puppet, Salt, etc.) - -**Reference**: https://docs.mattermost.com/install/software-hardware-requirements.html - -3.3.4 Install software -^^^^^^^^^^^^^^^^^^^^^^ - -Install and configure Mattermost and its component software (PostgreSQL, NGINX, or another proxy, etc.) - -**Reference**: https://docs.mattermost.com/guides/deployment.html#install-guides - -Install in High Availability (Available in Mattermost Enterprise): https://docs.mattermost.com/scale/high-availability-cluster-based-deployment.html - -3.3.5 Test deployment -^^^^^^^^^^^^^^^^^^^^^ - -Verify that the software has been deployed successfully in each environment. Create, or update, automated tests to verify deployments. - -**Reference**: https://docs.mattermost.com/manage/health-checks.html - -3.3.6 Bulk load data -^^^^^^^^^^^^^^^^^^^^ - -Large quantities of data can be imported from a JSON file into Mattermost at the command line using the bulk loading feature. This feature is most suitable for migrating data from an existing system, or for pre-populating a new installation with data. - -You can import the following data types: - -- Teams -- Channels (public and private) -- Users -- Users’ team memberships -- Users’ channel memberships -- Users’ notification preferences -- Posts (regular, non-reply posts) -- Direct message and group message channels -- Direct messages and group messages - -**Reference**: https://docs.mattermost.com/onboard/bulk-loading-data.html - -3.3.7 Implement backup -^^^^^^^^^^^^^^^^^^^^^^ - -Implement backup procedures to protect data stored within the Mattermost database, files uploaded by users, and the Mattermost ``config.json`` file. - -**Reference**: https://docs.mattermost.com/deploy/backup-disaster-recovery.html - -3.3.8 Implement monitoring -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mattermost Enterprise supports integrated health and performance monitoring with Prometheus and Grafana. A guide to the statistics collected and reported on is available in the reference below: - -**Reference**: https://docs.mattermost.com/scale/deploy-prometheus-grafana-for-performance-monitoring.html - -3.3.9 AD/LDAP setup -^^^^^^^^^^^^^^^^^^^^ - -Available in Mattermost Enterprise and Professional subscription plans. - -Mattermost supports AD/LDAP integration for user authentication and user attribute syncing. - -**Reference**: https://docs.mattermost.com/onboard/ad-ldap.html - -3.3.10 Multi-factor authentication -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Available in Mattermost Enterprise and Professional subscription plans. - -Configure multi-factor authentication (“MFA”) if required as part of your IT security policy. Compatible with Google Authenticator. - -**Reference**: https://docs.mattermost.com/onboard/multi-factor-authentication.html - -3.3.11 SAML Single-Sign-On -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Available in Mattermost Enterprise and Professional subscription plans. - -Mattermost can be configured to act as a SAML 2.0 Service Provider. Mattermost officially supports Okta, OneLogin, and Microsoft ADFS as the identity providers (IDPs). - -**Reference**: https://docs.mattermost.com/onboard/sso-saml.html - -3.3.12 Train administrators -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Train administrators on the tasks required to manage Mattermost. - -**Reference**: https://docs.mattermost.com/guides/administration.html - -3.3.13 Update legal and support settings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mattermost has configuration settings for the terms of service, privacy policy, and support URLs and emails. It is highly recommended that you modify these in your configuration so that your users have the correct legal information and can contact administrators to resolve account issues. You can find these under **System Console > Legal and Support** in prior versions or **System Console** > **Site Configuration** > **Customization** in versions after 5.12. - -.. image:: ../images/legal_and_support_settings.png - :alt: Legal and Support settings - -3.3.14 Onboard users -^^^^^^^^^^^^^^^^^^^^ - -Send all users a welcome email with instructions on how to get started using Mattermost including links to the mobile applications and the User Guide. - -**References**: -- Links to download Mattermost apps: https://mattermost.com/apps -- Channels Guide: https://docs.mattermost.com/guides/collaborate.html - -3.4 Implementation schedule -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In this section, provide a schedule of activities to be accomplished during implementation. Show the required tasks (described in Section 3.3, Major Tasks) in chronological order, with the beginning and end dates of each task. - -+----+--------------------------------------------+------------+------------+ -| | Task | Start Date | End Date | -+====+============================================+============+============+ -| 1 | Create System Architecture Document | xx/xx/xxxx | xx/xx/xxxx | -+----+--------------------------------------------+------------+------------+ -| 2 | Gather Required Software and Documentation | | | -+----+--------------------------------------------+------------+------------+ -| 3 | Prepare Deployment Environments | | | -+----+--------------------------------------------+------------+------------+ -| 4 | Install Software | | | -+----+--------------------------------------------+------------+------------+ -| 5 | Test Deployment | | | -+----+--------------------------------------------+------------+------------+ -| 6 | Bulk Load Data | | | -+----+--------------------------------------------+------------+------------+ -| 7 | Implement Backup | | | -+----+--------------------------------------------+------------+------------+ -| 8 | Implement Monitoring | | | -+----+--------------------------------------------+------------+------------+ -| 9 | Train Administrators | | | -+----+--------------------------------------------+------------+------------+ -| 10 | Onboard Users | | | -+----+--------------------------------------------+------------+------------+ - -3.5 Security -~~~~~~~~~~~~ - -If appropriate for the system to be implemented, include an overview of the system security features and requirements during the implementation. - -3.5.1 System security features -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The Mattermost platform will be secured in the following ways: - -- Mattermost will be hosted entirely on-premises behind your company firewall with access restricted to VPN connections; -- Mobile access to Mattermost will be further restricted by the use of multi-factor authorization; -- Transmissions to and from Mattermost will be encrypted using TLS; -- Encryption-at-rest will be applied using your company's standards; -- Mattermost’s integrity and audit controls store a complete history of messages, including edits and deletes, along with all files uploaded. User interface actions for “deleting” messages and channels remove the data only from the user interface; the data is retained within your database. If your compliance guidelines require it, you can turn off users’ ability to edit and delete their messages after they are posted. -- Mattermost will be protected against brute force attacks by its rate limiting API; -- Authentication to Mattermost will be controlled using your company's Active Directory/LDAP/SAML directory server. - -**Reference**: https://docs.mattermost.com/about/security.html - -3.5.2 Security during implementation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This section addresses security issues specifically related to the implementation effort, if any. For example, if LAN servers or workstations will be installed at a site with sensitive data preloaded on non-removable hard disk drives, address how security would be provided for the data on these devices during shipping, transport, and installation because theft of the devices could compromise the sensitive data. - -4 Implementation support ------------------------- - -This section describes the support software, materials, equipment, and facilities required for the implementation, as well as the personnel requirements and training necessary for the implementation. The information provided in this section is not site-specific. If there are additional support requirements not covered by the subsequent sections, others may be added as needed. - -4.1 Hardware, software, facilities, and materials -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In this section, list support software, materials, equipment, and facilities required for the implementation, if any. - -4.1.1 Hardware -^^^^^^^^^^^^^^ - -This section provides a list of support equipment and includes all hardware used for testing time implementation. For example, if a client/server database is implemented on a LAN, a network monitor or “sniffer” might be used, along with test programs. to determine the performance of the database and LAN at high-utilization rates. If the equipment is site-specific, list it in Section 5, Implementation Requirements by Site. - -4.1.2 Software -^^^^^^^^^^^^^^ - -This section provides a list of software and databases required to support the implementation. Identify the software by name, code, or acronym. Identify which software is commercial off-the-shelf and which is State-specific. Identify any software used to facilitate the implementation process. If the software is site-specific, list it in Section 4. - -4.1.3 Facilities -^^^^^^^^^^^^^^^^ - -In this section, identify the physical facilities and accommodations required during implementation. Examples include physical workspace for assembling and testing hardware components, desk space for software installers, and classroom space for training the implementation stall. Specify the hours per day needed, number of days, and anticipated dates. If the facilities needed are site-specific, provide this information in Section 4, Implementation Requirements by Site. - -4.1.4 Material -^^^^^^^^^^^^^^ - -This section provides a list of required support materials, such as magnetic tapes and disk packs. - -4.2 Personnel -~~~~~~~~~~~~~ - -This section describes personnel requirements and any known or proposed staffing requirements, if appropriate. Also describe the training, if any, to be provided for the implementation staff. - -4.2.1 Personnel requirements and staffing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In this section, describe the number of personnel, length of time needed, types of skills, and skill levels for the staff required during the implementation period. If particular staff members have been selected or proposed for the implementation, identify them and their roles in the implementation. - -4.2.2 Training of implementation staff -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This section addresses the training, if any, necessary to prepare staff for implementing and maintaining the system; it does not address user training, which is the subject of the Training Plan. Describe the type and amount of training required for each of the following areas, if appropriate, for the system: - -- System hardware/software installation -- System support -- System maintenance and modification - -Present a training curriculum listing the courses that will be provided, a course sequence. and a proposed schedule. If appropriate, identify which courses particular types of staff should attend by job position description. - -If training will be provided by one or more commercial vendors, identify them, the course name(s), and a brief description of the course content. - -If the training will be provided by State staff, provide the course name(s) and an outline of the content of each course. Identify the resources, support materials, and proposed instructors required to teach the course(s). - -4.3 Performance monitoring -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Available in Mattermost Enterprise. - -This section describes the performance monitoring tool and techniques and how it will be used to help decide if the implementation is successful: https://docs.mattermost.com/scale/deploy-prometheus-grafana-for-performance-monitoring.html - -4.4 Configuration management interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section describes the interactions required with the Configuration Management (CM) representative on CM-related issues, such as when software listings will be distributed, and how to confirm that libraries have been moved from the development to the production environment. diff --git a/source/getting-started/light-install.rst b/source/getting-started/light-install.rst deleted file mode 100644 index 908f71fb8d2..00000000000 --- a/source/getting-started/light-install.rst +++ /dev/null @@ -1,70 +0,0 @@ -:orphan: - -Light install guide -=================== - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -Mattermost is a collaboration platform. With Mattermost, you can integrate the tools you use every day into one place and never miss a notification or task. - -Before you get started you'll need: - -* A clean Ubuntu server with root level access -* (Recommended) A domain name pointing to your server (e.g. ``mymattermostserver.com``) -* (Recommended) Email addresses of your team members so you can invite them to the server - -Installation -------------- - -Install Mattermost using :doc:`Mattermost Omnibus `. - -Open a terminal window and enter: - -.. code-block:: sh - - curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash - -Then, to install the Omnibus package, run: - -.. code-block:: sh - - sudo apt install mattermost-omnibus - -.. note:: - - Although the recommended way to install and configure Omnibus is with SSL enabled, if you want to use or test without it (or without a domain name), you can run: - - .. code-block:: sh - - sudo MMO_HTTPS=false apt install mattermost-omnibus - -When your server is up and running, navigate to it via the domain name (e.g. ``mymattermostserver.com``) that points to your server (or the server’s IP address if you’re not using a domain name). Next, create a team and invite people to join your Mattermost server. - -If you have any problems installing Mattermost Omnibus, see the :doc:`troubleshooting guide ` for common error messages, or `join the Mattermost user community for troubleshooting help `_. - -Add users ---------- - -Next, add people to your team by sending them an invitation: - -1. Select your team name at the top left corner of Mattermost. -2. Select **Invite People** and enter the email addresses of the people you want to add. -3. Select **Invite Members**. - -When the invitee receives the email with the link, it’s a single click to join your server, chat to you in the channel you’ve created, or create their own channels. More information about adding users is available :doc:`here `. - -Create a notifications hub --------------------------- - -Create a `“heartbeat” channel `_ and integrate your most-used apps and plugins with Mattermost to send status updates and critical notifications in one place. - -You can find and install integrations and plugins via **Product menu > Marketplace**. - -Get started with GitHub, Jira, and Jenkins: - -* Connect your GitHub organization to Mattermost using a slash command, to manage your reviews, pull requests, comments, and merges. GitHub is pre-packaged in Mattermost. Follow the `configuration steps `_, and then let your team know to run /github connect so they can receive notifications. -* Connect your Jira account to Mattermost and set up a channel for the bot to post issues so your team is always up to date. Visit the `configuration guide `_ to get started. Once configured, share the `end user documentation `_ with your team so they can start receiving notifications. -* Connect your Jenkins server to Mattermost to centralize your workflows and manage builds. Visit the `installation guide `_ to get started. Share the `features list `_ with your team so they can ramp up quickly. - -**Next:** :doc:`Learn more about organizing conversations ` and setting up :doc:`Mattermost on your mobile device `. diff --git a/source/guides/additional-server-installation-guides.rst b/source/guides/additional-server-installation-guides.rst deleted file mode 100644 index e7dac467c6e..00000000000 --- a/source/guides/additional-server-installation-guides.rst +++ /dev/null @@ -1,17 +0,0 @@ -Additional server installation guides -===================================== - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Deploy Mattermost on Bitnami - AWS Elastic Beanstalk Docker setup - Open source components - -These guides are for administrators looking for alternate deployment methods as well as a list of all open source copmonents included across Mattermost releases. - -* :doc:`Deploy Mattermost on Bitnami ` -* :doc:`AWS Elastic Beanstalk Docker setup ` -* :doc:`Open source components ` diff --git a/source/guides/administration-guide.rst b/source/guides/administration-guide.rst new file mode 100644 index 00000000000..9c09535c371 --- /dev/null +++ b/source/guides/administration-guide.rst @@ -0,0 +1,31 @@ +Administration Guide +===================== + +Welcome to the Mattermost Administration Guide. This guide is organized into sections based on administrative tasks and scenarios to help you effectively manage and optimize your Mattermost workspace. + +Whether you’re configuring server settings, managing users, monitoring performance, or ensuring compliance, this guide provides all the information you need. Use the navigation below to access detailed instructions and best practices for each topic. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Self-hosted billing + Cloud workspace management + Server maintenance + Server configuration + User provisioning + User management + Monitoring and performance + Compliance + Migration + +* :doc:`Self-hosted billing ` - Billing and payment options for Mattermost self-hosted deployments. +* :doc:`Cloud workspace management ` - Learn how to manage cloud workspaces in Mattermost. +* :doc:`Server maintenance ` - Learn about Mattermost server maintenance and best practices. +* :doc:`Server configuration ` - Learn about server configuration and settings. +* :doc:`User provisioning ` - Learn about user provisioning and management. +* :doc:`User management ` - Learn about user management and best practices. +* :doc:`Monitoring and performance ` - Learn about monitoring and performance optimization. +* :doc:`Compliance ` - Learn about compliance and security best practices. +* :doc:`Migration ` - Learn about migrating to Mattermost. \ No newline at end of file diff --git a/source/guides/administration.rst b/source/guides/administration.rst deleted file mode 100644 index a265506b546..00000000000 --- a/source/guides/administration.rst +++ /dev/null @@ -1,28 +0,0 @@ -Manage Mattermost -================== - -.. include:: ../_static/badges/allplans-cloud-selfhosted.rst - :start-after: :nosearch: - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Get started - Cloud workspace management - Self-hosted administration - Other resources - -This guide is for people who administer an existing Mattermost server using the System Console, the ``config.json`` file, or through the management of environment variables. - -As a system admin, access the System Console by selecting the **Product** |product-list| menu and selecting **System Console**. - -This administrative guide is divided into 4 parts: - -* :doc:`Get started ` - An overview of standard configurations and features for both self-hosted and Cloud deployments. -* :doc:`Cloud workspace management ` - Detailed information about admin capabilities of Mattermost Cloud deployments. -* :doc:`Self-hosted administration ` - Detailed information about admin capabilities of self-hosted Mattermost servers. -* :doc:`Other resources ` - Additional migration, conversion, and troubleshooting resources. - -If you’re looking for resources to help you install, deploy, and scale your self-hosted Mattermost server, see the :doc:`Mattermost Deployment Guide `. diff --git a/source/guides/cloud-workspace-management.rst b/source/guides/cloud-workspace-management.rst index d51777af869..b45b6f54b95 100644 --- a/source/guides/cloud-workspace-management.rst +++ b/source/guides/cloud-workspace-management.rst @@ -5,7 +5,7 @@ This section of the guide is for system admins of Mattermost Cloud deployments. .. tip:: - If you're the system admin for a Mattermost self-hosted workspace, see the :doc:`Self-hosted administration ` documentation. + If you're the system admin for a Mattermost self-hosted workspace, see the :doc:`Self-hosted administration ` documentation. .. toctree:: :maxdepth: 1 diff --git a/source/guides/compliance-with-mattermost.rst b/source/guides/compliance-with-mattermost.rst index 977be7e7bdd..0021d24b628 100644 --- a/source/guides/compliance-with-mattermost.rst +++ b/source/guides/compliance-with-mattermost.rst @@ -15,6 +15,7 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com Logging Export channel data Legal Hold + JSON audit log schema * :doc:`Compliance exports ` - Export compliance reports to third-party systems to archive history. * :doc:`Compliance monitoring ` - Enable oversight and prevent unauthorized queries with compliance exports. @@ -22,4 +23,5 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com * :doc:`Data retention ` - Control how long data is stored in Mattermost with global and custom retention policies to meet data retention compliance requirements. * :doc:`Logging ` - Learn how to customize logging options based on business practices and needs. * :doc:`Export channel data ` - Migrate data between systems and back data up for operational continuity. -* :doc:`Legal Hold ` - Preserve relevant Mattermost information when litigation is anticipated. \ No newline at end of file +* :doc:`Legal Hold ` - Preserve relevant Mattermost information when litigation is anticipated. +* :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. \ No newline at end of file diff --git a/source/guides/deployment-guide.rst b/source/guides/deployment-guide.rst new file mode 100644 index 00000000000..cf7da89f87e --- /dev/null +++ b/source/guides/deployment-guide.rst @@ -0,0 +1,42 @@ +Deployment Guide +================ + +Welcome to deployment guidance for Mattermost. This guide is organized into sections based on application types and deployment scenarios to help you achieve a successful deployment of Mattermost across various platforms. + +Whether you're deploying the server application, desktop application, or mobile application, or troubleshooting deployments, this guide has you covered. Use the navigation below to access detailed information about each topic. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Application Architecture + Server Deployment + Desktop App Deployment + Mobile App Deployment + Deployment Troubleshooting + +* :doc:`Application architecture ` - An overview of Mattermost's architecture and components. +* :doc:`Server deployment ` - Pre-deployment checks, security considerations, hardware recommendations, software prerequisites, and step-by-step guidance to deploying Mattermost server. +* :doc:`Desktop deployment ` - Installation procedures for Mattermost's desktop applications across Windows, macOS, and Linux, and large-scale, enterprise-wide deployments. +* :doc:`Mobile deployment ` - How to set up push notifications using Mattermost's notification service and troubleshooting tips. +* :doc:`Deployment troubleshooting ` - Best practices for diagnosing and resolving common deployment issues. + +How to use this guide +---------------------- + +Navigate through the sections using the headings above to find the deployment instructions and troubleshooting steps pertinent to your needs. Each section is designed to provide clear, actionable information to ensure a successful deployment and operation of Mattermost. + +If you are new to Mattermost, we recommend starting with the Preparations section under Server Application to understand the prerequisites and get started. + +.. note:: + + - Mattermost server deployment is officially supported on Linux operating systems only. + - macOS and Windows deployments are supported for testing and development purposes only. + - If you encounter issues that aren't covered in this documentation: + + - Non-commercial customers: Reference the `Mattermost community forums `_ + - Commercial customers: See the `Mattermost Support Knowledge Base `_, or `contact Mattermost Support `_ for assistance. + - For advanced customization or integrations, refer to the :doc:`Open source components ` documentation for details about extending Mattermost functionality. + +Enjoy deploying Mattermost with confidence! diff --git a/source/guides/deployment-guides.rst b/source/guides/deployment-guides.rst deleted file mode 100644 index edddaaebd32..00000000000 --- a/source/guides/deployment-guides.rst +++ /dev/null @@ -1,15 +0,0 @@ -Deployment guides -================= - -These deployment guides are for administrators who are ready to integrate Mattermost with their organization’s IT infrastructure. - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Server deployment - Desktop and mobile app deployment - -* :doc:`Server deployment ` - Guides for admins setting up a self-hosted deployment. -* :doc:`Desktop and mobile app deployment ` - Guides for admins deploying the desktop and mobile apps. \ No newline at end of file diff --git a/source/guides/deployment-troubleshooting.rst b/source/guides/deployment-troubleshooting.rst index 13faa597a1f..87df95c2273 100644 --- a/source/guides/deployment-troubleshooting.rst +++ b/source/guides/deployment-troubleshooting.rst @@ -6,14 +6,18 @@ Deployment troubleshooting :hidden: :titlesonly: - General troubleshooting - Troubleshooting mobile applications - PostgreSQL installation troubleshooting - MySQL installation troubleshooting + General deployment troubleshooting + Docker deployment troubleshooting + Desktop app troubleshooting + Mobile app troubleshooting + PostgreSQL installation troubleshooting + MySQL installation troubleshooting These guides will help you troubleshoot aspects of your Mattermost deployment. -* :doc:`General deployment troubleshooting ` -* :doc:`Mobile applications troubleshooting ` -* :doc:`PostgreSQL installation troubleshooting ` -* :doc:`MySQL installation troubleshooting ` \ No newline at end of file +* :doc:`General deployment troubleshooting ` +* :doc:`Docker deployment troubleshooting ` +* :doc:`Desktop app installation troubleshooting ` +* :doc:`Mobile applications troubleshooting ` +* :doc:`PostgreSQL installation troubleshooting ` +* :doc:`MySQL installation troubleshooting ` \ No newline at end of file diff --git a/source/guides/deployment.rst b/source/guides/deployment.rst deleted file mode 100644 index 6ba2da00140..00000000000 --- a/source/guides/deployment.rst +++ /dev/null @@ -1,58 +0,0 @@ -Deploy Mattermost -================= - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -Learn how to install, deploy, and scale Mattermost for teams and organizations of any size. - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Migrate from MySQL to PostgreSQL - Prepare your Mattermost database - Deploy on Ubuntu - Deploy using Docker - Deploy with a tarball - Deploy using Omnibus - Deploy using Kubernetes - Deploy Mattermost on Azure AKS - Deploy on Red Hat - Set up an NGINX proxy - Set up TLS - Prepare for your Mattermost deployment - Deployment guides - Upgrade Mattermost - Scale Mattermost - Secure Mattermost - Compliance with Mattermost - Deployment troubleshooting - Additional server installation guides - -.. tip:: - - * See the :doc:`configuration settings ` documentation to learn more about customizing your production deployment. - - * Encountering issues with your deployment? See the :ref:`Deployment Troubleshooting ` documentation for details. - -* :doc:`Migrate from MySQL to PostgreSQL ` - Learn how to migrate from MySQL to PostgreSQL. -* :doc:`Prepare your Mattermost database ` - Learn how to prepare and configure a database for Mattermost. -* :doc:`Deploy on Ubuntu ` - Signed packages direct from Mattermost featuring a single command for install and upgrades. -* :doc:`Deploy using Docker ` - The fastest way to try Mattermost and a great single server installation option. -* :doc:`Deploy with a tarball ` - Support for any Linux distribution. -* :doc:`Deploy using Omnibus ` - An entire Mattermost installation on a single server. -* :doc:`Deploy using Kubernetes ` - Install using the Mattermost Helm Chart or Operator and simplified updates. -* :doc:`Deploy Mattermost on Azure AKS ` - Deploy Mattermost on Azure AKS. -* :doc:`Deploy on Red Hat ` - Support for all current Red Hat Enterprise Linux platforms with a tarball. -* :doc:`Set up NGINX proxy ` - Learn how to configure Mattermost for HTTPS for deployments of more than 200 users. -* :doc:`Set up TLS ` - Learn how to configure Mattermost for HTTPS for deployments of fewer than 200 concurrent users. -* :doc:`Deployment guides ` - for administrators who are ready to integrate Mattermost with their organization’s IT infrastructure. -* :doc:`Prepare for your Mattermost deployment ` - Review software and hardware requirements for Mattermost server, and plan out your Mattermost rollout. -* :doc:`Upgrade Mattermost ` - Learn how to stay up to date with the latest features and improvements. -* :doc:`Scale Mattermost ` - Learn how to scale and monitor your Mattermost deployment. -* :doc:`Secure Mattermost ` - Learn how to safeguard your Mattermost data. -* :doc:`Compliance with Mattermost ` - Learn how to keep sensitive data safe and compliant in the strictest, most complex environments. -* :doc:`Deployment troubleshooting ` - Having trouble with your deployment? -* :doc:`Additional server installation guides ` - Additional deployment guides and an open source component list you can reference for every release. \ No newline at end of file diff --git a/source/guides/desktop-mobile-app-deployment.rst b/source/guides/desktop-mobile-app-deployment.rst deleted file mode 100644 index 1bffd1f1fa1..00000000000 --- a/source/guides/desktop-mobile-app-deployment.rst +++ /dev/null @@ -1,46 +0,0 @@ -Desktop and mobile app deployment -================================= - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Desktop app deployment guide - Desktop MSI installer and group policy installation guides (Beta) - Desktop App custom dictionaries - Desktop managed resources - Using Mattermost’s pre-built mobile apps - Testing push notifications - Deploy Mattermost mobile apps - Mobile push notifications - Building and distributing your own custom Mattermost mobile apps - Deploying mobile apps using an EMM provider - AppConfig for EMM solutions with Mattermost Mobile Apps - Mobile VPN options - Mobile apps FAQ - Client-side data storage FAQ - -Customize the Mattermost desktop and mobile apps to meet any deployment needs. - -Desktop app ------------- - -* :doc:`Desktop app deployment guide ` - Customize and distribute the Mattermost desktop app with pre-configured settings. -* :doc:`Desktop MSI installer and group policy installation guides (Beta) ` - Use the Mattermost MSI installer and Group Policy definitions for Windows deployment. -* :doc:`Desktop app custom dictionaries ` - Create custom dictionaries for Mattermost spellcheck. -* :doc:`Desktop managed resources ` - Configure resource management for services running on the same domain as your Mattermost instance. - -Mobile apps ------------ - -* :doc:`Using Mattermost’s pre-built mobile apps ` - Connect users to your Mattermost server with our prebuilt apps for Android and iOS. -* :doc:`Testing push notifications ` - Learn how to test mobile push notifications. -* :doc:`Deploy Mattermost mobile apps ` - Learn the basics of how to customize and deploy Mattermost to the Enterprise. -* :doc:`Mobile push notifications ` - Set up mobile push notifications. -* :doc:`Building and distributing your own custom Mattermost mobile apps ` - Build custom mobile Mattermost apps. -* :doc:`Deploying mobile apps using an EMM provider ` - Deploy with Enterprise Mobile Management software to enforce security policies and enforce specific versions of the Mattermost mobile apps. -* :doc:`AppConfig for EMM solutions with Mattermost mobile apps ` - Learn how AppConfig provides an easy way to configure enterprise mobile applications. -* :doc:`Mobile VPN options ` - Learn how to use the Mattermost mobile apps with Mobile VPNs. -* :doc:`Mobile apps frequently asked questions ` -* :doc:`Client-side data storage frequently asked questions ` \ No newline at end of file diff --git a/source/guides/get-started-with-administration.rst b/source/guides/get-started-with-administration.rst deleted file mode 100644 index bc687ad7514..00000000000 --- a/source/guides/get-started-with-administration.rst +++ /dev/null @@ -1,95 +0,0 @@ -Get started with administration -================================ - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Mattermost feature labels - Optimize your workspace - Mattermost configuration settings - Self-hosted edition and license - Cloud subscription, billing, and account - Reporting configuration settings - User management configuration settings - Environment configuration settings - Site configuration settings - Authentication configuration settings - Plugins configuration settings - Enable Copilot - Product limits - Manage user surveys - Integrations configuration settings - Compliance configuration settings - Experimental configuration settings - Deprecated configuration settings - Environment variables - Provisioning workflows - Active Directory/LDAP - GitLab SSO - OpenID SSO - Google SSO - Entra ID SSO - Advanced permissions - Manage team and channel members - Custom branding tools - Notify Admin - -These resources will help you get started with your Mattermost self-hosted or Cloud workspace. - -.. tip:: - - As a system admin, access the System Console by selecting the **Product** |product-list| menu and selecting **System Console**. - -* **Mattermost feature labels** - Learn what :doc:`Mattermost feature labels `, including :ref:`Experimental `, :ref:`Beta `, :ref:`General Availability `, and :ref:`Deprecated ` mean to the status, maturity, and support level of Mattermost product features and functionality in your Mattermost deployment. -* **Optimize your workspace** - Review health and growth scores for your Mattermost workspace, and take necessary action using the :doc:`workspace optimization ` page in the System Console. -* **Configure your workspace** - Mattermost offers extensive configuration options for both :doc:`self-hosted Mattermost servers and Mattermost Cloud workspaces `, and provides a list of :doc:`deprecated configuration settings ` no longer supported. -* **Enable Copilot** - Learn how to :doc:`enable Copilot in Mattermost ` -* **Product Limits** - Learn about Mattermost :doc:`product limits `. -* **Manage user surveys** - Learn how to :doc:`create, manage, and export data from user surveys ` in your self-hosted Mattermost deployment. -* **Environment variables** - Learn how to use :doc:`environment variables ` to manage configuration for a self-hosted deployment. -* **Provisioning workflows** - Learn how to :doc:`provision ` and de-provision user accounts. -* **User authentication** - All versions of Mattermost provide basic authentication and offer :doc:`multi-factor authentication ` out of the box. Enterprise and Professional versions of Mattermost also include :doc:`Active Directory/LDAP ` and SSO for :doc:`GitLab SSO `, :doc:`OpenID `, :doc:`Google `, and :doc:`Entra ID `. -* **User permissions** - All versions of Mattermost offer standard user permissions control. Enterprise and Professional versions also include :doc:`advanced permissions control ` to customize which users can perform specific actions. -* **Manage team and channel members** - :doc:`Manage team and channel members ` synchronization, moderation, and membership settings. -* **Customize branding** - Change Mattermost branding, site name, and description with :doc:`custom branding tools `. -* **Notify admin** - Keep track of your users' :doc:`feature requirement needs `. - -Advanced user management -------------------------- - -.. toctree:: - :maxdepth: 1 - :hidden: - - Use AD/LDAP synchronized groups to manage team or private channel membership - Guest accounts - SAML Single Sign-On - SAML Single-Sign-On: technical documentation - -* :doc:`Use AD/LDAP synchronized groups to manage team or private channel membership ` - Synchronize your AD/LDAP group with private Mattermost channels and teams. -* :doc:`Guest accounts ` - Create guest accounts to collaborate with individuals outside your organization. -* :doc:`SAML Single Sign-On ` - Configure Mattermost to be a SAML 2.0 service provider. -* :doc:`SAML Single Sign-On: technical documentation ` - SAML 2.0 reference documentation for Mattermost. - -Advanced workspace management ------------------------------ - -.. toctree:: - :maxdepth: 1 - :hidden: - - Connected workspaces - Statistics - In-product notices - User satisfaction surveys - System-wide notifications - Bulk export tool - -* :doc:`Connected workspaces ` - Connect channels from multiple Mattermost servers in a federated architecture. -* :doc:`Statistics ` - Get statistics about your Mattermost server usage. -* :doc:`In-product notices ` - Get notified about Mattermost updates via in-app notices. -* :doc:`User satisfaction surveys ` - Learn about Mattermost user satisfaction surveys and how to configure their operation. -* :doc:`System-wide notifications ` - Display system-wide notifications to all users across all teams. -* :doc:`Bulk export tool ` - Export user, team, channel, and post data from Mattermost. diff --git a/source/guides/other-administration-resources.rst b/source/guides/other-administration-resources.rst deleted file mode 100644 index 1d7188bdc69..00000000000 --- a/source/guides/other-administration-resources.rst +++ /dev/null @@ -1,25 +0,0 @@ -Other administration resources -============================== - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Convert OAuth 2.0 providers to OpenID Connect - Generate a support packet - mmctl command line tool - Migration announcement email template - Advanced permissions infrastructure - Command line tools - Code Signing Custom Builds - -If the information above doesn’t solve your problem, look at these other resources to find something that meets your needs. Alternatively, you can also :doc:`get help ` from our community or via premium support services. - -* :doc:`Convert OAuth 2.0 service providers to OpenID Connect ` - Migrate from OAuth 2.0 to OpenID Connect. -* :doc:`Generate a support packet ` - Generate configuration information, logs, plugin details, and data dependencies to provide when contacting Mattermost support. -* :doc:`mmctl command line tool ` - Use mmctl to manage self-hosted Mattermost servers from the command line. -* :doc:`Migration announcement email template ` - Use this email template to notify your users about migrating to Mattermost. -* :doc:`Advanced permissions: backend infrastructure ` - Read our technical guide on modifying self-hosted Mattermost installations to create custom permissions schemes. -* :doc:`Command line tools ` - Learn how to use the command line to manage self-hosted Mattermost servers. -* :doc:`Code signing custom builds ` - Learn how to reduce security warnings from operating systems and ensure smoother, more trustworthy installations with Code Signing. \ No newline at end of file diff --git a/source/guides/prepare-for-your-mattermost-deployment.rst b/source/guides/prepare-for-your-mattermost-deployment.rst deleted file mode 100644 index 1ddc7bf18e3..00000000000 --- a/source/guides/prepare-for-your-mattermost-deployment.rst +++ /dev/null @@ -1,24 +0,0 @@ -Prepare for your Mattermost deployment -======================================= - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Software and hardware requirements - Administrator tasks - Architecture overview - Plan your Mattermost implementation - Enterprise roll out checklist - Welcome email template - -These guides will help you prepare for your Mattermost deployment. - -* :doc:`Migrate from MySQL to PostgreSQL ` - Learn how to migrate from MySQL to PostgreSQL. -* :doc:`Software and hardware requirements ` - Confirm software and hardware requirements for your Mattermost deployment. -* :doc:`Administrator tasks ` - Learn about the standard configurations and settings you’ll encounter. -* :doc:`Architecture overview ` - Learn the basics of user authentication, notifications, data management services, network connectivity, and high availability. -* :doc:`Plan your Mattermost implementation ` - Get a detailed breakdown of the technical requirements to deploy Mattermost for your team or organization. -* :doc:`Enterprise roll out checklist ` - Learn how to roll Mattermost out to thousands of users. -* :doc:`Welcome email template ` - Use our sample email template when you’re ready to invite users to your server. \ No newline at end of file diff --git a/source/guides/scale-mattermost.rst b/source/guides/scale-mattermost.rst index 337cc851f40..4ec38f59ee7 100644 --- a/source/guides/scale-mattermost.rst +++ b/source/guides/scale-mattermost.rst @@ -2,7 +2,7 @@ Scale Mattermost ================ .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :hidden: :titlesonly: @@ -16,14 +16,6 @@ Scale Mattermost Scale up to 90000 users Scale up to 100000 users Scale up to 200000 users - High availability cluster-based deployment - Elasticsearch - Collect performance metrics - Deploy Prometheus and Grafana for performance monitoring - Performance monitoring metrics - Push notification health targets - Mattermost performance alerting guide - Ensuring releases perform at scale Scale and monitor your Mattermost deployment. @@ -37,13 +29,4 @@ Scale and monitor your Mattermost deployment. * :doc:`Scale up to 80000 users ` - Learn how to scale Mattermost to up to 80000 users. * :doc:`Scale up to 90000 users ` - Learn how to scale Mattermost to up to 90000 users. * :doc:`Scale up to 100000 users ` - Learn how to scale Mattermost to up to 100000 users. - * :doc:`Scale up to 200000 users ` - Learn how to scale Mattermost to up to 200000 users. - -* :doc:`High availability cluster-based deployment ` - Learn how to run Mattermost at scale with all the config tweaks needed. -* :doc:`Elasticsearch ` - Enhance search performance with Elasticsearch. -* :doc:`Collect performance metrics ` - Learn how to collect performance metrics without deploying Prometheus. -* :doc:`Deploy Prometheus and Grafana for performance monitoring ` - Use Prometheus and Grafana to monitor the health and performance of your Mattermost cluster. -* :doc:`Performance monitoring metrics ` - The custom and standard Go metrics available for monitoring system performance. -* :doc:`Push notification health targets ` - Learn the push notification thresholds to maintain to ensure a performant production deployment of Mattermost. -* :doc:`Mattermost performance alerting guide ` - Learn strategies and best practices for monitoring your Mattermost cluster. -* :doc:`Ensuring releases perform at scale ` - Learn how Mattermost ensures new releases perform at scale. + * :doc:`Scale up to 200000 users ` - Learn how to scale Mattermost to up to 200000 users. \ No newline at end of file diff --git a/source/guides/secure-mattermost.rst b/source/guides/secure-mattermost.rst index d2301d2913c..251e1f9572b 100644 --- a/source/guides/secure-mattermost.rst +++ b/source/guides/secure-mattermost.rst @@ -8,22 +8,26 @@ Mattermost ships with several security features that can help organizations safe :hidden: :titlesonly: - Encryption options + Encryption options + Transport encryption Multi-factor authentication Delegated granular administration Custom terms of service User and group provisioning via AD/LDAP SAML-based SSO + SAML SSO techical documentation Certificate-based authentication * :doc:`Encryption options ` - Setup encryption for data in transit and at rest. +* :doc:`Transport encryption ` - Secure data in transit between Mattermost and other services. * :doc:`Multi-factor authentication ` - Require users to provide a secure one-time code in addition to their username and password to log in to Mattermost. -* :ref:`ID-only push notifications ` - Enable fully private mobile notifications to protect against iOS and Android notification infrastructure breaches. -* :doc:`Enterprise mobility management ` - Secure mobile endpoints with management application configuration. +* :ref:`ID-only push notifications ` - Enable fully private mobile notifications to protect against iOS and Android notification infrastructure breaches. +* :doc:`Enterprise mobility management ` - Secure mobile endpoints with management application configuration. * :doc:`Delegated granular administration ` - Grant user access to specific areas of the Mattermost System Console. * :doc:`Custom terms of service ` - Increase clarity on legal Mattermost expectations for internal employees and guests. * :ref:`Manage session length ` - Control how long user sessions remain active. * :doc:`User and group provisioning via AD/LDAP ` - Provision and synchronize users and groups to pre-defined roles. * :doc:`SAML-based single sign-on (SSO) ` - Enable login using a single user ID and password managed through a SAML 2.0 Service Provider. +* :doc:`SAML SSO technical documentation ` - Technical details on SAML SSO. * :doc:`Certificate-based authentication ` - Identify a user or a device before granting access to Mattermost. * :ref:`Manage file sharing and downloads ` - Control file sharing and downloads in Mattermost. \ No newline at end of file diff --git a/source/guides/self-hosted-administration.rst b/source/guides/self-hosted-administration.rst deleted file mode 100644 index 539d1d99a80..00000000000 --- a/source/guides/self-hosted-administration.rst +++ /dev/null @@ -1,51 +0,0 @@ -Self-hosted administration -========================== - -This section of the guide is for system admins of self-hosted Mattermost servers. - -.. tip:: - - If you're the system admin for a Mattermost Cloud workspace, see the :doc:`Cloud workspace management ` documentation. - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Mattermost self-hosted billing - Mattermost error codes - Request a server Health Check - Store configuration in your database - Bulk loading data - SMTP email setup - Email templates - Calls deployment - Configure CloudFront to host static assets - Use an outbound proxy - Migration guide - Migrate from Slack - Chinese, Japanese, and Korean search - Customize Mattermost - JSON audit log schema - SSL client certificate setup - Manage telemetry - Configure health check probes - -* :doc:`Mattermost self-hosted billing ` - Manage your Mattermost subscription. -* :doc:`Mattermost error codes ` - Learn more about the error code you're encountering in Mattermost. -* :doc:`Request a server Health Check ` - Learn how to request a detailed analysis of your current system health, actionable recommendations to enhance performance, reliability, and security, and guidance on best practices for future system maintenance as an Enterprise customer. -* :doc:`Store configuration in your Mattermost database ` - Store Mattermost configuration information in your database rather than as a JSON file. We recommend this for High Availability environments. -* :doc:`Bulk loading data ` - Import bulk data into Mattermost for teams, channels, users, post content, and more. -* :doc:`SMTP email setup ` - Connect to an email server to send emails for password resets and system notifications. -* :doc:`Email templates ` - Alter the transactional emails Mattermost sends to your users. -* :doc:`Calls deployment ` - Learn about the different calls deployment types. -* :doc:`Configure CloudFront to host Mattermost static assets ` - Improve caching performance to reduce content load times. -* :doc:`Use an outbound proxy ` - Monitor outbound traffic and control the websites that can appear in embedded content. -* :doc:`Migration guide ` - Learn how to migrate from other chat services to Mattermost. -* :doc:`Migrate from Slack ` - Learn how to migrate from Slack to Mattermost. -* :doc:`Chinese, Japanese, and Korean search ` - Set up search capabilities for teams communicating via Chinese, Japanese, or Korean. -* :doc:`Whitelabel Mattermost ` - Whitelabel the Mattermost server and apps. -* :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. -* :doc:`SSL client certificate setup ` - Configure SSL client certificates for Mattermost Desktop and Web Apps. -* :doc:`Manage telemetry ` - Self-hosted system admins can opt out of sharing telemetry data with Mattermost. -* :doc:`Configure health check probes ` - Configure health check probes for your self-hosted Mattermost server. \ No newline at end of file diff --git a/source/guides/server-deployment.rst b/source/guides/server-deployment.rst deleted file mode 100644 index 0fdf268defe..00000000000 --- a/source/guides/server-deployment.rst +++ /dev/null @@ -1,23 +0,0 @@ -Server deployment -================== - -.. toctree:: - :maxdepth: 1 - :hidden: - :titlesonly: - - Deployment overview - Set up a socket-based Mattermost database - Image proxy - Backup and disaster recovery - Configure transport encryption - Bleve search - Trial Mattermost using Docker - -* :doc:`Deployment overview ` - Learn the basics of the Mattermost user experience, communication protocols, network access, data storage, and deployment options. -* :doc:`Set up a socket-based Mattermost database ` - Connect your Mattermost server to your database service. -* :doc:`Image proxy ` - Setup and configure an image proxy to make loading images faster and more reliable and prevent pixel tracking. -* :doc:`Backup and disaster recovery ` - Implement data backups, disaster recovery, and high availability deployment. -* :doc:`Configure transport encryption ` - Use transport encryption between Mattermost clusters and your proxy and database. -* :doc:`Bleve search ` - Use the Bleve search engine to provide Lucene-style full-text search. -* :doc:`Trial Mattermost using Docker ` - Learn how to evaluate Mattermost in a non-production environment using Docker. \ No newline at end of file diff --git a/source/guides/upgrade-mattermost.rst b/source/guides/upgrade-mattermost.rst index 86b43bc3c83..0ba12956fbe 100644 --- a/source/guides/upgrade-mattermost.rst +++ b/source/guides/upgrade-mattermost.rst @@ -1,9 +1,6 @@ Upgrade Mattermost ================== -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - .. toctree:: :maxdepth: 1 :hidden: @@ -13,16 +10,22 @@ Upgrade Mattermost Prepare to upgrade Mattermost Communicate scheduled maintenance best practices Upgrade Mattermost Server - Enterprise install and upgrade - Install a license key + Enterprise install and upgrade + Administrator onboarding tasks + Enterprise roll-out-checklist + Welcome email to end users Downgrade Mattermost Server + Open source components Stay up to date with the latest features and improvements. +* :doc:`Important upgrade notes ` - Find version-specific upgrade considerations. * :doc:`Prepare to upgrade Mattermost ` - Learn how to prepare for a Mattermost upgrade. * :doc:`Communicate scheduled mainenance best practices ` - 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. -* :doc:`Important upgrade notes ` - Find version-specific upgrade considerations. +* :doc:`Enterprise install and upgrade ` - Learn how to upgrade your Mattermost server to premium versions. +* :doc:`Administrator onboarding tasks ` - Learn about the onboarding tasks for administrators after an upgrade. +* :doc:`Enterprise roll-out-checklist ` - Learn about the roll-out checklist for enterprise users. +* :doc:`Welcome email to end users ` - Learn how to send a welcome email to end users after an upgrade. * :doc:`Downgrade Mattermost Server ` - Find out how to roll back to older versions of Mattermost. +* :doc:`Open source components ` - Find out about the open source components used in Mattermost. \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index d31c8a8b41e..3b9af9683ab 100644 --- a/source/index.rst +++ b/source/index.rst @@ -16,9 +16,9 @@ Mattermost product documentation :glob: About Mattermost - Deploy Mattermost - Manage Mattermost - Use Mattermost + User Guide + Deployment Guide + Administration Guide Integrate and extend Develop with Mattermost Get help with Mattermost diff --git a/source/install/cluster-transport-encryption.rst b/source/install/cluster-transport-encryption.rst deleted file mode 100644 index 45dc3658933..00000000000 --- a/source/install/cluster-transport-encryption.rst +++ /dev/null @@ -1,223 +0,0 @@ -Configuring cluster transport encryption -======================================== - -.. include:: ../_static/badges/ent-selfhosted.rst - :start-after: :nosearch: - -Mattermost is able to encrypt the messages sent within the cluster of a deployment using SSH tunneling. The guide walks through the deployment of this solution on Ubuntu 20.04, but it can be adapted for any Linux operating system. - -While this document only describes the configuration of a three-node cluster, it is by no means limited to that number. - -Prerequisites -------------- - -- SSH port whitelisted between each node of the deployment. -- Active ufw/iptables on each node. -- Access to the root/sudo user of each node for configuration. -- A configured Mattermost cluster. -- Mattermost running with a dedicated service user. -- Mattermost service is stopped on each cluster node. - -.. note:: - Support on the application level is currently in development and, when available, will deprecate this document. - -Example environment -------------------- - -In this scenario there are three application nodes in our environment with the following hostname/IP mapping: - -- **transport-encryption-mattermost1:** 10.10.250.146 -- **transport-encryption-mattermost2:** 10.10.250.231 -- **transport-encryption-mattermost3:** 10.10.250.165 - -Preparations ------------- - -- Connect to each Mattermost server with a sudo or root user. -- Make a note of the IP from each cluster member used for the internal communication. -- Ensure ``AllowTcpForwarding`` is enabled in ``/etc/ssh/sshd_config`` of each cluster node. - -SSH authentication ------------------- - -On each node, generate a SSH key-pair for the service account. In our scenario this is called ``mattermost``: - -.. code-block:: sh - - sudo -u mattermost ssh-keygen -t rsa - -.. code-block:: text - - Generating public/private rsa key pair. - Enter file in which to save the key (/home/mattermost/.ssh/id_rsa): - Enter passphrase (empty for no passphrase): - Enter same passphrase again: - Your identification has been saved in /home/mattermost/.ssh/id_rsa. - Your public key has been saved in /home/mattermost/.ssh/id_rsa.pub. - The key fingerprint is: - SHA256:redacted mattermost@transport-encryption-mattermost1 - - -The location of the SSH key itself is irrelevant if company policies require the usage of another storage location. - -Next, ensure that the SSH public key of each node is added to the ``authorized_keys`` file of the other nodes of the cluster. To do so, copy the contents of ``/home/mattermost/.ssh/id_rsa.pub`` of nodes 2 and 3, and add it to ``/home/mattermost/.ssh/authorized_keys`` of node 1. - -Repeat this step for each node of the cluster. As a result, each node should be able to establish an SSH connection to the other nodes of the cluster. - -.. note:: - - This service account can be separate from the service account already used for the Mattermost ``systemd`` service itself. It's important that this service account is allowed to create a SSH tunnel with port forwarding, but it doesn't require any additional permissions. - -ufw configuration ------------------ - -As a next step, allow SSH access from each of the other member nodes, e.g.: - -- mattermost1 allows from mattermost2 and mattermost3 -- mattermost2 allows from mattermost1 and mattermost3 -- mattermost3 allows from mattermost1 and mattermost2 - -To do so, we add an exception in the firewall. The commands for ``mattermost1`` look as follows: - -.. code-block:: sh - - sudo ufw allow from 10.10.250.231/32 to any port ssh - sudo ufw allow from 10.10.250.165/32 to any port ssh - sudo ufw status - -.. code-block:: text - - Rule added - Rule added - Status: active - - To Action From - -- ------ ---- - 22/tcp ALLOW 10.10.250.10 - 8065/tcp ALLOW Anywhere - 22/tcp ALLOW 10.10.250.231 - 22/tcp ALLOW 10.10.250.165 - - -Repeat the same steps on the other nodes, replacing the IPs with the ones from the other member nodes. Do so for each member node, excluding the node itself. - -Next, open ``/etc/ufw/after.rules`` and add the following block to the bottom of the file: - -.. code-block:: text - - *nat - :POSTROUTING ACCEPT [0:0] - :PREROUTING ACCEPT [0:0] - - -A OUTPUT -p tcp -d 10.10.250.231 --dport 8075 -j DNAT --to-destination 127.0.0.1:18075 - -A OUTPUT -p tcp -d 10.10.250.231 --dport 8074 -j DNAT --to-destination 127.0.0.1:18074 - -A OUTPUT -p tcp -d 10.10.250.165 --dport 8075 -j DNAT --to-destination 127.0.0.1:28075 - -A OUTPUT -p tcp -d 10.10.250.165 --dport 8074 -j DNAT --to-destination 127.0.0.1:28074 - - COMMIT - - -Two lines always belong to a single node, so in a deployment with four nodes: - -.. code-block:: text - - -A OUTPUT -p tcp -d ip_node_2 --dport 8075 -j DNAT --to-destination 127.0.0.1:18075 - -A OUTPUT -p tcp -d ip_node_2 --dport 8074 -j DNAT --to-destination 127.0.0.1:18074 - -A OUTPUT -p tcp -d ip_node_3 --dport 8075 -j DNAT --to-destination 127.0.0.1:28075 - -A OUTPUT -p tcp -d ip_node_3 --dport 8074 -j DNAT --to-destination 127.0.0.1:28074 - -A OUTPUT -p tcp -d ip_node_4 --dport 8075 -j DNAT --to-destination 127.0.0.1:38075 - -A OUTPUT -p tcp -d ip_node_4 --dport 8074 -j DNAT --to-destination 127.0.0.1:38074 - -Please be aware that the ports on the right side must be unique, so if you have a cluster of six nodes, use 8075 and 8074 with 1 to 5 in front of it. If the cluster is of bigger size, additional ports must be used. - -Ensure that your operating system has IP forwarding enabled using the following command: - -.. code-block:: sh - - sysctl -w net.ipv4.ip_forward=1 - -After that, reload the ufw rules and confirm that the iptable rules were successfully created: - -.. code-block:: sh - - iptables -t nat -L - -.. code-block:: text - - Chain PREROUTING (policy ACCEPT) - target prot opt source destination - - Chain INPUT (policy ACCEPT) - target prot opt source destination - - Chain OUTPUT (policy ACCEPT) - target prot opt source destination - DNAT tcp -- anywhere 10.10.250.231 tcp dpt:8075 to:127.0.0.1:18075 - DNAT tcp -- anywhere 10.10.250.231 tcp dpt:8074 to:127.0.0.1:18074 - DNAT tcp -- anywhere 10.10.250.165 tcp dpt:8075 to:127.0.0.1:28075 - DNAT tcp -- anywhere 10.10.250.165 tcp dpt:8074 to:127.0.0.1:28074 - -Repeat those steps for every node on the cluster. At the end of this section the following should be configured: - -- SSH access enabled in firewall from each cluster node to another. -- Per node 2 iptables rules for port 8074 and 8075. -- IP forwarding enabled. - -SSH configuration ------------------ - -As a next step, ensure that the SSH tunnels are created as part of the Mattermost service start. To do so, create a file called ``pre_start.sh`` in ``/opt/mattermost/bin`` on ``mattermost1``: - -.. code-block:: sh - - #!/bin/bash - ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 18075:10.10.250.231:8075 10.10.250.231 || true - ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 18074:10.10.250.231:8074 10.10.250.231 || true - ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 28075:10.10.250.165:8075 10.10.250.165 || true - ssh -N -f -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -L 28074:10.10.250.165:8074 10.10.250.165 || true - -.. note:: - - - We're ignoring the error from the SSH connection itself in case a tunnel is already active. Otherwise the Mattermost server would fail to start. - - Please make sure to back up this script in case of a version upgrade. - -Afterwards, set the executable bit on the shell script: - -.. code-block:: sh - - chmod +x /opt/mattermost/bin/pre_start.sh - -Open the systemd unit file of Mattermost and search for ``Type=Notify``. After this, enter a ``ExecStartPre`` script that will be executed before Mattermost itself is started: - -.. code-block:: text - - [Service] - Type=notify - ExecStartPre=/opt/mattermost/bin/pre_start.sh - -Reload the systemd daemon afterwards: - -.. code-block:: sh - - systemctl daemon-reload - -Repeat the same steps on each of the member nodes and adapt the node IPs and amount of entries for your environment. - -Cluster start -------------- - -Once each node is configured, restart the service on each cluster and confirm that it's running using the command below: - -.. code-block:: sh - - systemctl start mattermost - systemctl status mattermost.service - -.. code-block:: text - - ● mattermost.service - Mattermost - Loaded: loaded (/lib/systemd/system/mattermost.service; static; vendor preset: enabled) - Active: active (running) since Fri 2019-10-04 19:44:20 UTC; 5min ago - Process: 16734 ExecStartPre=/opt/mattermost/bin/pre_start.sh (code=exited, status=0/SUCCESS) - -Next, open the Mattermost System Console and confirm that each node is reporting successfully in the High Availability section. diff --git a/source/install/common-configure-support-email.rst b/source/install/common-configure-support-email.rst deleted file mode 100644 index a0903299c96..00000000000 --- a/source/install/common-configure-support-email.rst +++ /dev/null @@ -1,5 +0,0 @@ -:orphan: -:nosearch: - -.. note:: - We recommend configuring the `Support Email `_ under ``SupportSettings``, set ``"SupportEmail"``. This is the email address your users will contact when they need help. diff --git a/source/install/common-default-config-changes.rst b/source/install/common-default-config-changes.rst deleted file mode 100644 index 4701bdd49cd..00000000000 --- a/source/install/common-default-config-changes.rst +++ /dev/null @@ -1,8 +0,0 @@ -:orphan: -:nosearch: - -Configure the following properties in this file: - -* Under ``SqlSettings``, set ``DriverName`` to ``"postgres"``. This is the default and recommended database for all Mattermost installations. -* Under ``SqlSettings``, set ``DataSource`` to ``"postgres://mmuser:@:5432/mattermost?sslmode=disable&connect_timeout=10"`` replacing ``mmuser``, ````, ```` and ``mattermost`` with your database name. -* Under ``ServiceSettings``, set ``"SiteURL"``: The domain name for the Mattermost application (e.g. ``https://mattermost.example.com``). \ No newline at end of file diff --git a/source/install/common-deploy-faq.rst b/source/install/common-deploy-faq.rst deleted file mode 100644 index ff8fdaba9de..00000000000 --- a/source/install/common-deploy-faq.rst +++ /dev/null @@ -1,37 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Why doesn't Mattermost start at system boot? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To have the Mattermost Server start at system boot, the systemd unit file needs to be enabled. Run the following command: - -.. code-block:: sh - - sudo systemctl enable mattermost.service - -Why does Mattermost fail to start at system boot? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If your database is on the same system as your Mattermost Server, we recommend editing the default ``/lib/systemd/system/mattermost.service`` systemd unit file to add ``After=postgresql.service`` and ``BindsTo=postgresql.service`` to the ``[Unit]`` section. - -Can I run Mattermost without a proxy? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes. Mattermost binds to 443 instead of 8065. The Mattermost binary requires the correct permissions to do that binding. You must activate the ``CAP_NET_BIND_SERVICE`` capability to allow the new Mattermost binary to bind to ports lower than 1024 by running the following command: - -.. code-block:: sh - - sudo setcap cap_net_bind_service=+ep ./mattermost/bin/mattermost - -.. note:: - - We highly recommend using a proxy in front of Mattermost server for up to 200 concurrent users. If you have fewer than 200 concurrent users, you can :doc:`set up TLS `. If you're exceeding 200 concurrent users, you'll need :doc:`a proxy `, such as NGINX, in front of Mattermost to manage the traffic. - -Where can I access Mattermost Server logs? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mattermost Server logs are located in the ``logs`` directory of wherever you installed Mattermost. By default, this is ``/opt/mattermost/logs``, inside the ``mattermost.log`` file. - diff --git a/source/install/common-gpg-public-key-changed.rst b/source/install/common-gpg-public-key-changed.rst deleted file mode 100644 index d51ab96fbf0..00000000000 --- a/source/install/common-gpg-public-key-changed.rst +++ /dev/null @@ -1,18 +0,0 @@ -:orphan: -:nosearch: - -.. important:: - - The GPG public key has changed. You can `import the new public key `_ or run the automatic Mattermost PPA repository setup script provided below. Depending on your setup, additional steps may also be required, particularly for installations that didn't rely on the repository setup script. We recommend deleting the old key from ``/etc/apt/trusted.gpg.d`` before adding the apt repository. - - - For Ubuntu Focal - 20.04 LTS: - - ``sudo apt-key del A1B31D46F0F3A10B02CF2D44F8F2C31744774B28`` - - ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo apt-key add`` - - - For Ubuntu Jammy - 22.04 LTS and Ubuntu Noble - 24.04 LTS: - - ``sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg`` - - ``curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg | gpg --dearmor | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null`` \ No newline at end of file diff --git a/source/install/common-omnibus-tip.rst b/source/install/common-omnibus-tip.rst deleted file mode 100644 index 479b748de9d..00000000000 --- a/source/install/common-omnibus-tip.rst +++ /dev/null @@ -1,7 +0,0 @@ -:orphan: -:nosearch: - -.. tip:: - - If you are running the Mattermost Server and database on a single system, we recommend the :doc:`Mattermost Omnibus install method ` as this greatly reduces setup and ongoing maintenance. - diff --git a/source/install/common-postgres-database-important.rst b/source/install/common-postgres-database-important.rst deleted file mode 100644 index ebc40ee836a..00000000000 --- a/source/install/common-postgres-database-important.rst +++ /dev/null @@ -1,6 +0,0 @@ -:orphan: -:nosearch: - -.. important:: - - You need a PostgreSQL database. See the :doc:`database preparation ` documentation for details on this prerequisite. diff --git a/source/install/config-tls-mattermost.rst b/source/install/config-tls-mattermost.rst deleted file mode 100644 index 830730777bd..00000000000 --- a/source/install/config-tls-mattermost.rst +++ /dev/null @@ -1,74 +0,0 @@ -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Configure TLS on Mattermost server ------------------------------------ - -You have two options if you want users to connect with HTTPS: - -1. Set up TLS on Mattermost server. -2. Install a proxy such as NGINX and set up TLS on the proxy. - -The easiest option is to set up TLS on the Mattermost Server, but if you expect to have more than 200 users, use a proxy for better performance. A proxy server also provides standard HTTP request logs. - -.. note:: - - Your Mattermost server must be accessible from the Let's Encrypt CA in order to verify your domain name and issue the certificate. Be sure to open your firewall and configure any reverse proxies to forward traffic to ports 80 and 443. More information can be found `at Let's Encrypt `_. - -Configure TLS on the Mattermost server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -1. In **System Console > Environment > Web Server** (or **System Console > General > Configuration** in versions prior to 5.12). - - a. Change the **Listen Address** setting to ``:443``. - b. Change the **Connection Security** setting to ``TLS``. - c. Change the **Forward port 80 to 443** setting to ``true``. - -2. Activate the ``CAP_NET_BIND_SERVICE`` capability to allow Mattermost to bind to low ports. - - .. code-block:: sh - - sudo setcap cap_net_bind_service=+ep /opt/mattermost/bin/mattermost - -3. Install the security certificate. You can use `Let's Encrypt `__ to automatically install and setup the certificate, or you can specify your own certificate. - -To use a Let's Encrypt certificate -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The certificate is retrieved the first time that a client tries to connect to the Mattermost server. Certificates are retrieved for any hostname a client tries to reach the server at. - - a. Change the **Use Let's Encrypt** setting to ``true``. - b. Restart the Mattermost server for these changes to take effect. - -.. note:: - - If Let's Encrypt is enabled, forward port 80 through a firewall, with :ref:`Forward80To443 ` ``config.json`` setting set to ``true`` to complete the Let's Encrypt certification. - -To use your own certificate -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -a. Change the **Use Let's Encrypt** setting to ``false``. -b. Change the **TLS Certificate File** setting to the location of the certificate file. -c. Change the **TLS Key File** setting to the location of the private key file. -d. Restart the Mattermost server for these changes to take effect. - -.. note:: - - Password-protected certificates are not supported. - -Use TLS on NGINX (as a proxy) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - Do not set up TLS on Mattermost before doing so for NGINX. It breaks the connection as the TLS prevents it from successfully communicating with the Mattermost server. - -- NGINX will act as a forward proxy to encrypt the traffic between the client and Mattermost server. After installing the SSL certificate, the incoming traffic will be handled via NGINX on port 443 exposed to the internet, proxy to the Mattermost server running on port 80. -- (Optional) Upstream encryption between NGINX to Mattermost server is allowed. -- Follow `NGINX's guide on setting up SSL Termination for TCP Upstream Servers `__. - -Other helpful resources: - -- `NGINX's SSL blog `_ -- `NGINX's SSL guide `_ diff --git a/source/install/database-transport-encryption.rst b/source/install/database-transport-encryption.rst deleted file mode 100644 index adabc38a273..00000000000 --- a/source/install/database-transport-encryption.rst +++ /dev/null @@ -1,121 +0,0 @@ -Configuring database transport encryption -========================================== - -.. include:: ../_static/badges/ent-selfhosted.rst - :start-after: :nosearch: - -Mattermost is able to encrypt the traffic between the database and the application using TLS. This guide describes the setup steps for a single, separate MySQL server. - -Prerequisites -------------- - -- Operational Mattermost server or cluster. -- Operational MySQL server. -- Confirmed connectivity between Mattermost and MySQL server. -- Authentication credentials for Mattermost user on MySQL server. - -Example environment -------------------- - -In this scenario there is one Mattermost application server and one MySQL server, both running Ubuntu 20.04, with the following IPs: - -- **transport-encryption-mattermost1:** 10.10.250.146 -- **transport-encryption-mysql1:** 10.10.250.148 - -Configuring MySQL ------------------ - -As a first step, connect to both servers with a sudo or root user. - -Execute the following command to prepare the server for SSL connections: - -.. code-block:: sh - - sudo mysql_ssl_rsa_setup --uid=mysql - -This generates self-signed certificates in ``/var/lib/mysql/`` that the MySQL server uses to encrypt the connection. If you would like to use certificates from your company CA, please follow the MySQL documentation for configuration steps. - -**Note:** Optionally, it can be enforced that all connections must be made via a local socket connection or TLS. To do this, open ``/etc/mysql/mysql.conf.d/mysqld.cnf`` and append the following line to the file: - -.. code-block:: text - - require_secure_transport = ON - -Any connection to the MySQL server must now be made with secure transport enabled. - -Last but not least, restart the server and confirm it is up and running: - - .. code-block:: sh - - systemctl restart mysql - systemctl status mysql - -.. code-block:: text - - ● mysql.service - MySQL Community Server - Loaded: loaded (/lib/systemd/system/mysql.service; enabled; vendor preset: enabled) - Active: active (running) since Fri 2019-10-18 16:41:25 UTC; 2s ago - Process: 8380 ExecStart=/usr/sbin/mysqld --daemonize --pid-file=/run/mysqld/mysqld.pid (code=exited, status=0/SUCCESS) - Process: 8360 ExecStartPre=/usr/share/mysql/mysql-systemd-start pre (code=exited, status=0/SUCCESS) - Main PID: 8382 (mysqld) - Tasks: 27 (limit: 2361) - CGroup: /system.slice/mysql.service - └─8382 /usr/sbin/mysqld --daemonize --pid-file=/run/mysqld/mysqld.pid - - Oct 18 16:41:25 transport-encryption-mysql1 systemd[1]: Stopped MySQL Community Server. - Oct 18 16:41:25 transport-encryption-mysql1 systemd[1]: Starting MySQL Community Server... - Oct 18 16:41:25 transport-encryption-mysql1 systemd[1]: Started MySQL Community Server. - -Configuring Mattermost ----------------------- - -On the Mattermost server, open the file ``config.json`` and look for the ``DataSource`` value in the ``SqlSettings`` section. It should look similar to this: - -.. code-block:: text - - "DataSource": "mmuser:sad09zusaopdhsad123@tcp(10.10.250.148:3306)/mattermost?charset=utf8mb4,utf8\u0026writeTimeout=30s", - -At the end of the line, we can configure that TLS must be turned on with the ``tls`` flag which supports the following values: - -- true (Require TLS + a trusted certificate) -- false -- skip-verify (Require TLS + accept self-signed) -- preferred (Try TLS, fallback to unencrypted) - -In our case we need to use ``skip-verify`` since we use a self-signed certificate. The configuration setting will now look like this: - -.. code-block:: text - - "DataSource": "mmuser:sad09zusaopdhsad123@tcp(10.10.250.148:3306)/mattermost?charset=utf8mb4,utf8\u0026writeTimeout=30s&tls=skip-verify", - -If you're running Mattermost in a cluster, be sure to update the value on each node of the cluster. If you are using configuration in the database, be sure to update the ``systemd`` unit file and enable TLS for the configuration store. - -Once complete, restart the Mattermost server and ensure the system is operational: - -.. code-block:: sh - - sudo systemctl restart mattermost - systemctl status mattermost - -.. code-block:: text - - ● mattermost.service - Mattermost - Loaded: loaded (/lib/systemd/system/mattermost.service; static; vendor preset: enabled) - Active: active (running) since Fri 2019-10-18 16:47:08 UTC; 3s ago - Process: 3424 ExecStartPre=/opt/mattermost/bin/pre_start.sh (code=exited, status=0/SUCCESS) - Main PID: 3443 (mattermost) - Tasks: 20 (limit: 2361) - CGroup: /system.slice/mattermost.service - ├─3443 /opt/mattermost/bin/mattermost --config=mysql://mmuser:sad09zusaopdhsad123@tcp(10.10.250.148:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s&tls=skip-verify - └─3459 plugins/com.mattermost.nps/server/dist/plugin-linux-amd64 - - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8637397,"caller":"scheduler/worker.go:36","msg":"Worker started","worker":"Plugins"} - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8639545,"caller":"jobs/jobs_watcher.go:38","msg":"Watcher Started"} - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"info","ts":1571417228.8641603,"caller":"jobs/schedulers.go:72","msg":"Starting schedulers."} - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8645394,"caller":"app/web_hub.go:436","msg":"Hub for index 0 is starting with goroutine 3923"} - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8648505,"caller":"app/web_hub.go:436","msg":"Hub for index 1 is starting with goroutine 3924"} - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.8656101,"caller":"web/static.go:31","msg":"Using client directory at /opt/mattermost/client"} - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"info","ts":1571417228.8681324,"caller":"commands/server.go:105","msg":"Sending systemd READY notification."} - Oct 18 16:47:08 transport-encryption-mattermost1 systemd[1]: Started Mattermost. - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.9003174,"caller":"jobs/schedulers.go:166","msg":"Next run time for scheduler","scheduler_name":"MigrationsSched - Oct 18 16:47:08 transport-encryption-mattermost1 mattermost[3443]: {"level":"debug","ts":1571417228.9025588,"caller":"jobs/schedulers.go:166","msg":"Next run time for scheduler","scheduler_name":"PluginsSchedule diff --git a/source/install/deploying-team-edition-on-bitnami.rst b/source/install/deploying-team-edition-on-bitnami.rst deleted file mode 100644 index 54ffcd44c59..00000000000 --- a/source/install/deploying-team-edition-on-bitnami.rst +++ /dev/null @@ -1,8 +0,0 @@ -Deploy Mattermost on Bitnami -============================= - -Deploy your Mattermost Team Edition server in the cloud with one simple click using one of several Bitnami cloud images. Deployment options include: - -- `Amazon Web Services `__ -- `Microsoft Azure `__ -- `Google Cloud Platform `__ diff --git a/source/install/download-latest-tarball.rst b/source/install/download-latest-tarball.rst deleted file mode 100644 index 37b61b8ef08..00000000000 --- a/source/install/download-latest-tarball.rst +++ /dev/null @@ -1,22 +0,0 @@ -:orphan: -:nosearch: - -In a terminal window, ssh onto the system that will host the Mattermost Server. - -Using ``wget``, download the Mattermost Server release you want to install. - -.. tab:: Latest release - - .. code-block:: sh - - wget https://releases.mattermost.com/10.6.1/mattermost-10.6.1-linux-amd64.tar.gz - -.. tab:: Current ESR - - .. code-block:: sh - - wget https://releases.mattermost.com/10.5.2/mattermost-10.5.2-linux-amd64.tar.gz - -.. tab:: Older releases - - If you are looking for an older release, Enterprise and Team Edition releases can be found in our :doc:`version archive ` documentation. diff --git a/source/install/install-kubernetes-aks.rst b/source/install/install-kubernetes-aks.rst deleted file mode 100644 index 0a1fc16a4a8..00000000000 --- a/source/install/install-kubernetes-aks.rst +++ /dev/null @@ -1,133 +0,0 @@ -Install Mattermost on Azure AKS -================================ - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -You can use a supported `Azure Marketplace Container Offer `__ to install Mattermost on your existing Azure infrastructure. - -.. important:: - - You are responsible for Azure costs associated with any infrastructure you spin up to host a Mattermost server, and Azure credits cannot be applied towards the purchase of a Mattermost license. - -Infrastructure pre-requisites ------------------------------ - -Deploying Mattermost on Azure AKS requires the following database and cluster prerequisites. - -PostgreSQL v13.0+ database -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mattermost requires a pre-existing PostgreSQL database within your infrastructure. We recommend using `Azure Database for PostgreSQL - Flexible Server `_. Deploy one by following `this Microsoft quick start guide `_. - -.. tip:: - We recommend using Private Access for your database. - -Running AKS cluster -~~~~~~~~~~~~~~~~~~~ - -Mattermost Azure Container Offer requires a pre-existing Kubernetes Cluster with an Ingress Controller pre-installed. We recommend creating a new AKS cluster with the `AGIC add-on enabled `_. - -Follow `this tutorial `_ to create a new AKS cluster with the add-on enabled. - -.. tip:: - - - Connectivity should be already in place between the AKS cluster and the PostgreSQL database. - - Any pre-installed Ingress Controller within the cluster that supports the Ingress Kubernetes resource and TLS termination should work out of the box. - -Deployment pre-requisites -------------------------- - -Deploying Mattermost on Azure AKS requires the following deployment prerequisites. - -Valid DNS name and TLS certificates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Mattermost relies on strong TLS certification in order to provide all the features to users. You need to have access to a DNS zone and be able to provide a valid TLS key and certificate for the Ingress Controller. - -Mattermost License and AKS Capacity -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: ../_static/badges/ent-only.rst - :start-after: :nosearch: - -If your deployment option is for more than ``100 users``, you must have more than 2 nodes on your AKS cluster to support High Availability, and you must provide a valid Mattermost License file. - -.. note:: - - Providing a license is optional at this stage. You can enable a **30 day** Mattermost trial once the server is deployed. - -Deploy Mattermost ------------------ - -1. Navigate to our `Azure Marketplace Container Offer `_ and get the offer. - - Alternatively, you can go to the ``Extensions + Applications`` section of your AKS cluster and install the Mattermost offering from there. Visit the `Microsoft cluster extensions documentation `_ to learn more. - -2. Choose the **Resource Group** and the **Region** of your installed AKS and PostgreSQL database. - - .. image:: ../_static/images/azure/basics.png - :alt: An example of the Azure AKS Project details screen. - -3. Choose your AKS cluster. - - .. image:: ../_static/images/azure/aks-cluster.png - :alt: An example of the Azure AKS cluster setup screen. - -4. Fill in the details for your PostgreSQL database. - - .. image:: ../_static/images/azure/postgreSQL.png - :alt: An example of the Azure AKS Database setup screen. - - .. note:: - - - Connectivity should be already in place between the AKS cluster and the database. - - Database should already exist and the user specified must have full access. - -5. Adjust deployment details. - - .. image:: ../_static/images/azure/deployment-details.png - :alt: An example of the Azure AKS Deployment Details setup screen. - -.. note:: - You can define a Deployment size to automatically adjust the installation. A valid Mattermost license is required for deployments of more than 100 users. - -6. Configure Mattermost installation hostname and Ingress details. The AGIC add-on is used in the following example to show the ingress annotations required. - - .. code-block:: yaml - - kubernetes.io/ingress.class: azure/application-gateway - appgw.ingress.kubernetes.io/ssl-redirect: "true" - -Upload yor own TLS certificates at this stage to take advantage of all Mattermost features. - - .. image:: ../_static/images/azure/networking-details.png - :alt: An example of the Azure AKS Networking Details setup screen. - -7. Ensure that everything is running. You should be able to check the installed plugin from the **AKS Extensions + Applications** page under the **Settings** menu. - - a. When the deployment is complete, obtain the hostname or IP address of your Mattermost deployment using the following command: - - .. code-block:: sh - - kubectl -n mattermost-operator get ingress - - b. Get the resulting IP address from the ``ADDRESS`` column, and use your domain registration service to create a DNS record. - c. You should be good to go. - -Learn more about managing your Mattermost server by visiting the :doc:`Managing Mattermost ` documentation. - -Upgrade Mattermost -------------------- - -1. Visit the ``Extensions + Applications`` section of your AKS cluster where your Mattermost installation is deployed. -2. You can enable minor version auto upgrades since these are not updating Mattermost version -3. Expand the ``Configurarion Settings`` table and add the below configuration and the version you want to install as a value. - - .. code:: - - global.azure.mattermost.version - - .. image:: ../images/global-azure-mattermost-version.png - :alt: An example of using custom Mattermost version. -4. Click ``Save`` and wait for the upgrade. \ No newline at end of file diff --git a/source/install/install-kubernetes.rst b/source/install/install-kubernetes.rst deleted file mode 100644 index 9da04b22ecf..00000000000 --- a/source/install/install-kubernetes.rst +++ /dev/null @@ -1,413 +0,0 @@ -Deploy Mattermost on Kubernetes -===================================== - -.. include::../_static/badges/allplans-selfhosted.rst - :start-after: - :nosearch: - -This document provides a guide to deploying Mattermost on Kubernetes using the Mattermost Kubernetes Operator. This guide will primarily focus on the recommended approach of using S3-compatible storage and a managed database service. If you choose to use self-managed components, you will need to adapt the instructions accordingly, pointing to your internal services instead. - -Intended outcome and deployment recommendations -------------------------------------------------- - -The goal of this documentation is to enable you to quickly and reliably deploy a production-ready Mattermost instance. While the operator supports a range of configurations, we strongly recommend using a cloud-native approach for production environments. - -While this guide focuses on using external, managed services for your database and file storage, the Mattermost Operator *does* offer the flexibility to use other solutions. For example, you could choose to deploy a PostgreSQL database within your Kubernetes cluster using the CloudNative PG operator (or externally however you wish), or use a self-hosted MinIO instance for object storage. - -While using managed cloud services is generally simpler to maintain and our recommended approach for production deployments, using self-managed services like MinIO for storage and CloudNative PG for PostgreSQL are also valid options if you have the expertise to manage them. - -Prerequisites -------------- - -Before you begin, ensure you have the following: - -* A functioning Kubernetes cluster (see the `Kubernetes setup guide `__). Your cluster should be running a `supported Kubernetes version `__. -* The `kubectl` command-line tool installed on your local machine (see the `kubectl installation guide `__). -* A fundamental understanding of Kubernetes concepts, such as deployments, pods, and applying manifests. -* Sufficient Kubernetes resources allocated based on your expected user load. Consult the `Mattermost Kubernetes Operator <#install-the-mattermost-operator>`__ documentation for resource requirements at different scales. - -.. tip:: - - * If you're new to Kubernetes or prefer a managed solution, consider using a service like `Amazon EKS `_, `Azure Kubernetes Service `_, `Google Kubernetes Engine `_, or `DigitalOcean Kubernetes `_. - * To customize your production deployment, refer to the :doc:`configuration settings documentation `. - * If you encounter issues during deployment, consult the :ref:`deployment troubleshooting guide `. - -Installation Steps ------------------- - -The installation process involves setting up the necessary operators and then deploying Mattermost itself. - -Install the Nginx Ingress Controller -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Follow the instructions in the `Kubernetes deployment documentation `_ to install the NGINX ingress controller on your Kubernetes cluster. Mattermost recommends installing the Nginx Operator via helm, regardless of platform you are installing to. - -Install the Mattermost Operator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Mattermost Kubernetes Operator can be installed using Helm. - -1. Install Helm (version 3.13.0 or later). See the `Helm quickstart documentation `_ for installation instructions. - -2. Add the Mattermost Helm repository: - - .. code-block:: sh - - helm repo add mattermost https://helm.mattermost.com - -3. Create a file named ``config.yaml`` and populate it with the contents of the `Mattermost operator values file `_. This file allows for customization of the operator. - -4. Create a namespace for the Mattermost Operator: - - .. code-block:: sh - - kubectl create ns mattermost-operator - -5. Install the Mattermost Operator: - - .. code-block:: sh - - helm install mattermost/mattermost-operator -n - - For example: - - .. code-block:: sh - - helm install mattermost-operator mattermost/mattermost-operator -n mattermost-operator - - To use your custom ``config.yaml`` file: - - .. code-block:: sh - - helm install mattermost-operator mattermost/mattermost-operator -n mattermost-operator -f config.yaml - -.. tip:: - - If you don't specify a version, the latest version of the Mattermost Operator will be installed. - -Deploy Mattermost ------------------ - -1. **(Mattermost Enterprise only)** Create a Mattermost license secret. Create a file named ``mattermost-license-secret.yaml`` with the following content, replacing ``[LICENSE_FILE_CONTENTS]`` with your actual license: - - .. code-block:: yaml - - apiVersion: v1 - kind: Secret - metadata: - name: my-mattermost-license - type: Opaque - stringData: - license: - -.. note:: - - A Mattermost Enterprise license is required for multi-server deployments. For single-server deployments without an Enterprise license, add ``Replicas: 1`` to the ``spec`` section in step 2. See the :doc:`high availability documentation ` for more on highly-available deployments. - -2. Create a Mattermost installation manifest file named ``mattermost-installation.yaml``. Use the following template, adjusting the values as needed: - - .. code-block:: yaml - - apiVersion: installation.mattermost.com/v1beta1 - kind: Mattermost - metadata: - name: # Example: mm-example-full - spec: - size: # Example: 5000users - ingress: - enabled: true - host: # Example: example.mattermost-example.com - annotations: - kubernetes.io/ingress.class: nginx - version: # Example: 9.3.0 - licenseSecret: "" # If you created a license secret, put the name here - -.. note:: - - File names in this guide are suggestions; you can use different names. - - - Key fields in the manifest include: - - * ``metadata.name``: The name of your Mattermost deployment in Kubernetes. - * ``spec.size``: The size of your installation (e.g., "100users", "1000users", etc.). - * ``spec.ingress.host``: The DNS name for your Mattermost installation. - * ``spec.version``: The Mattermost version. See the :doc:`server version archive ` for available versions. - * ``spec.licenseSecret``: The name of the Kubernetes secret containing your license (required for Enterprise). - - For a full list of configurable fields, see the `example manifest `_ and the `Custom Resource Definition `_. - -3. Create a file named ``mattermost-database-secret.yaml`` for database credentials. This secret must be in the same namespace as the Mattermost installation. - - .. code-block:: yaml - - apiVersion: v1 - data: - DB_CONNECTION_CHECK_URL: - DB_CONNECTION_STRING: - MM_SQLSETTINGS_DATASOURCEREPLICAS: - kind: Secret - metadata: - name: my-postgres-connection - type: Opaque - - - Example for AWS Aurora with PostgreSQL: - - .. code-block:: yaml - - apiVersion: v1 - data: - DB_CONNECTION_CHECK_URL: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK - DB_CONNECTION_STRING: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK - MM_SQLSETTINGS_DATASOURCEREPLICAS: cG9zdGdyZXM6Ly91c2VyOnN1cGVyX3NlY3JldF9wYXNzd29yZEBteS1kYXRhYmFzZS5jbHVzdGVyLXJvLWFiY2QudXMtZWFzdC0xLnJkcy5hbWF6b25hd3MuY29tOjU0MzIvbWF0dGVybW9zdD9jb25uZWN0X3RpbWVvdXQ9MTAK - kind: Secret - metadata: - name: my-postgres-connection - type: Opaque - -Create the Filestore Secret -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Create a file named ``mattermost-filestore-secret.yaml`` to store the credentials for your object storage service (e.g., AWS S3, MinIO). This secret must be created in the same namespace where you intend to install Mattermost. The file should contain the following YAML structure: - -.. code-block:: yaml - - apiVersion: v1 - kind: Secret - metadata: - name: # Choose a descriptive name (e.g., my-s3-credentials) - type: Opaque - data: - accesskey: - secretkey: - -.. csv-table:: - :header: "Key", "Description", "Required" - - "accesskey", "Base64-encoded access key for your storage service.", "Yes" - "secretkey", "Base64-encoded secret key for your storage service.", "Yes" - "metadata.name", "The name of the Kubernetes secret.", "Yes" - -.. important:: - - The ``accesskey`` and ``secretkey`` values must be **base64-encoded**. Do not enter the raw keys directly. Use a command-line tool or online encoder to generate the base64 strings. - -**Example (AWS S3):** - -.. code-block:: yaml - - apiVersion: v1 - kind: Secret - metadata: - name: my-s3-credentials - type: Opaque - data: - accesskey: QUNDRVNTX0tFWQo= # Example: Replace with your actual encoded key - secretkey: U1VQRVJfU0VDUkVUX0tFWQo= # Example: Replace with your actual encoded key - -Configure the Mattermost Installation Manifest -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Now, modify the ``mattermost-installation.yaml`` file (created in step 2) to connect Mattermost to your external database and object storage. - -.. tip:: - Refer to the supported fields in step 2 for guidance on where to add these configurations within the YAML structure. - -Connect to the Database -^^^^^^^^^^^^^^^^^^^^^^^ - -Add the following to the ``spec`` section of your manifest: - - .. code-block:: yaml - - spec: - database: - external: - secret: # The name of the database secret (e.g., my-postgres-connection) - -Connect to Object Storage -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Add the following to the ``spec`` section of your manifest: - - .. code-block:: yaml - - spec: - fileStore: - external: - url: # The URL of your storage service (e.g., s3.amazonaws.com) - bucket: # The name of your storage bucket - secret: # The name of the filestore secret (e.g., my-s3-credentials) - -S3-specific settings -^^^^^^^^^^^^^^^^^^^^^ - -If you are using Amazon S3, it's recommended to enable server-side encryption (SSE) and SSL. Add the following environment variables to the ``mattermostEnv`` section: - - .. code-block:: yaml - - spec: - mattermostEnv: - - name: MM_FILESETTINGS_AMAZONS3SSE - value: "true" - - name: MM_FILESETTINGS_AMAZONS3SSL - value: "true" - -**Example Manifest (Mattermost Enterprise, PostgreSQL, S3):** - - .. code-block:: yaml - - apiVersion: installation.mattermost.com/v1beta1 - kind: Mattermost - metadata: - name: mm-example-external-db - spec: - size: 5000users - ingress: - enabled: true - host: example.mattermost-example.com - annotations: - kubernetes.io/ingress.class: nginx - version: 9.3.0 - licenseSecret: my-mattermost-license - database: - external: - secret: my-postgres-connection - fileStore: - external: - url: s3.amazonaws.com - bucket: my-s3-bucket - secret: my-s3-iam-access-key # Or whatever you named your secret - mattermostEnv: - - name: MM_FILESETTINGS_AMAZONS3SSE - value: "true" - - name: MM_FILESETTINGS_AMAZONS3SSL - value: "true"... (Rest of the document continues as before) - -Apply the Installation Manifest -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -With the manifest files prepared, you can now deploy Mattermost to your Kubernetes cluster. Ensure you are connected to the correct cluster using `kubectl`. - -1. Create the Mattermost Namespace: - - .. code-block:: sh - - kubectl create ns mattermost - -2. Apply the License Secret (Mattermost Enterprise only): - - .. code-block:: sh - - kubectl apply -n mattermost -f # Replace with the actual path - -3. Apply the Mattermost Installation Manifest: - - .. code-block:: sh - - kubectl apply -n mattermost -f # Replace with the actual path - -**Monitor the Deployment:** - -You can track the deployment's progress using either the Kubernetes dashboard or the command line: - - .. code-block:: sh - - kubectl -n mattermost get mm -w - -The Mattermost installation is complete when the Custom Resource reaches the ``stable`` state. - -Access Mattermost -~~~~~~~~~~~~~~~~~ - -Once the deployment is complete, you can access your Mattermost instance. - -1. Get the Ingress Address: - - .. code-block:: sh - - kubectl -n mattermost get ingress - -2. Connect to Mattermost: Copy the address from the ``ADDRESS`` column of the ingress output. Open your web browser and navigate to this address. - -3. Configure DNS (Recommended): - -For production environments, configure your DNS to point your domain (specified in the `ingress.host` field of your manifest) to the ingress address obtained in the previous step. This is typically done through your domain registrar or cloud DNS provider (e.g., Route53 on AWS). - -4. Local Testing (Optional): If you are testing locally and haven't configured DNS, you can use port-forwarding to access Mattermost: - - .. code-block:: sh - - kubectl -n mattermost port-forward svc/ 8065:8065 # Replace with the name of your Mattermost service - - Then, navigate to ``http://localhost:8065`` in your browser. You can determine the service name by running: `kubectl get svc -n mattermost`. - -**Congratulations!** You have successfully deployed Mattermost on Kubernetes. - -Frequently asked questions --------------------------- - -What's the difference between the Mattermost Operator and Helm Charts? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Mattermost Operator is a self-contained set of application/product-specific instructions that runs inside Kubernetes and facilitates application -management and deployment. - -Helm is a tool used to deploy Kubernetes manifests to a cluster, but does not facilitate application management. - -We provide a `helm chart `__ that can be used to to install the Mattermost Operator. - -What database and filestore should I use for Mattermost? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Always refer to the Mattermost server documentation for what databases and filestores are supported. - -The following documentation on :doc:`scaling for enterprise ` is a good place to start. - -In Kubernetes, Mattermost recommends a cloud-native approach using managed services like Amazon RDS for PostgreSQL, Azure Database for PostgreSQL, or Google Cloud SQL for PostgreSQL for the database, and Amazon S3 or similar for file storage. For purely self-hosted solutions, you can use a PostgreSQL database (via CloudNative-PG operator) and MinIO for file storage. - -What are the Operator-Managed database and filestore options? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Mattermost Operator provides an option to directly provision a database and filestore for a Mattermost installation to use, -but this option **is not intended for production use** as these options rely on specific versions of third party operators not owned or maintained by Mattermost. -For production deployments of Mattermost, one of the other database and filestore configuration options should be chosen. - -Note that you can choose to manage your Mattermost database and filestore in Kubernetes with other operators, but these should -be provisioned separately first and then connected to the Mattermost installation as ``external`` backends. We do not recommend this method for users who aren't intimately familiar with Kubernetes. - -Can you use blue-green deployments with different database schemas? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Currently this is not supported as it introduces the possibility of missing a data entry in the database. - -Are environment variables supported? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Yes. However, ``config.json`` file settings will be overridden if the `$MM_SQLSETTINGS_DATASOURCE` environment variable is set. See the :doc:`Environment Variables ` configuration settings documentation for details. - -Issues configuring login with SAML on Kubernetes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For some SAML authentication configurations, ``502`` status code response can appear during login attempts due to requests being too large. -This can be caused by the default ``proxy-buffer-size`` setting for NGINX Ingress being too low. -To fix this issue, configure an appropriate buffer size (8k or 16k should be sufficient for most cases) with NGINX annotation by adding it to the Mattermost manifest under ``spec.ingressAnnotations``: - -.. code-block:: yaml - - ... - spec: - ... - ingress: - ... - annotations: - nginx.ingress.kubernetes.io/proxy-buffer-size: 16k - ... - -Use caution when changing the buffer size as it may slightly impact NGINX performance. Exact values are machine-dependent. - -Need help? ----------- - -If you run into challenges when using or transitioning to the Mattermost Operator for your Kubernetes deployment, `let us know `_. Your feedback helps us improve our tools and documentation for a better customer experience. \ No newline at end of file diff --git a/source/install/install-mattermost-server-tarball.rst b/source/install/install-mattermost-server-tarball.rst deleted file mode 100644 index 5cad3f76981..00000000000 --- a/source/install/install-mattermost-server-tarball.rst +++ /dev/null @@ -1,83 +0,0 @@ -:orphan: -:nosearch: - -Install the Mattermost Server by extracting the tarball, creating users and groups, and setting file/folder permissions. - -First extract the tarball: - -.. code-block:: sh - - tar -xvzf mattermost*.gz - -Now move the entire folder to the ``/opt`` directory (or whatever path you require): - -.. code-block:: sh - - sudo mv mattermost /opt - -.. note:: - - If you choose a custom path, ensure this alternate path is used in all steps that follow. - -By default the Mattermost Server uses ``/opt/mattermost/data`` as the folder for files. This can be changed in the System Console during setup (even using alternative storage such as S3). Create the default storage folder: - -.. code-block:: sh - - sudo mkdir /opt/mattermost/data - -Now set up a user and group called ``mattermost``: - -.. code-block:: sh - - sudo useradd --system --user-group mattermost - -.. note:: - - If you choose a custom user and group name, ensure it is used in all the steps that follow. - -Set the file and folder permissions for your installation: - -.. code-block:: sh - - sudo chown -R mattermost:mattermost /opt/mattermost - -Give the ``mattermost`` group write permissions to the application folder: - -.. code-block:: sh - - sudo chmod -R g+w /opt/mattermost - -You will now have the latest Mattermost Server version installed on your system. Starting and stopping the Mattermost Server is done using ``systemd``. Create the systemd unit file: - -.. code-block:: sh - - sudo touch /lib/systemd/system/mattermost.service - -As root, edit the systemd unit file to add the following lines: - -.. code-block:: text - - [Unit] - Description=Mattermost - After=network.target - - [Service] - Type=notify - ExecStart=/opt/mattermost/bin/mattermost - TimeoutStartSec=3600 - KillMode=mixed - Restart=always - RestartSec=10 - WorkingDirectory=/opt/mattermost - User=mattermost - Group=mattermost - LimitNOFILE=49152 - - [Install] - WantedBy=multi-user.target - -Save the file and reload systemd using ``sudo systemctl daemon-reload``. Mattermost Server is now installed and is ready for setup. - -.. note:: - - If you are installing the Mattermost server on the same system as your database, you may want to add both ``After=postgresql.service`` and ``BindsTo=postgresql.service`` to the ``[Unit]`` section of the systemd unit file. diff --git a/source/install/install-rhel.rst b/source/install/install-rhel.rst deleted file mode 100644 index 72beff56735..00000000000 --- a/source/install/install-rhel.rst +++ /dev/null @@ -1,170 +0,0 @@ -Install Mattermost on RHEL -========================== - -.. raw:: html - -
- -
-

- - Available on all plans -

-

- - Self-hosted deployments -

-
- -
-

Minimum system requirements:

-
    -
  • Operating System: Enterprise Linux 7+, Oracle Linux 6+, Oracle Linux 7+ -
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
    • -
  • Database: PostgreSQL v13+
    • -
  • Network: -
      -
    • Application 80/443, TLS, TCP Inbound
      • -
    • Administrator Console 8065, TLS, TCP Inbound
      • -
    • SMTP port 10025, TCP/UDP Outbound
      • -
    -
    • -
-
- -
- -.. note:: - - You need a PostgreSQL database. See the :doc:`database preparation ` documentation for details on this prerequisite. - -This Mattermost deployment includes 4 steps: `download <#download>`__, `install <#install>`__, `setup <#setup>`__, and `update <#updates>`__. - -Download the latest Mattermost Server tarball ---------------------------------------------- - -.. include:: download-latest-tarball.rst - :start-after: :nosearch: - -Install -------- - -Ahead of installing the Mattermost Server, it’s good practice to update all your repositories and, where required, update existing packages by running the following commands: - -.. code-block:: sh - - sudo dnf update - sudo dnf upgrade - -After any updates, and any system reboots, are complete, install the Mattermost Server. - -.. include:: install-mattermost-server-tarball.rst - :start-after: :nosearch: - -Setup ------ - -.. include:: setup-mattermost-server.rst - :start-after: :nosearch: - -.. important:: - If you don't receive an error when starting Mattermost after the previous step, you are good to go. If you did receive an error, continue on - -Modify SELinux settings ------------------------ - -When deploying Mattermost from RHEL9, which has SELinux running with enforceing mode enabled by default, additional configuration is required the SELinux policy is being enforced and denies access based on SELinux policy rules. - -First, ensure that SELinux is enabled and in enforcing mode by running the ``sestatus`` command. If it's ``enforcing``, you'll need to configure it properly. - -Set bin contexts for ``/opt/mattermost/bin`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -SELinux enforces security contexts for binaries. To label the Mattermost binaries as safe, you'll need to set them to the below SELinux context. - -.. code-block:: sh - - sudo semanage fcontext -a -t bin_t "/opt/mattermost/bin(/.*)?" - sudo restorecon -RF /opt/mattermost/bin - -Now, try starting Mattermost again with - -.. code-block:: sh - - sudo systemctl start mattermost - -If you don't receive an error, verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that's returned by the Mattermost Server. You're all set! - -.. important:: - If on starting Mattermost you receive an error, before moving on, check for the existence of a file in ``/opt/mattermost/logs`` - if ``mattermost.log`` exists in that directory, it's more likely you're dealing with a configuration issue in ``config.json``. Double check the previous steps before continuing - -Try different contexts for ``/opt/mattermost`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -SELinux enforces security contexts for files and directories. To label your Mattermost directory as safe, you'll need to set an appropriate SELinux context. - -1. Check current context by running ``ls -Z /opt/mattermost``. When you see something like ``drwxr-xr-x. root root unconfined_u:object_r:default_t:s0 mattermost`` returned, the ``default_t`` indicates that SELinux doesn't know what this directory is for. -2. Set a safe context by assigning a SELinux type that's compatible with web services or applications by running ``sudo semanage fcontext -a -t httpd_sys_content_t "/opt/mattermost(/.*)?"``. A common one is ``httpd_sys_content_t``, used for serving files. Ensure you match the directory and its contents recursively. Run the ``sudo restorecon -R /opt/mattermost`` to apply the changes. - -Allow Mattermost to bind to ports -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When Mattermost needs specific ports (e.g., 8065), ensure that SELinux allows it by allowing Mattermost to bind to ports. Run the ``sudo semanage port -l | grep 8065`` command, and if the port's not listed, you'll need to add it by running ``sudo semanage port -a -t http_port_t -p tcp 8065``, replacing the ``8065`` with the required port. - -Handle custom policies -~~~~~~~~~~~~~~~~~~~~~~~ - -If Mattermost requires actions that SELinux blocks, you'll need to generate a custom policy. - -1. Check for SELinux denials first in the logs by running ``sudo ausearch -m avc -ts recent``, or by checking the audit log: ``sudo cat /var/log/audit/audit.log | grep denied``. - -2. If needed, generate a policy module by installing ``audit2allow`` to generate policies automatically. - -.. code-block:: sh - - sudo yum install -y policycoreutils-python-utils - sudo grep mattermost /var/log/audit/audit.log | audit2allow -M mattermost_policy - sudo semodule -i mattermost_policy.pp - -Test the configuration -~~~~~~~~~~~~~~~~~~~~~~ - -Restart Mattermost to confirm the configuation works as expected by running ``sudo systemctl restart mattermost``. In the case of failures, revisit the logs to identify other SELinux-related issues. - -.. tip:: - - Need Mattermost working quickly for testing purposes? You can change SELinux to permissive mode by running the ``sudo setenforce 0``. command where policies aren't enforced, only logged. This command changes the SELinux mode to "permissive". While in permissive mode, policies aren't enforced, and violations are logged instead of being blocked. This can be helpful for debugging and troubleshooting issues related to SELinux policies. Ensure you re-enable enforcing mode once context is working as needed by running the ``sudo setenforce 1`` command. - -See the following SELinux resources for additional details: - -- `SELinux User’s and Administrator’s Guide `_ -- `SELinux Project Wiki `_ -- `Introduction to SELinux `_ -- `A Sysadmin’s Guide to SELinux: 42 Answers to the Big Questions `_ -- `Mastering SELinux: A Comprehensive Guide to Linux Security `_ - -Updates -------- - -Updating your Mattermost Server installation when using the tarball requires several manual steps. See the :doc:`upgrade Mattermost Server ` documentation for details. - -Remove Mattermost ------------------- - -If you wish to remove the Mattermost Server for any reason, you must stop the Mattermost Server, back up all important files, and then run this command: - -.. code-block:: sh - - sudo rm /opt/mattermost - -.. note:: - - Depending on your configuration, there are several important folders in ``/opt/mattermost`` to backup. These are ``config``, ``logs``, ``plugins``, ``client/plugins``, and ``data``. We strongly recommend you back up these locations before running the ``rm`` command. - -You may also remove the Mattermost systemd unit file and the user/group created for running the application. - -Frequently asked questions --------------------------- - -.. include:: common-deploy-faq.rst - :start-after: :nosearch: diff --git a/source/install/install-tar.rst b/source/install/install-tar.rst deleted file mode 100644 index 96bdf890bff..00000000000 --- a/source/install/install-tar.rst +++ /dev/null @@ -1,91 +0,0 @@ -Install Mattermost Server using the tarball -=========================================== - -.. raw:: html - -
- -
-

- - Available on all plans -

-

- - Self-hosted deployments -

-
- -
-

Minimum system requirements:

-
    -
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
    • -
  • Database: PostgreSQL v13+
    • -
  • Network: -
      -
    • Application 80/443, TLS, TCP Inbound
      • -
    • Administrator Console 8065, TLS, TCP Inbound
      • -
    • SMTP port 10025, TCP/UDP Outbound
      • -
    -
    • -
-
- -
- -You can install the Mattermost Server on any 64-bit Linux system using the tarball. This is the most flexible installation method, but it comes with the highest effort, normally favored by advanced system administrators. - -.. include:: ../_static/badges/academy-tarball-deployment.rst - :start-after: :nosearch: - -.. include:: common-omnibus-tip.rst - :start-after: :nosearch: - -.. include:: common-postgres-database-important.rst - :start-after: :nosearch: - -This Mattermost deployment includes 3 steps: `download <#download>`__, `install <#install>`__, and `setup <#setup>`__. - -Download --------- - -.. include:: download-latest-tarball.rst - :start-after: :nosearch: - -Install -------- - -.. include:: install-mattermost-server-tarball.rst - :start-after: :nosearch: - -Setup ------ - -.. include:: setup-mattermost-server.rst - :start-after: :nosearch: - -Updates -------- - -Updating your Mattermost Server installation when using the tarball requires several manual steps. See the :doc:`upgrade Mattermost Server ` documentation for details. - -Remove Mattermost ------------------- - -If you wish to remove the Mattermost Server for any reason, you must stop the Mattermost Server, back up all important files, and then run this command: - -.. code-block:: sh - - sudo rm - rf /opt/mattermost - -.. note:: - - Depending on your configuration, there are several important folders in ``/opt/mattermost`` to backup. These are ``config``, ``logs``, ``plugins``, ``client/plugins``, and ``data``. We strongly recommend you back up these locations before running the ``rm`` command. - -You may also remove the Mattermost systemd unit file and the user/group created for running the application. - -Frequently asked questions --------------------------- - -.. include:: common-deploy-faq.rst - :start-after: :nosearch: diff --git a/source/install/install-ubuntu.rst b/source/install/install-ubuntu.rst deleted file mode 100644 index 796f9c76376..00000000000 --- a/source/install/install-ubuntu.rst +++ /dev/null @@ -1,137 +0,0 @@ -Install Mattermost Server on Ubuntu -=================================== - -.. raw:: html - -
- -
-

- - Available on all plans -

-

- - Self-hosted deployments -

-
- -
-

Minimum system requirements:

-
    -
  • Operating System: 20.04 LTS, 22.04 LTS, 24.04 LTS -
  • Hardware: 1 vCPU/core with 2GB RAM (support for up to 1,000 users)
    • -
  • Database: PostgreSQL v13+
    • -
  • Network: -
      -
    • Application 80/443, TLS, TCP Inbound
      • -
    • Administrator Console 8065, TLS, TCP Inbound
      • -
    • SMTP port 10025, TCP/UDP Outbound
      • -
    -
    • -
-
- -
- -You can install the Mattermost Server using our ``.deb`` signed packages using the Mattermost PPA (Personal Package Archive). Using the Mattermost Personal Package Archive (PPA) not only provides the quickest way to install a Mattermost Server, but also provides automatic updates. This install method is used for both single and clustered installations. - -.. include:: common-omnibus-tip.rst - :start-after: :nosearch: - -.. include:: common-postgres-database-important.rst - :start-after: :nosearch: - -This Mattermost deployment includes 4 steps: `add the PPA repository <#add-the-mattermost-server-ppa-repository>`__, `install <#install>`__, `setup <#setup>`__, and `update <#updates>`__. - -Add the Mattermost Server PPA repository ----------------------------------------- - -.. include:: common-gpg-public-key-changed.rst - :start-after: :nosearch: - -In a terminal window, run the following repository setup command to add the Mattermost Server repositories: - -.. code-block:: sh - - curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost - -This command configures the repositories needed for a PostgreSQL database, configures an NGINX web server to act as a proxy, configures certbot to issue and renew the SSL certificate, and configures the Mattermost Omnibus repository so that you can run the install command. - -Install -------- - -Ahead of installing the Mattermost Server, it's good practice to update all your repositories and, where required, update existing packages by running the following command: - -.. code-block:: sh - - sudo apt update - -After any updates and system reboots are complete, you can install the Mattermost Server by running: - -.. code-block:: sh - - sudo apt install mattermost -y - -You now have the latest Mattermost Server version installed on your system. - -The installation path is ``/opt/mattermost``. The package will have added a user and group named ``mattermost``. The required systemd unit file has also been created but will not be set to active. - -.. note:: - - Since the signed package from the Mattermost repository is used for mulitple installation types, we don't add any dependencies in the systemd unit file. If you are installing the Mattermost server on the same system as your database, you may want to add both ``After=postgresql.service`` and ``BindsTo=postgresql.service`` to the ``[Unit]`` section of the systemd unit file. - -Setup ------ - -Before you start the Mattermost Server, you need to edit the configuration file. A sample configuration file is located at ``/opt/mattermost/config/config.defaults.json``. - -Rename this configuration file with correct permissions: - -.. code-block:: sh - - sudo install -C -m 600 -o mattermost -g mattermost /opt/mattermost/config/config.defaults.json /opt/mattermost/config/config.json - -.. include:: common-default-config-changes.rst - :start-after: :nosearch: - -.. include:: common-configure-support-email.rst - :start-after: :nosearch: - -After modifying the ``config.json`` configuration file, you can now start the Mattermost Server: - -.. code-block:: sh - - sudo systemctl start mattermost - -Verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that’s returned by the Mattermost Server. - -The final step, depending on your requirements, is to run ``sudo systemctl enable mattermost.service`` so that Mattermost will start on system boot. - -.. note:: - - The value of the ``sslmode`` property in the ``DataSource`` configuration is entirely dependent on your native environment. Please consult the native environment setup documentation for guidance on its value. The available options for ``sslmode`` are ``disable`` or ``require``. For example, if you are using Amazon Lightsail as your data source, you must set ``sslmode`` to ``require`` to successfully connect to the database. - -Updates -------- - -When a new Mattermost version is released, run: ``sudo apt update && sudo apt upgrade`` to download and update your Mattermost instance. - -.. note:: - - When you run the ``sudo apt upgrade`` command, ``mattermost-server`` will be updated along with any other packages. We strongly recommend you stop the Mattermost Server before running the ``apt`` command using ``sudo systemctl stop mattermost``. - -Remove Mattermost ------------------- - -If you wish to remove the Mattermost Server for any reason, you can run this command: - -.. code-block:: sh - - sudo apt remove --purge mattermost - -Frequently asked questions --------------------------- - -.. include:: common-deploy-faq.rst - :start-after: :nosearch: diff --git a/source/install/prepare-mattermost-database.rst b/source/install/prepare-mattermost-database.rst deleted file mode 100644 index edaf8706e05..00000000000 --- a/source/install/prepare-mattermost-database.rst +++ /dev/null @@ -1,261 +0,0 @@ -Prepare your Mattermost database -================================ - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -You need a PostgreSQL database. See the :ref:`database software ` documentation for details on database version support. Looking for information on migrating from MySQL to PostgreSQL? See the :doc:`Migrate from MySQL to PostgreSQL ` documentation for details. - -.. tip:: - - We recommend using a managed PostgreSQL database service, such as Amazon RDS, Google Cloud SQL, or Azure Database for PostgreSQL. - -Set up a PostgreSQL database ----------------------------- - -To set up a PostgreSQL database for use by the Mattermost server: - -1. Log in to the server that will host the database, and install PostgreSQL. See the `PostgreSQL `__ documentation for details. When the installation is complete, the PostgreSQL server is running, and a Linux user account called *postgres* has been created. - -2. Access PostgreSQL by running: - - .. code-block:: sh - - sudo -u postgres psql - -3. Create the Mattermost database by running: - - .. tab:: Ubuntu - - .. code-block:: SQL - - CREATE DATABASE mattermost; - - .. tab:: Red Hat - - .. code-block:: SQL - - CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0; - -3. Create the Mattermost database by running: - - .. tab:: Ubuntu - - .. code-block:: SQL - - CREATE DATABASE mattermost; - - .. tab:: Red Hat - - .. code-block:: SQL - - CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0; - -4. Switch to the new database by running: - - .. code-block:: sh - - \connect mattermost - -5. Create the Mattermost user *mmuser* by running the following command. Ensure you use a password that's more secure than ``mmuser-password``. - - .. code-block:: SQL - - CREATE USER mmuser WITH PASSWORD 'mmuser-password'; - -6. If you're configuring PostgreSQL v15.x or later: - - a. Grant the user access to the Mattermost database by running: - - .. code-block:: SQL - - GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser; - - b. Grant the user to change the owner of a database to a user ``mmuser`` by running: - - .. code-block:: SQL - - ALTER DATABASE mattermost OWNER TO mmuser; - - c. Grant access to objects contained in the specified schema by running: - - .. code-block:: SQL - - GRANT USAGE, CREATE ON SCHEMA PUBLIC TO mmuser; - -7. Exit the PostgreSQL interactive terminal by running: - - .. code-block:: text - - \q - -8. (Optional) If you use separate servers for your database and the Mattermost server, you may allow PostgreSQL to listen on all assigned IP addresses. We recommend ensuring that only the Mattermost server is able to connect to the PostgreSQL port using a firewall. - - .. tab:: Ubuntu - - Open ``/etc/postgresql/{version}/main/postgresql.conf`` as *root* in a text editor. - - Replace ``{version}`` with the version of PostgreSQL that's currently running. - - a. Find the following line: ``#listen_addresses = 'localhost'`` - - b. Uncomment the line and change ``localhost`` to ``*``: ``listen_addresses = '*'`` - - c. Restart PostgreSQL for the change to take effect by running: - - .. code-block:: sh - - sudo systemctl restart postgresql-{version} - - .. tab:: Red Hat - - Open ``/var/lib/pgsql/{version}/data/postgresql.conf`` as *root* in a text editor. - - Replace ``{version}`` with the version of PostgreSQL that's currently running. - - a. Find the following line: ``#listen_addresses = 'localhost'`` - - b. Uncomment the line and change ``localhost`` to ``*``: ``listen_addresses = '*'`` - - c. Restart PostgreSQL for the change to take effect by running: - - .. code-block:: sh - - sudo systemctl restart postgresql-{version} - -9. Modify the file ``pg_hba.conf`` to allow the Mattermost server to communicate with the database by ensuring host connection types are set to ``trust``. - - .. tab:: Ubuntu - - These host connections are specific to Ubuntu 20.04, and will differ depending on the operating system version you're running. For example, in Ubuntu 22.04, the ``peer`` connection types are listed as ``sha-256`` instead. - - **Local Database (same server)** - - If the Mattermost server and the database are on the same machine: - - a. Open ``/etc/postgresql/{version}/main/pg_hba.conf`` as *root* in a text editor. - - b. Find the following lines: - - ``local all all peer`` - - ``host all all ::1/128 ident`` - - c. Change ``peer`` and ``ident`` to ``trust``: - - ``local all all trust`` - - ``host all all ::1/128 trust`` - - **Remote Database (separate server)** - - If the Mattermost server and the database are on different machines: - - a. Open ``/etc/postgresql/{version}/main/pg_hba.conf`` in a text editor as *root* user. - - b. Add the following line to the end of the file, where ``{mattermost-server-IP}`` is the IP address of the Mattermost server: ``host all all {mattermost-server-IP}/32 md5``. - - .. tab:: Red Hat - - These host connections are specific to Red Hat 8, and will differ depending on the operating system version you're running. - - **Local Database (same server)** - - If the Mattermost server and the database are on the same machine: - - a. Open ``/var/lib/pgsql/{version}/data/pg_hba.conf`` as *root* in a text editor. - - b. Find the following lines: - - ``local all all peer`` - - ``host all all ::1/128 scram-sha-256`` - - c. Change ``peer`` and ``ident`` to ``trust``: - - ``local all all trust`` - - ``host all all ::1/128 trust`` - - **Remote Database (separate server)** - - If the Mattermost server and the database are on different machines: - - a. Open ```/var/lib/pgsql/{version}/data/pg_hba.conf`` in a text editor as *root* user. - - b. Add the following line to the end of the file, where ``{mattermost-server-IP}`` is the IP address of the Mattermost server: ``host all all {mattermost-server-IP}/32 md5``. - -10. Reload PostgreSQL by running: - - .. code-block:: sh - - sudo systemctl reload postgresql-{version} - -11. Verify that you can connect with the user *mmuser*. - -.. tab:: Local Database (same server) - - If the Mattermost server and the database are on the same machine, use the following command: - - .. code-block:: sh - - psql --dbname=mattermost --username=mmuser --password - -.. tab:: Remote Database (separate server) - - If the Mattermost server is on a different machine, log into that machine and use the following command: - - .. code-block:: sh - - psql --host={postgres-server-IP} --dbname=mattermost --username=mmuser --password - - .. note:: - - You might have to install the PostgreSQL client software to use the command. -The PostgreSQL interactive terminal starts. To exit the PostgreSQL interactive terminal, type ``\q`` and press :kbd:`Enter` on Windows or Linux, or :kbd:`↵` on Mac. - -When the PostgreSQL database is installed, and the initial setup is complete, you can install the Mattermost server. - -.. important:: - - If you are upgrading a major version of Postgres, it is essential that ``ANALYZE VERBOSE`` is run on the database post upgrade. This is necessary to re-populate the ``pg_statistics`` table used to generate optimal query plans. The database performance might suffer if this step is not done. - - -Minimum supported version policy ---------------------------------- - -To make planning easier and ensure your Mattermost deployment remains fast and secure, we are introducing a policy for updating the minimum supported version of PostgreSQL. The oldest supported PostgreSQL version Mattermost supports will match the oldest version supported by the PostgreSQL community. This ensures you benefit from the latest features and security updates. - -This policy change takes effect from Mattermost v10.6, where the minimum PostgreSQL version required will be PostgreSQL 13. This aligns with the PostgreSQL community's support policy, which provides 5 years of support for each major version. - -.. note:: - - Mattermost v10.6 is not an :ref:`Extended Support Release (ESR) `. Going forward, this database version support policy will only apply to ESR releases. - -When a PostgreSQL version reaches its end of life (EOL), Mattermost will require a newer version starting with the next scheduled ESR release. This means the following future PostgreSQL minimum version increases as follows: - -+-----------------------------------------------------------+------------------+--------------------------------+ -| **Mattermost Version** | **Release Date** | **Minimum PostgreSQL Version** | -+===========================================================+==================+================================+ -| :ref:`v9.11 ESR ` | 2024-8-15 | 11.x | -+-----------------------------------------------------------+------------------+--------------------------------+ -| :ref:`v10.5 ESR ` | 2025-2-15 | 11.x | -+-----------------------------------------------------------+------------------+--------------------------------+ -| :ref:`v10.6 ` | 2025-3-15 | 13.x | -+-----------------------------------------------------------+------------------+--------------------------------+ -| v10.11 ESR | 2025-8-15 | 13.x | -+-----------------------------------------------------------+------------------+--------------------------------+ -| v11.5 ESR ``*`` | 2026-2-15 | 14.x (EOL 2026-11-12) | -+-----------------------------------------------------------+------------------+--------------------------------+ - -``*`` Forcasted release version and date. - -Customers will have 9 months to plan, test, and upgrade their PostgreSQL version before the new requirement takes effect. This policy aims to provide clarity and transparency so you can align database upgrades with the Mattermost release schedule. Contact a `Mattermost Expert `_. to discuss your options. - -Frequently asked questions -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -What about MySQL databases? -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Mattermost is :ref:`deprecating support for MySQL ` starting with v11. We aren't actively maintaining or working on MySQL support. diff --git a/source/install/proxy-to-mattermost-transport-encryption.rst b/source/install/proxy-to-mattermost-transport-encryption.rst deleted file mode 100644 index c104a30f000..00000000000 --- a/source/install/proxy-to-mattermost-transport-encryption.rst +++ /dev/null @@ -1,113 +0,0 @@ -Configuring proxy to Mattermost transport encryption -==================================================== - -.. include:: ../_static/badges/ent-selfhosted.rst - :start-after: :nosearch: - -Mattermost is able to encrypt the traffic between the proxy and the application server using TLS. - -Prerequisites -------------- - -- Operational Mattermost server or cluster. -- Authentication credentials for Mattermost user on application server. - -Example environment -------------------- - -In this scenario there is one Mattermost application server and one NGINX server, both running Ubuntu 20.04, with the following IPs: - -- **transport-encryption-mattermost1:** 10.10.250.146 -- **transport-encryption-nginx:** 10.10.250.107 - -Configuring NGINX ------------------ - -On the NGINX server, connect to both servers with a sudo or root user. Open the Mattermost proxy configuration and search for the following line twice: - -.. code-block:: text - - proxy_pass http://backend; - -Change the protocol from ``http`` to ``https``: - -.. code-block:: text - - proxy_pass https://backend; - -Afterwards do not reload the NGINX server yet to minimize the downtime of the service. - -Configuring Mattermost ----------------------- - -On the Mattermost server, change to the config directory of Mattermost and generate a self-signed certificate that will be used to encrypt the traffic between the proxy server and the application server. - -**Note:** Alternatively you can sign a certificate from your company's CA. - -.. code-block:: sh - - cd /opt/mattermost/config - openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes - chown root:mattermost *.pem - chmod 640 *.pem - - -Once complete, open the file ``config.json`` and modify the values ``ConnectionSecurity``, ``TLSCertFile`` and ``TLSKeyFile`` in the ``ServiceSettings`` section. - -**Before** - -.. code-block:: json - - { - "ServiceSettings": { - "SiteURL": "https://transport-encryption.dev.example.com", - "WebsocketURL": "", - "LicenseFileLocation": "", - "ListenAddress": ":8065", - "ConnectionSecurity": "", - "TLSCertFile": "", - "TLSKeyFile": "", - "...":"..." - }, - "...":"..." - } - - -**After** - -.. code-block:: json - - { - "ServiceSettings": { - "SiteURL": "https://transport-encryption.dev.example.com", - "WebsocketURL": "", - "LicenseFileLocation": "", - "ListenAddress": ":8065", - "ConnectionSecurity": "TLS", - "TLSCertFile": "/opt/mattermost/config/cert.pem", - "TLSKeyFile": "/opt/mattermost/config/key.pem", - "...":"..." - }, - "...":"..." - } - - -Restart the Mattermost server and ensure it's up and running: - -.. code-block:: sh - - sudo systemctl restart mattermost - systemctl status mattermost - -.. code-block:: text - - ● mattermost.service - Mattermost - Loaded: loaded (/lib/systemd/system/mattermost.service; static; vendor preset: enabled) - Active: active (running) since Mon 2019-10-28 16:45:29 UTC; 1h 15min ago - [...] - -Finally, on the **NGINX server**, reload the configuration to ensure that requests are sent on HTTPS: - -.. code-block:: sh - - sudo systemctl reload nginx diff --git a/source/install/setup-mattermost-server.rst b/source/install/setup-mattermost-server.rst deleted file mode 100644 index 71e0153d0e4..00000000000 --- a/source/install/setup-mattermost-server.rst +++ /dev/null @@ -1,28 +0,0 @@ -:orphan: -:nosearch: - -.. This page is intentionally not accessible via the LHS navigation pane because it's common content included on other docs pages. - -Before you start the Mattermost Server, you need to edit the configuration file. A default configuration file is located at ``/opt/mattermost/config/config.json``. - -We recommend taking a backup of this default config ahead of making changes: - -.. code-block:: sh - - sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json - -.. include:: common-default-config-changes.rst - :start-after: :nosearch: - -.. include:: common-configure-support-email.rst - :start-after: :nosearch: - -After modifying the ``config.json`` configuration file, you can now start the Mattermost server: - -.. code-block:: sh - - sudo systemctl start mattermost - -Verify that Mattermost is running: curl ``http://localhost:8065``. You should see the HTML that’s returned by the Mattermost Server. - -The final step, depending on your requirements, is to run sudo ``systemctl enable mattermost.service`` so that Mattermost will start on system boot. diff --git a/source/install/setup-tls.rst b/source/install/setup-tls.rst deleted file mode 100644 index af270fc2162..00000000000 --- a/source/install/setup-tls.rst +++ /dev/null @@ -1,8 +0,0 @@ -Set up TLS -========== - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -.. include:: config-tls-mattermost.rst - :start-after: :nosearch: \ No newline at end of file diff --git a/source/install/transport-encryption.rst b/source/install/transport-encryption.rst deleted file mode 100644 index 31ba9248038..00000000000 --- a/source/install/transport-encryption.rst +++ /dev/null @@ -1,23 +0,0 @@ -Configuring transport encryption -================================= - -.. include:: ../_static/badges/ent-selfhosted.rst - :start-after: :nosearch: - -The components of the Mattermost setup are shown in the following diagram, including the transport encryption used. Aside from the encryption between the nodes of the Mattermost cluster, all transports rely on TLS encryption. - -.. note:: - - The transport between the Application servers is not used by default and requires additional setup steps. Enhancing the core product to include automatic encryption between cluster nodes is in progress and planned for a later release. - -.. image:: ../images/transport-encryption.png - :alt: Components of the Mattermost setup where all transports rely on TLS encryption. - -The configuration guides are split up into the following documents: - -.. toctree:: - :titlesonly: - - proxy-to-mattermost-transport-encryption.rst - database-transport-encryption.rst - cluster-transport-encryption.rst diff --git a/source/install/trial-mattermost-using-docker.rst b/source/install/trial-mattermost-using-docker.rst deleted file mode 100644 index da051a3a764..00000000000 --- a/source/install/trial-mattermost-using-docker.rst +++ /dev/null @@ -1,60 +0,0 @@ -Trial Mattermost using Docker -============================= - -.. include:: ../_static/badges/allplans-selfhosted.rst - :start-after: :nosearch: - -.. tip:: - - Looking to deploy Mattermost in a production environment? See the :doc:`Docker deployment ` documentation for details. - -.. _Preview Mattermost on Docker: - -Preview Mattermost using Docker -------------------------------- - -Using the `Mattermost Docker Preview Image `__ is the fastest way to trial Mattermost in **Preview Mode**, and explore product functionality on a single local machine. - -.. important:: - - This local image is self-contained (i.e., it has an internal database and works out of the box). Dropping a container using this image removes data and configuration as expected. You can see the :doc:`configuration settings ` documentation to learn more about customizing your trial deployment. - - **Preview Mode** shouldn't be used in a production environment, as it uses a known password string, contains other non-production configuration settings, has email disabled, keeps no persistent data (all data lives inside the container), and doesn't support upgrades. - - If you are planning to use the calling functionality in **Preview Mode** on a non-local environment, you should ensure that the server is running on a secure (HTTPs) connection and that the :ref:`network requirements ` to run calls are met. - -1. Install `Docker `__. - -2. Once you have Docker, run the following command in a terminal window: - - .. code-block:: sh - - docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview - -3. When Docker is done fetching the image, navigate to ``http://localhost:8065/`` in your browser to preview Mattermost. -4. Select **Don't have an account** in the top right corner of the screen to create an account for your preview instance. If you don't see this option, ensure that the :ref:`Enable open server ` configuration setting is enabled. This setting is disabled for self-hosted Mattermost deployments by default. -5. Log in to your preview instance with your user credentials. - -Troubleshooting your preview deployment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The **Preview Mode** Docker instance for Mattermost is designed for product evaluation, and sets ``SendEmailNotifications=false`` so the product can function without enabling email. See the :doc:`Configuration Settings ` documentation to customize your deployment. - -To update your Mattermost preview image and container, you must first stop and delete your existing **mattermost-preview** container by running the following commands: - -.. code-block:: sh - - docker pull mattermost/mattermost-preview - docker stop mattermost-preview - docker rm mattermost-preview - -Once the new image is pulled and the container is stopped and deleted you need to run the ``docker run`` command from above. - -.. important:: - On Linux, include ``sudo`` in front of all ``docker`` commands. - -To access a shell inside the container, run the following command: - -.. code-block:: sh - - docker exec -ti mattermost-preview /bin/bash \ No newline at end of file diff --git a/source/integrate/community-for-mattermost-for-microsoft-teams.rst b/source/integrate/community-for-mattermost-for-microsoft-teams.rst index 60da7e772ee..313f89cc918 100644 --- a/source/integrate/community-for-mattermost-for-microsoft-teams.rst +++ b/source/integrate/community-for-mattermost-for-microsoft-teams.rst @@ -52,8 +52,8 @@ Once you've installed the app, here are some ways to get started: - **Share feedback**: Your ideas and feedback are valuable! Share your thoughts in the `~user-feedback `_ channel. -Roadmap for Community for Mattermost and Microsoft Teams Integration -------------------------------------------------------------------- +Roadmap for Community for Mattermost and Microsoft Teams integration +---------------------------------------------------------------------- We are continuously improving the integration between Mattermost and Microsoft Teams to provide better connectivity and communication. Below are the upcoming features planned for this integration: diff --git a/source/manage/admin/customize-branding.rst b/source/manage/admin/customize-branding.rst new file mode 100644 index 00000000000..a7a066356e4 --- /dev/null +++ b/source/manage/admin/customize-branding.rst @@ -0,0 +1,17 @@ +Customize branding +=================== + +Whether you’re customizing the appearance of your workspace, utilizing branding tools, or managing code signing for custom builds, this section of documentation has you covered and provides everything you need to customize the branding of Mattermost to align with your organization’s identity. Use the navigation below to access detailed instructions for each customization option. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Customize Mattermost + Custom branding tools + Code signing custom builds + +* :doc:`Customize Mattermost ` - Learn how to customize the Mattermost server. +* :doc:`Custom branding tools ` - Learn about custom branding tools for Mattermost. +* :doc:`Code signing custom builds ` - Learn about code signing custom builds of Mattermost. \ No newline at end of file diff --git a/source/manage/error-codes.rst b/source/manage/admin/error-codes.rst similarity index 97% rename from source/manage/error-codes.rst rename to source/manage/admin/error-codes.rst index f72698ff494..0731493846e 100644 --- a/source/manage/error-codes.rst +++ b/source/manage/admin/error-codes.rst @@ -1,7 +1,7 @@ Mattermost error codes ====================== -.. include:: ../_static/badges/allplans-selfhosted.rst +.. include:: ../../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: Mattermost is designed to deploy in private networks which may be disconnected or “air-gapped” from the internet. In these deployments, links to Mattermost’s online documentation may be unavailable. diff --git a/source/manage/generating-support-packet.rst b/source/manage/admin/generating-support-packet.rst similarity index 99% rename from source/manage/generating-support-packet.rst rename to source/manage/admin/generating-support-packet.rst index d937bbac44e..c3bc836470a 100644 --- a/source/manage/generating-support-packet.rst +++ b/source/manage/admin/generating-support-packet.rst @@ -1,7 +1,7 @@ Generate a Support Packet ========================== -.. include:: ../_static/badges/ent-pro-selfhosted.rst +.. include:: ../../_static/badges/ent-pro-selfhosted.rst :start-after: :nosearch: The Support Packet is used to help customers diagnose and troubleshoot issues. Use the System Console or the :ref:`mmctl system supportpacket ` command to generate a zip file that includes configuration information, logs, plugin details, and data on external dependencies across all nodes in a high-availability cluster. Confidential data, such as passwords, are automatically stripped. @@ -17,7 +17,7 @@ Generate 1. Go to the System Console, and select **Commercial Support** from the System Console menu. - .. image:: ../images/system-console-commercial-support.png + .. image:: ../../images/system-console-commercial-support.png :alt: Example of available System Console menu options. 2. Select **Download Support Packet**. A zip file is downloaded to the local machine. You'll be notified if any packet files are unavailable during packet generation. See the ``warning.txt`` file for details. diff --git a/source/upgrade/installing-license-key.rst b/source/manage/admin/installing-license-key.rst similarity index 98% rename from source/upgrade/installing-license-key.rst rename to source/manage/admin/installing-license-key.rst index e0d3b476390..432df28e043 100644 --- a/source/upgrade/installing-license-key.rst +++ b/source/manage/admin/installing-license-key.rst @@ -1,7 +1,7 @@ Install a license key ===================== -.. include:: ../_static/badges/ent-pro-cloud-selfhosted.rst +.. include:: ../../_static/badges/ent-pro-cloud-selfhosted.rst :start-after: :nosearch: You can use the System Console or the mmctl tools to add or change a Mattermost license key. diff --git a/source/manage/admin/migration.rst b/source/manage/admin/migration.rst new file mode 100644 index 00000000000..f2226ee9592 --- /dev/null +++ b/source/manage/admin/migration.rst @@ -0,0 +1,25 @@ +Migration +========== + +This Mattermost Migration Guide is organized into sections based on migration scenarios and tools to help you transition smoothly to Mattermost or optimize your current setup. + +Whether you’re migrating from another platform, upgrading your database, or using bulk tools for data management, this guide provides the resources and instructions you need for a successful migration. Use the navigation below to explore detailed guidance tailored to your migration needs. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Migrate from MySQL to PostgreSQL + Server migration guide + Migrate from Slack + Bulk export tool + Bulk loading tool + Migration announcement email template + +* :doc:`Migrate from MySQL to PostgreSQL ` - Learn how to migrate from MySQL to PostgreSQL. +* :doc:`Server migration guide ` - Learn about about migrating to Mattermost. +* :doc:`Migrate from Slack ` - Learn how to migrate from Slack to Mattermost. +* :doc:`Bulk export tool ` - Learn about the bulk export tool for Mattermost. +* :doc:`Bulk loading tool ` - Learn about the bulk loading tool for Mattermost. +* :doc:`Migration announcement email template ` - Use this email template to notify your users that you've migrated to Mattermost. \ No newline at end of file diff --git a/source/manage/admin/monitoring-and-performance.rst b/source/manage/admin/monitoring-and-performance.rst new file mode 100644 index 00000000000..2c64a0850a8 --- /dev/null +++ b/source/manage/admin/monitoring-and-performance.rst @@ -0,0 +1,45 @@ +Monitoring and performance +========================== + +This Monitoring and Performance Guide is organized into sections to help you effectively monitor, optimize, and manage the performance of your Mattermost installation. + +From collecting performance metrics and deploying monitoring tools to configuring health checks and managing notifications, this guide offers comprehensive resources to ensure your Mattermost workspace operates at peak efficiency. Use the navigation below to explore detailed instructions and best practices. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Optimize your Mattermost workspace + Collect performance metrics + Deploy Prometheus and Grafana for performance monitoring + Performance monitoring metrics + Push notification health targets + Performance alerting guide + Ensuring releases perform at scale + Manage user surveys + User satisfaction surveys + Notify admin + System-wide notifications + Statistics + In-product notices + Health checks + Health check probes + Product limits + +* :doc:`Optimize your Mattermost workspace ` - Learn about optimizing your Mattermost workspace. +* :doc:`Collect performance metrics ` - Learn about collecting performance metrics for Mattermost. +* :doc:`Deploy Prometheus and Grafana for performance monitoring ` - Learn how to deploy Prometheus and Grafana for performance monitoring. +* :doc:`Performance monitoring metrics ` - Learn about performance monitoring metrics for Mattermost. +* :doc:`Push notification health targets ` - Learn about push notification health targets for Mattermost. +* :doc:`Performance alerting guide ` - Learn about performance alerting for Mattermost. +* :doc:`Ensuring releases perform at scale ` - Learn how to ensure releases perform at scale for Mattermost. +* :doc:`Manage user surveys ` - Learn about managing user surveys for Mattermost. +* :doc:`User satisfaction surveys ` - Learn how to send user satisfaction surveys for Mattermost. +* :doc:`Notify admin ` - Learn how to notify admins for Mattermost. +* :doc:`System-wide notifications ` - Learn about system-wide notifications for Mattermost. +* :doc:`Statistics ` - Learn about Mattermost statistics . +* :doc:`In-product notices ` - Learn how to use in-product notices for Mattermost. +* :doc:`Health checks ` - Learn about health checks for Mattermost. +* :doc:`Health check probes ` - Learn how to set up health check probes for Mattermost. +* :doc:`Product limits ` - Learn about product limits for Mattermost. \ No newline at end of file diff --git a/source/manage/self-hosted-billing.rst b/source/manage/admin/self-hosted-billing.rst similarity index 100% rename from source/manage/self-hosted-billing.rst rename to source/manage/admin/self-hosted-billing.rst diff --git a/source/manage/admin/server-configuration.rst b/source/manage/admin/server-configuration.rst new file mode 100644 index 00000000000..da5af4a13e7 --- /dev/null +++ b/source/manage/admin/server-configuration.rst @@ -0,0 +1,37 @@ +Server configuration +===================== + +This Server Configuration Guide is organized into sections to provide you with the tools and knowledge necessary to configure your Mattermost server for improved efficiency, scalability, and functionality. + +Whether you’re setting up email notifications, optimizing search capabilities, enabling high availability, or configuring telemetry, this guide covers all aspects of server setup and management. Use the navigation below to access detailed instructions for each topic. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Elasticsearch + High availability + Store configuration in your database + Server configuration options + Environment variables + Customize the server + SMTP email setup + Email templates + Chinese, Japanese, and Korean search + SSL client certificate setup + Connected workspaces + Telemetry + +* :doc:`Elasticsearch ` - Learn how to configure Elasticsearch for Mattermost. +* :doc:`High availability ` - Learn how to configure high availability for Mattermost. +* :doc:`Store configuration in your database ` - Learn how to store configuration information in your Mattermost database rather than as a JSON file. +* :doc:`Server configuration options ` - Learn about server configuration options for Mattermost. +* :doc:`Environment variables ` - Learn how to use environment variables for Mattermost configuration. +* :doc:`Customize the server ` - Learn about customizing branding for Mattermost server. +* :doc:`SMTP email setup ` - Learn how to set up SMTP email for Mattermost. +* :doc:`Email templates ` - Learn about customizing email templates for Mattermost. +* :doc:`Chinese, Japanese, and Korean search ` - Learn about enabling Chinese, Japanese, and Korean search for Mattermost. +* :doc:`SSL client certificate setup ` - Learn how to set up SSL client certificates for Mattermost. +* :doc:`Connected workspaces ` - Learn how to connect Mattermost workspaces. +* :doc:`Telemetry ` - Learn about Mattermost telemetry and data collection. diff --git a/source/manage/admin/server-maintenance.rst b/source/manage/admin/server-maintenance.rst new file mode 100644 index 00000000000..c3e0c3c1a00 --- /dev/null +++ b/source/manage/admin/server-maintenance.rst @@ -0,0 +1,33 @@ +Server maintenance +==================== + +This Server Maintenance Guide is organized into sections that provide the tools and knowledge needed to maintain your Mattermost server effectively, ensuring optimal security, scalability, and reliability. + +Whether you’re installing a license key, performing backups, upgrading the server, or using administrative tools like mmctl and the CLI, this guide offers comprehensive instructions to help you manage your server with confidence. Use the navigation below to access detailed information on each topic. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Install a license key + Generate a support packet + Backup and disaster recovery + Upgrade Mattermost server + Secure Mattermost + Scale your deployment + Mattermost error codes + mmctl + CLI + Feature labels + +* :doc:`Install a license key ` - Learn how to install a license key for Mattermost. +* :doc:`Generate a support packet ` - Learn how to generate a support packet for Mattermost. +* :doc:`Backup and disaster recovery ` - Learn about backup and disaster recovery for Mattermost. +* :doc:`Upgrade Mattermost server ` - Learn how to upgrading Mattermost server. +* :doc:`Secure Mattermost ` - Learn about securing Mattermost server. +* :doc:`Scale your deployment ` - Learn about scaling Mattermost deployment. +* :doc:`Mattermost error codes ` - Learn about Mattermost error codes and troubleshooting. +* :doc:`mmctl ` - Learn about the mmctl command line tool for Mattermost. +* :doc:`CLI ` - Learn about command line tools for Mattermost. +* :doc:`Feature labels ` - Learn about Mattermost feature labels and their meanings. \ No newline at end of file diff --git a/source/manage/admin/user-management.rst b/source/manage/admin/user-management.rst new file mode 100644 index 00000000000..fb0c3084a92 --- /dev/null +++ b/source/manage/admin/user-management.rst @@ -0,0 +1,21 @@ +User management +=============== + +Welcome to the Mattermost User Management Guide. This User Management Guide is organized into sections to help you manage users, permissions, and roles effectively in your Mattermost workspace. + +Whether you’re configuring team and channel settings, managing guest accounts, or leveraging advanced permissions infrastructure, this guide provides the resources and instructions necessary to tailor user management to your organization’s needs. Use the navigation below to explore detailed guidance for each area. + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Permissions + Manage team and channel configuration + Advanced permissions infrastructure + Guest accounts + +* :doc:`Permissions ` - Learn about permissions in Mattermost. +* :doc:`Manage team and channel configuration ` - Learn about managing team and channel configuration in Mattermost. +* :doc:`Advanced permissions infrastructure ` - Learn about advanced permissions infrastructure in Mattermost. +* :doc:`Guest accounts ` - Learn about guest accounts in Mattermost. \ No newline at end of file diff --git a/source/manage/admin/user-provisioning.rst b/source/manage/admin/user-provisioning.rst new file mode 100644 index 00000000000..4a325fcebee --- /dev/null +++ b/source/manage/admin/user-provisioning.rst @@ -0,0 +1,25 @@ +User provisioning +================== + +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Provisioning workflows + AD/LDAP setup + AD/LDAP manage team or private channel membership + GitLab SSO + OpenID Connect SSO + Google SSO + Entra ID SSO + Convert OAuth 2.0 providers to OpenID + +* :doc:`Provisioning workflows ` - Learn about provisioning workflows in Mattermost. +* :doc:`AD/LDAP setup ` - Learn how to set up AD/LDAP in Mattermost. +* :doc:`AD/LDAP manage team or private channel membership ` - Learn how to manage team or private channel membership using AD/LDAP sync groups in Mattermost. +* :doc:`GitLab SSO ` - Learn how to use GitLab SSO in Mattermost. +* :doc:`OpenID Connect SSO ` - Learn how to use about OpenID Connect SSO in Mattermost. +* :doc:`Google SSO ` - Learn how to use Google SSO in Mattermost. +* :doc:`Entra ID SSO ` - Learn how to use Entra ID SSO in Mattermost. +* :doc:`Convert OAuth 2.0 providers to OpenID ` - Learn how to convert OAuth 2.0 providers to OpenID in Mattermost. \ No newline at end of file diff --git a/source/manage/cloud-data-export.rst b/source/manage/cloud-data-export.rst index 204f407b7f0..38eb4b4fa04 100644 --- a/source/manage/cloud-data-export.rst +++ b/source/manage/cloud-data-export.rst @@ -104,7 +104,7 @@ You can migrate your Cloud workspace data to a self-hosted deployment at any tim How does the process work? ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Before you export and migrate your data, you must :doc:`install Mattermost ` on the server you’ll be using to run Mattermost. The migration is done using the mmctl CLI tool, which is a remote CLI tool for Mattermost that's installed locally and uses the Mattermost API. ``mmctl`` is pre-installed. +Before you export and migrate your data, you must :doc:`install Mattermost ` on the server you’ll be using to run Mattermost. The migration is done using the mmctl CLI tool, which is a remote CLI tool for Mattermost that's installed locally and uses the Mattermost API. ``mmctl`` is pre-installed. The :ref:`mmctl usage notes ` provide some additional context and information which you can reference before and during the process. diff --git a/source/manage/command-line-tools.rst b/source/manage/command-line-tools.rst index 8e91d1761f4..5fc23a2bc5c 100644 --- a/source/manage/command-line-tools.rst +++ b/source/manage/command-line-tools.rst @@ -36,7 +36,7 @@ Use the CLI .. tab:: Via Mattermost - To run the CLI commands, you must be in the Mattermost root directory. On a default installation of Mattermost, the root directory is ``/opt/mattermost``. If you followed our standard :doc:`installation process `, you must run the commands as the user ``mattermost``. The name of the executable is ``mattermost``, and it can be found in the ``/opt/mattermost/bin`` directory. + To run the CLI commands, you must be in the Mattermost root directory. On a default installation of Mattermost, the root directory is ``/opt/mattermost``. If you followed our standard :doc:`installation process `, you must run the commands as the user ``mattermost``. The name of the executable is ``mattermost``, and it can be found in the ``/opt/mattermost/bin`` directory. For example, to get the Mattermost version on a default installation of Mattermost: diff --git a/source/manage/configure-health-check-probes.rst b/source/manage/configure-health-check-probes.rst index 85e67774368..c11956791e8 100644 --- a/source/manage/configure-health-check-probes.rst +++ b/source/manage/configure-health-check-probes.rst @@ -6,7 +6,7 @@ Configure server health check probes This page describes how to configure health check probes for a Mattermost server. -Before you begin, you should have a running Mattermost server. If you don't, you can :doc:`install Mattermost on various distributions ` or deploy a `Kubernetes cluster with Minikube `_. +Before you begin, you should have a running Mattermost server. If you don't, you can :doc:`install Mattermost on various distributions `. .. note:: diff --git a/source/getting-started/feature-labels.rst b/source/manage/feature-labels.rst similarity index 99% rename from source/getting-started/feature-labels.rst rename to source/manage/feature-labels.rst index 25d3f948a60..7dd884847bb 100644 --- a/source/getting-started/feature-labels.rst +++ b/source/manage/feature-labels.rst @@ -21,8 +21,4 @@ Feature has undergone thorough validation and testing and has production-level q Deprecated ----------- -Feature is officially marked for removal from the product. It is no longer supported or actively maintained by the development team. If the feature is still in use in your deployed version, we recommend users discontinue its use and migrate to alternative functionalities. - - - - +Feature is officially marked for removal from the product. It is no longer supported or actively maintained by the development team. If the feature is still in use in your deployed version, we recommend users discontinue its use and migrate to alternative functionalities. \ No newline at end of file diff --git a/source/manage/request-server-health-check.rst b/source/manage/request-server-health-check.rst index b25f2b9fda6..70771ef0d86 100644 --- a/source/manage/request-server-health-check.rst +++ b/source/manage/request-server-health-check.rst @@ -27,7 +27,7 @@ Get started Getting started with a Mattermost Health Check is simple and involves 3 steps: -1. :doc:`Generate a Support Packet `: The Mattermost Support Packet contains critical information about your Mattermost environment, including logs, configurations, and usage data. +1. :doc:`Generate a Support Packet `: The Mattermost Support Packet contains critical information about your Mattermost environment, including logs, configurations, and usage data. 2. Submit Your Support Packet: Once you’ve generated the Support Packet, submit it through our Support System as a `standard support request `_. Please include “Health Check Provided” in the subject line. diff --git a/source/onboard/bulk-loading-data.rst b/source/onboard/bulk-loading-data.rst index 92be8650172..97a990cf680 100644 --- a/source/onboard/bulk-loading-data.rst +++ b/source/onboard/bulk-loading-data.rst @@ -1615,5 +1615,3 @@ Running bulk loading tool hangs and doesn't complete If you have Bleve search indexing enabled, temporarily disable it in **System Console > Experimental > Bleve** and run the command again. Bleve does not support multiple processes opening and manipulating the same index. Therefore, if the Mattermost server is running, an attempt to run the bulk loading tool will lock when trying to open the indeces. - -If you are not using the Bleve search indexing, feel free to post in our :doc:`Troubleshooting forum ` for help. diff --git a/source/onboard/certificate-based-authentication.rst b/source/onboard/certificate-based-authentication.rst index 4f887b81081..bad0f3b130b 100644 --- a/source/onboard/certificate-based-authentication.rst +++ b/source/onboard/certificate-based-authentication.rst @@ -8,7 +8,7 @@ Certificate-based authentication (CBA) is available as an experimental feature t Follow these steps to configure user CBA for your browser and Mattermost Desktop Apps. Support for the Mattermost iOS and Android Apps is planned. It is expected that you can manage certificate distribution for each personal device (BYOD) and their life cycle management with a service like `OpenSSL `__. -Before you begin, follow the :doc:`official guides to install Mattermost ` on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let's Encrypt. +Before you begin, follow the :doc:`official guides to install Mattermost ` on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let's Encrypt. Set up mutual TLS authentication for the Web App ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/onboard/ssl-client-certificate.rst b/source/onboard/ssl-client-certificate.rst index 6e954f326de..87b30599d20 100644 --- a/source/onboard/ssl-client-certificate.rst +++ b/source/onboard/ssl-client-certificate.rst @@ -6,7 +6,7 @@ SSL client certificate setup Follow these steps to configure SSL client certificates for your browser and the Mattermost desktop apps on Windows, macOS, and Linux. SSL client certificates are not yet supported on the Mattermost mobile apps. -Before you begin, follow the :doc:`official guides to install Mattermost ` on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let's Encrypt. +Before you begin, follow the :doc:`official guides to install Mattermost ` on your system, including NGINX configuration as a proxy with SSL and HTTP/2, and a valid SSL certificate such as Let's Encrypt. For the purposes of this guide, the Mattermost server domain name is ``example.mattermost.com``, and the user account is ``mmuser`` with email ``mmuser@mattermost.com`` and password ``mmuser-password``. @@ -133,8 +133,3 @@ You should see the Mattermost login page. If you see: 2. Go to **File > Import Items** and select the ``mmuser-mattermost.p12`` file. 10. Go to ``https://example.mattermost.com``. You should see a popup for the client certificate request. - -Troubleshooting -~~~~~~~~~~~~~~~~ - -:doc:`Follow this process ` to resolve configuration issues and to ask for help. diff --git a/source/overview/index.rst b/source/overview/index.rst index 535dcc7f11f..a1891197a47 100644 --- a/source/overview/index.rst +++ b/source/overview/index.rst @@ -5,7 +5,7 @@ About Mattermost Mattermost’s purpose is to accelerate the world’s mission critical work by developing and delivering secure, open core collaboration software providing unrivaled focus, adaptability and resilience to our customers. You’ll find an overview of our products, features, security, integrations, licensing and subscriptions, authentication, and compliance support below. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :hidden: /about/product.rst diff --git a/source/preferences/customize-desktop-app-experience.rst b/source/preferences/customize-desktop-app-experience.rst index 2c5dbae68b0..0ca80f435d0 100644 --- a/source/preferences/customize-desktop-app-experience.rst +++ b/source/preferences/customize-desktop-app-experience.rst @@ -8,7 +8,7 @@ Additional customization options are available to you when using the Mattermost .. tab:: Linux - When you :ref:`install the Mattermost desktop app `, you can access additional Desktop App customization settings from the **More** |more-icon-vertical| icon located in the top left corner of the desktop app by selecting **File > Settings...** + When you :doc:`install the Mattermost desktop app `, you can access additional Desktop App customization settings from the **More** |more-icon-vertical| icon located in the top left corner of the desktop app by selecting **File > Settings...** .. image:: ../images/desktop-app-settings.jpg :alt: Access Desktop App customization settings by selecting More in the top left corner, then selecting File > Settings. @@ -56,7 +56,7 @@ Additional customization options are available to you when using the Mattermost .. tab:: Mac - When you :ref:`install the Mattermost desktop app `, you can access additional Desktop App customization settings by selecting **Mattermost > Preferences** from the menu bar. + When you :doc:`install the Mattermost desktop app `, you can access additional Desktop App customization settings by selecting **Mattermost > Preferences** from the menu bar. .. image:: ../images/mac-desktop-app-settings.png :alt: Access Desktop App customization settings by selecting Mattermost from the menu bar, then selecting Preferences. @@ -92,7 +92,7 @@ Additional customization options are available to you when using the Mattermost .. tab:: Windows - When you :ref:`install the Mattermost desktop app `, you can access additional Desktop App customization settings from the **More** |more-icon-vertical| icon located in the top left corner of the desktop app by selecting **File > Settings...** + When you :doc:`install the Mattermost desktop app `, you can access additional Desktop App customization settings from the **More** |more-icon-vertical| icon located in the top left corner of the desktop app by selecting **File > Settings...** .. image:: ../images/desktop-app-settings.jpg :alt: Access Desktop App customization settings by selecting More in the top left corner, then selecting File > Settings. diff --git a/source/scale/high-availability-cluster-based-deployment.rst b/source/scale/high-availability-cluster-based-deployment.rst index 4610868b40b..295a8e6aa56 100644 --- a/source/scale/high-availability-cluster-based-deployment.rst +++ b/source/scale/high-availability-cluster-based-deployment.rst @@ -8,22 +8,24 @@ A high availability cluster-based deployment enables a Mattermost system to main High availability in Mattermost consists of running redundant Mattermost application servers, redundant database servers, and redundant load balancers. The failure of any one of these components does not interrupt operation of the system. -Requirements for continuous operation -------------------------------------- +Mattermost Enterprise supports: -To enable continuous operation at all times, including during server updates and server upgrades, you must make sure that the redundant components are properly sized and that you follow the correct sequence for updating each of the system's components. +1. Clustered Mattermost servers, which minimize latency by: -Redundancy at anticipated scale - Upon failure of one component, the remaining application servers, database servers, and load balancers must be sized and configured to carry the full load of the system. If this requirement is not met, an outage of one component can result in an overload of the remaining components, causing a complete system outage. +- Storing static assets over a global CDN. +- Deploying multiple Mattermost servers to host API communication closer to the location of end users. -Update sequence for continuous operation - You can apply most configuration changes and dot release security updates without interrupting service, provided that you update the system components in the correct sequence. See the `upgrade guide`_ for instructions on how to do this. +They can also be used to handle scale and failure handoffs in disaster recovery scenarios. - **Exception:** Changes to configuration settings that require a server restart, and server version upgrades that involve a change to the database schema, require a short period of downtime. Downtime for a server restart is around five seconds. For a database schema update, downtime can be up to 30 seconds. +2. Database read replicas, where replicas can be: -.. important:: +- Configured as a redundant backup to the active database server. +- Used to scale up the number of concurrent users. +- Deployed closer to the location of end users, reducing latency. - Mattermost does not support high availability deployments spanning multiple datacenters. All nodes in a high availability cluster must reside within the same datacenter to ensure proper functionality and performance. +Moreover, search replicas are also supported to handle search queries. + +.. image:: ../images/architecture_high_availability.png Deployment guide ---------------- @@ -54,7 +56,7 @@ Remove a server from the cluster ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. Back up your Mattermost database and the file storage location. See the :doc:`backup ` documentation for details. -2. Modify your NGINX setup to remove the server. For information about this, see :ref:`proxy server configuration ` documentation for details. +2. Modify your NGINX setup to remove the server. For information about this, see :ref:`proxy server configuration ` documentation for details. 3. Open **System Console > Environment > High Availability** to verify that all the machines remaining in the cluster are communicating as expected with green status indicators. If not, investigate the log files for any extra information. Configuration and compatibility @@ -530,6 +532,23 @@ All cluster traffic uses the gossip protocol. :ref:`Gossip clustering can no lon When upgrading a high availability cluster-based deployment, you can't upgrade other nodes in the cluster when one node isn't using the gossip protocol. You must use gossip to complete this type of upgrade. Alternatively you can shut down all nodes and bring them all up individually following an upgrade. +Requirements for continuous operation +------------------------------------- + +To enable continuous operation at all times, including during server updates and server upgrades, you must make sure that the redundant components are properly sized and that you follow the correct sequence for updating each of the system's components. + +Redundancy at anticipated scale + Upon failure of one component, the remaining application servers, database servers, and load balancers must be sized and configured to carry the full load of the system. If this requirement is not met, an outage of one component can result in an overload of the remaining components, causing a complete system outage. + +Update sequence for continuous operation + You can apply most configuration changes and dot release security updates without interrupting service, provided that you update the system components in the correct sequence. See the `upgrade guide`_ for instructions on how to do this. + + **Exception:** Changes to configuration settings that require a server restart, and server version upgrades that involve a change to the database schema, require a short period of downtime. Downtime for a server restart is around five seconds. For a database schema update, downtime can be up to 30 seconds. + +.. important:: + + Mattermost does not support high availability deployments spanning multiple datacenters. All nodes in a high availability cluster must reside within the same datacenter to ensure proper functionality and performance. + Frequently asked questions (FAQ) --------------------------------- @@ -562,7 +581,7 @@ You may be asked to provide this data to Mattermost for analysis and troubleshoo .. note:: - - Ensure that server log files are being created. You can find more on working with Mattermost logs :ref:`here `. + - Ensure that server log files are being created. You can find more on working with Mattermost logs :ref:`here `. - When investigating and replicating issues, we recommend opening **System Console > Environment > Logging** and setting **File Log Level** to **DEBUG** for more complete logs. Make sure to revert to **INFO** after troubleshooting to save disk space. - Each server has its own server log file, so make sure to provide server logs for all servers in your High Availability cluster-based deployment. diff --git a/source/scale/scale-to-200-users.rst b/source/scale/scale-to-200-users.rst index adaac48a889..635e0f6452d 100644 --- a/source/scale/scale-to-200-users.rst +++ b/source/scale/scale-to-200-users.rst @@ -53,4 +53,4 @@ We strongly recommend that you review storage utilization at least quarterly to Additional considerations ------------------------- -Smaller deployments, or deployments using the :doc:`Mattermost Omnibus installer `, will need an increase in resources due to the fact the database is hosted on the same server as the Mattermost application. \ No newline at end of file +Smaller deployments, or deployments using the :doc:`Mattermost Omnibus installer `, will need an increase in resources due to the fact the database is hosted on the same server as the Mattermost application. \ No newline at end of file diff --git a/source/scale/scaling-for-enterprise.rst b/source/scale/scaling-for-enterprise.rst index 4702ccb01db..d233d588e94 100644 --- a/source/scale/scaling-for-enterprise.rst +++ b/source/scale/scaling-for-enterprise.rst @@ -12,6 +12,21 @@ Server requirements vary based on usage and we highly recommend that you run a p Available reference architectures --------------------------------- +.. toctree:: + :maxdepth: 1 + :hidden: + :titlesonly: + + Scale up to 200 users + Scale up to 2000 users + Scale up to 15000 users + Scale up to 30000 users + Scale up to 50000 users + Scale up to 80000 users + Scale up to 90000 users + Scale up to 100000 users + Scale up to 200000 users + The following reference architectures are available as recommended starting points for your self-hosted Mattermost deployment, where user counts refer to the number of concurrent users for a given deployment. The number of concurrent numbers is commonly lower than the total number of user accounts. * :doc:`Scale up to 200 users ` - Learn how to scale Mattermost to up to 200 users. diff --git a/source/getting-started/admin-onboarding-tasks.rst b/source/upgrade/admin-onboarding-tasks.rst similarity index 97% rename from source/getting-started/admin-onboarding-tasks.rst rename to source/upgrade/admin-onboarding-tasks.rst index 20ce7f36a64..b8c0beb8e81 100644 --- a/source/getting-started/admin-onboarding-tasks.rst +++ b/source/upgrade/admin-onboarding-tasks.rst @@ -31,7 +31,7 @@ These settings can also be set in the ``config.json`` file. Please see our :doc - Users can be pre-provisioned with migration and bulk loading data processes based on prior collaboration systems. Please see our :ref:`migration guide ` and :doc:`bulk loading documentation ` for additional details. - :doc:`AD/LDAP authentication ` and :doc:`SAML authentication ` are available for some subscription plans, providing identity management, single sign-on, and automatic account provisioning. -If your organization requires more structure and project management artifacts for the implementation of Mattermost, please see our :doc:`Enterprise roll out checklist `. +If your organization requires more structure and project management artifacts for the implementation of Mattermost, please see our :doc:`Enterprise roll out checklist `. Important administration notes ------------------------------ @@ -115,7 +115,7 @@ Enable full content push notifications, including the sender’s name, the chann .. note:: - - Mattermost subscription plans allow you to :ref:`enable HPNS ` that includes production-level uptime SLAs. + - Mattermost subscription plans allow you to enable HPNS that includes production-level uptime SLAs. - Mattermost Enterprise customers can :ref:`enable ID-Only push notifications ` so push notification content is not passed through Apple Push Notification Service (APNS) or Google Firebase Cloud Messaging (FCM) before reaching the device. The ID-only push notification setting `offers a high level of privacy `__ while allowing team members to benefit from mobile push notifications. diff --git a/source/install/enterprise-install-upgrade.rst b/source/upgrade/enterprise-install-upgrade.rst similarity index 98% rename from source/install/enterprise-install-upgrade.rst rename to source/upgrade/enterprise-install-upgrade.rst index d959a250c23..c8ae9d6b389 100644 --- a/source/install/enterprise-install-upgrade.rst +++ b/source/upgrade/enterprise-install-upgrade.rst @@ -1,5 +1,3 @@ -.. _ee-install: - Enterprise install and upgrade =============================== @@ -13,7 +11,7 @@ Once you've downloaded and installed Mattermost, start an Enterprise trial via * Installing Enterprise Edition ----------------------------- -See the :doc:`Deploy Mattermost ` page to install Mattermost Enterprise Edition. +See the :doc:`Deploy Mattermost ` page to install Mattermost Enterprise Edition. Upgrading to Mattermost Enterprise Edition -------------------------------------------- diff --git a/source/getting-started/enterprise-roll-out-checklist.rst b/source/upgrade/enterprise-roll-out-checklist.rst similarity index 95% rename from source/getting-started/enterprise-roll-out-checklist.rst rename to source/upgrade/enterprise-roll-out-checklist.rst index ada0085623b..28f46c0e5e9 100644 --- a/source/getting-started/enterprise-roll-out-checklist.rst +++ b/source/upgrade/enterprise-roll-out-checklist.rst @@ -57,8 +57,6 @@ Much of the preparation work is focused on ensuring the environment is deployed - Resource: https://mattermost.com/blog/27-things-enterprises-can-learn-startups-increase-productivity/ - Define success criteria, goals and metrics to measure success - - - Resource: https://docs.mattermost.com/getting-started/implementation-plan.html - Create a Project Charter to document goals, tasks, deliverables, and decisions @@ -116,8 +114,8 @@ Much of the preparation work is focused on ensuring the environment is deployed - Finalize production environment design basing hardware on expected usage and requirements for high availability - - Resource: https://docs.mattermost.com/getting-started/architecture-overview.html - - Resource: https://docs.mattermost.com/deploy/deployment-overview.html + - Resource: https://docs.mattermost.com/deploy/application-architecture.html + - Resource: https://docs.mattermost.com/deploy/deployment-guide.html - Resource: https://docs.mattermost.com/scale/scaling-for-enterprise.html - Resource: https://docs.mattermost.com/scale/high-availability-cluster-based-deployment.html @@ -133,13 +131,13 @@ Much of the preparation work is focused on ensuring the environment is deployed - 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/install/install-kubernetes.html + - Resource: https://docs.mattermost.com/deploy/server/install-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/getting-started/architecture-overview.html#database-with-vips + - Resource: https://docs.mattermost.com/deploy/server/server-architecture.html#database-with-virtual-ips - (Optional) Set up configuration management via the database instead of a config file for high available environments @@ -147,7 +145,7 @@ Much of the preparation work is focused on ensuring the environment is deployed - Install and configure File Storage - - Resource: https://docs.mattermost.com/deploy/deployment-overview.html#file-store + - Resource: https://docs.mattermost.com/deploy/server/preparations.html#file-storage-preparation - Install and configure proxy or load balancers @@ -286,14 +284,14 @@ Now that you have an environment in place, we recommend working through the foll - Resource: https://docs.mattermost.com/deploy/desktop-app.html - (Optional) Use the MSI installer to install on Windows machines - - Resource: https://docs.mattermost.com/install/desktop-msi-installer-and-group-policy-install.html + - Resource: https://docs.mattermost.com/deploy/desktop/desktop-msi-installer-and-group-policy-install.html - Roll out mobile app - Resource: https://docs.mattermost.com/deploy/mobile-overview.html - (Optional) Use an EMM provider - - Resource: https://docs.mattermost.com/deploy/deploy-mobile-apps-using-emm-provider.html + - Resource: https://docs.mattermost.com/deploy/mobile/deploy-mobile-apps-using-emm-provider.html 5. Roll out to groups of users ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/upgrade/important-upgrade-notes.rst b/source/upgrade/important-upgrade-notes.rst index 51dca93d66f..0ca7b433920 100644 --- a/source/upgrade/important-upgrade-notes.rst +++ b/source/upgrade/important-upgrade-notes.rst @@ -2,15 +2,15 @@ Important Upgrade Notes ======================= .. important:: - + .. include:: ../about/common-esr-support-rst.rst - + .. note:: - Upgrading the Microsoft Teams Calling plugin to v2.0.0 requires users to reconnect their accounts. - Mattermost plugins built with Go versions 1.22.0 and 1.22.1 do not work. Plugin developers should use Go 1.22.2 or newer instead. - - Keybase has stopped serving our Ubuntu repository signing key. If you were using it, update your installation scripts to retrieve the key as mentioned in our docs: https://docs.mattermost.com/install/install-ubuntu.html. + - Keybase has stopped serving our Ubuntu repository signing key. If you were using it, update your installation scripts to retrieve the key as mentioned in our docs: https://docs.mattermost.com/deploy/server/deploy-linux. - MySQL 8.0.22 contains an `issue with JSON column types `__ changing string values to integers which is preventing Mattermost from working properly. Users are advised to avoid this database version. - When upgrading to 7.x from a 5.x release please make sure to upgrade to 5.37.10 first for the upgrade to complete successfully. @@ -19,7 +19,8 @@ Important Upgrade Notes | from a version earlier than... | | +====================================================+==================================================================================================================================================================+ | v10.6 | Support for PostgreSQL v11 and v12 have been removed. The new minimum PostgreSQL version is v13+. | -| | See the :ref:`minimum supported PostgreSQL version policy ` documentation for details. | +| | See the | +| | :ref:`minimum supported PostgreSQL version policy ` documentation for details. | | +------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | Migration times: On a system with 12M posts, and 1M fileinfo entries, the migration takes 15s. This migration is non-locking. Note that there is no migration | | | for MySQL deployments because this optimization is only applicable for PostgreSQL. | @@ -247,7 +248,7 @@ Important Upgrade Notes | v9.5 | We have stopped supporting MySQL v5.7 since it's at the end of life. We urge customers to upgrade their MySQL instance at their earliest convenience. | | +------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | Added safety limit error message in compiled Team Edition and Enterprise Edition deployments when enterprise scale and access control automation features are | -| | unavailable and count of users who are registered and not deactivated exceeds 10,000. :doc:`ERROR_SAFETY_LIMITS_EXCEEDED `. | +| | unavailable and count of users who are registered and not deactivated exceeds 10,000. :doc:`ERROR_SAFETY_LIMITS_EXCEEDED `. | +----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | v9.2 | Fixed data retention policies to run jobs when any custom retention policy is enabled even when the global retention policy is set to "keep-forever". Before | | | this fix, the enabled custom data retention policies wouldn't run as long as the global data retention policy was set to "keep-forever" or was disabled. After | @@ -828,7 +829,7 @@ Important Upgrade Notes | | conditions. Customers are requested to check for these values in their config and set them to nil if necessary. See more details | | | :ref:`here `. | +----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| v6.2 | Channel results in the channel autocomplete will include private channels. Customers using :doc:`Bleve ` or | +| v6.2 | Channel results in the channel autocomplete will include private channels. Customers using :doc:`Bleve ` or | | | :doc:`Elasticsearch ` for autocomplete will have to reindex their data to get the new results. Since this can | | | take a long time, we suggest disabling autocomplete and running indexing in the background. When this is complete, re-enable autocomplete. | | | | @@ -1017,7 +1018,7 @@ Important Upgrade Notes | v5.29.0 | A new configuration setting ``ThreadAutoFollow`` has been added to support `Collapsed Reply Threads | | | `__ releasing in beta in Q1 2021. This | | | setting is enabled by default and may affect server performance. It is recommended to review our :ref:`documentation on hardware requirements | -| | ` to ensure your servers are appropriately scaled for the size of your user base. | +| | ` to ensure your servers are appropriately scaled for the size of your user base. | | +------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | Disabled the xmlsec1-based SAML library in favor of the re-enabled and improved SAML library. | +----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -1195,7 +1196,7 @@ Important Upgrade Notes | | :ref:`See documentation ` for additional information. | +----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | v5.8.0 | The local image proxy has been added, and images displayed within the client are now affected by the ``AllowUntrustedInternalConnections`` setting. | -| | :ref:`See documentation ` for more details if you have trouble loading images. | +| | :ref:`See documentation ` for more details if you have trouble loading images. | +----------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | v5.6.0 | Built-in WebRTC is removed. See `here for more details `__. | diff --git a/source/upgrade/prepare-to-upgrade-mattermost.rst b/source/upgrade/prepare-to-upgrade-mattermost.rst index 2997445051b..f393f83fefb 100644 --- a/source/upgrade/prepare-to-upgrade-mattermost.rst +++ b/source/upgrade/prepare-to-upgrade-mattermost.rst @@ -4,7 +4,7 @@ Prepare to upgrade Mattermost .. include:: ../_static/badges/allplans-selfhosted.rst :start-after: :nosearch: -In most cases, you can :doc:`upgrade Mattermost Server ` in a few minutes. However, the upgrade can take longer depending on several factors, including the size and complexity of your installation, and the version that you're upgrading from. When planning an upgrade, it's worth confirming that your current database and operating system version are still supported. Details can be found on our :ref:`software and hardware requirements ` page. +In most cases, you can :doc:`upgrade Mattermost Server ` in a few minutes. However, the upgrade can take longer depending on several factors, including the size and complexity of your installation, and the version that you're upgrading from. When planning an upgrade, it's worth confirming that your current database and operating system version are still supported. Details can be found on our :ref:`software and hardware requirements ` page. Upgrade Best Practices ---------------------- diff --git a/source/upgrade/upgrading-mattermost-server.rst b/source/upgrade/upgrading-mattermost-server.rst index e7147969e4d..8857af046a1 100644 --- a/source/upgrade/upgrading-mattermost-server.rst +++ b/source/upgrade/upgrading-mattermost-server.rst @@ -16,7 +16,7 @@ Before you begin **Read these instructions carefully from start to finish.** -Make sure that you understand how to :doc:`prepare for your upgrade `, familiarize yourself with all :doc:`software and hardware requirements `, read the :doc:`important upgrade notes ` and that you understand each step of the upgrade process documented below before starting a Mattermost upgrade. If you have questions or concerns, you can ask on the Mattermost forum at https://forum.mattermost.com/. +Make sure that you understand how to :doc:`prepare for your upgrade `, familiarize yourself with all :doc:`software and hardware requirements `, read the :doc:`important upgrade notes ` and that you understand each step of the upgrade process documented below before starting a Mattermost upgrade. If you have questions or concerns, you can ask on the Mattermost forum at https://forum.mattermost.com/. **Gather the following information before starting the upgrade:** @@ -131,7 +131,7 @@ Upgrade Mattermost Server sudo find mattermost/ mattermost/client/ -mindepth 1 -maxdepth 1 \! \( -type d \( -path mattermost/client -o -path mattermost/client/plugins -o -path mattermost/config -o -path mattermost/logs -o -path mattermost/plugins -o -path mattermost/data -o -path mattermost/yourFolderHere \) -prune \) | sort - d. If you're using :doc:`Bleve search `, and the directory exists *within* the ``mattermost`` directory, the index directory path won't be preserved using the command above. + d. If you're using :doc:`Bleve search `, and the directory exists *within* the ``mattermost`` directory, the index directory path won't be preserved using the command above. - You can either move the bleve index directory out from the ``mattermost`` directory before upgrading or, following an upgrade, you can copy the contents of the bleve index directory from the ``backup`` directory. - You can then store that directory or re-index as preferred. diff --git a/source/getting-started/welcome-email-to-end-users.rst b/source/upgrade/welcome-email-to-end-users.rst similarity index 100% rename from source/getting-started/welcome-email-to-end-users.rst rename to source/upgrade/welcome-email-to-end-users.rst