snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)
Some checks failed
Server CI / Postgres (shard 0) (push) Has been skipped
Server CI / Postgres (shard 3) (push) Has been skipped
BuildEnv Docker Image / build-image (push) Failing after 4s
BuildEnv Docker Image / build-image-fips (push) Failing after 4s
Migration Review & Release Notes / Generate migration review & release notes (push) Failing after 3s
Server CI / Build Environment (push) Failing after 3s
Server CI / Postgres (shard 1) (push) Has been skipped
Tools CI / check-style (mattermost-govet) (push) Failing after 4s
Server CI / Postgres (shard 2) (push) Has been skipped
Tools CI / check-style (mmgotool) (push) Failing after 3s
Server CI / Elasticsearch v8 Compatibility (push) Has been skipped
Server CI / OpenSearch v2 Compatibility (push) Has been skipped
Server CI / Postgres FIPS (shard 0) (push) Has been skipped
Tools CI / Test (mattermost-govet) (push) Failing after 3s
Server CI / Postgres FIPS (shard 1) (push) Has been skipped
Server CI / Postgres FIPS (shard 2) (push) Has been skipped
Tools CI / Test (mmgotool) (push) Failing after 3s
Server CI / Postgres FIPS (shard 3) (push) Has been skipped
Server CI / Run mmctl tests (push) Has been skipped
Server CI / Run mmctl tests (FIPS) (push) Has been skipped
Server CI / Merge Postgres Test Results (push) Has been skipped
Server CI / Merge Postgres FIPS Test Results (push) Has been skipped
Server CI / Check backport migrations (push) Has been skipped
Server CI / Check generated files (push) Has been skipped
Server CI / check-style (push) Has been skipped
Server CI / Vet API (push) Has been skipped
Server CI / Build mattermost server app (push) Has been skipped
Server CI / Server CI Complete (push) Failing after 2s
Server CI / Server CI Artifacts (push) Has been skipped
Server CI / Sentry Upload (push) Has been skipped
Server CI / Server CI Report (push) Failing after 5m1s
Server CI Nightly Race / Race Detector (push) Has been skipped
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (javascript) (push) Has been cancelled
Webapp CI Cache Warm / Warm Webapp node_modules Cache (push) Has been cancelled
E2E CI Cache Warm / Warm E2E npm Registry Cache (push) Has been cancelled
API / build (push) Has been cancelled
Web App CI / check-types (push) Has been cancelled
Web App CI / check-lint (push) Has been cancelled
Web App CI / check-i18n (push) Has been cancelled
Web App CI / check-external-links (push) Has been cancelled
Web App CI / test (platform) (push) Has been cancelled
Web App CI / test (mattermost-redux) (push) Has been cancelled
Web App CI / test (channels shard 1/4) (push) Has been cancelled
Web App CI / test (channels shard 2/4) (push) Has been cancelled
Web App CI / test (channels shard 3/4) (push) Has been cancelled
Web App CI / test (channels shard 4/4) (push) Has been cancelled
Web App CI / upload-coverage (push) Has been cancelled
Web App CI / build (push) Has been cancelled
YAML Lint / yamllint (push) Has been cancelled
Push mirrored docker images / cd/Push mirrored docker images (push) Has been cancelled
docs-cd / Build and deploy docs (push) Has been cancelled
Docs CI / build (push) Has been cancelled
E2E Cache Warm: Cypress deps / Warm Cypress deps cache (push) Has been cancelled
Scorecards supply-chain security / Scorecard analysis (push) Has been cancelled
Server CI Weekly / Postgres FIPS (push) Has been skipped
Server CI Weekly / Run mmctl tests (FIPS) (push) Has been skipped
Server CI Weekly / Postgres with binary parameters (push) Has been skipped
Server CI Weekly / Build Environment (push) Failing after 1s
Server CI Cache Warm / Warm Go Module and Build Cache (push) Failing after 2s
Server CI Nightly Race / Build Environment (push) Failing after 1s
Some checks failed
Server CI / Postgres (shard 0) (push) Has been skipped
Server CI / Postgres (shard 3) (push) Has been skipped
BuildEnv Docker Image / build-image (push) Failing after 4s
BuildEnv Docker Image / build-image-fips (push) Failing after 4s
Migration Review & Release Notes / Generate migration review & release notes (push) Failing after 3s
Server CI / Build Environment (push) Failing after 3s
Server CI / Postgres (shard 1) (push) Has been skipped
Tools CI / check-style (mattermost-govet) (push) Failing after 4s
Server CI / Postgres (shard 2) (push) Has been skipped
Tools CI / check-style (mmgotool) (push) Failing after 3s
Server CI / Elasticsearch v8 Compatibility (push) Has been skipped
Server CI / OpenSearch v2 Compatibility (push) Has been skipped
Server CI / Postgres FIPS (shard 0) (push) Has been skipped
Tools CI / Test (mattermost-govet) (push) Failing after 3s
Server CI / Postgres FIPS (shard 1) (push) Has been skipped
Server CI / Postgres FIPS (shard 2) (push) Has been skipped
Tools CI / Test (mmgotool) (push) Failing after 3s
Server CI / Postgres FIPS (shard 3) (push) Has been skipped
Server CI / Run mmctl tests (push) Has been skipped
Server CI / Run mmctl tests (FIPS) (push) Has been skipped
Server CI / Merge Postgres Test Results (push) Has been skipped
Server CI / Merge Postgres FIPS Test Results (push) Has been skipped
Server CI / Check backport migrations (push) Has been skipped
Server CI / Check generated files (push) Has been skipped
Server CI / check-style (push) Has been skipped
Server CI / Vet API (push) Has been skipped
Server CI / Build mattermost server app (push) Has been skipped
Server CI / Server CI Complete (push) Failing after 2s
Server CI / Server CI Artifacts (push) Has been skipped
Server CI / Sentry Upload (push) Has been skipped
Server CI / Server CI Report (push) Failing after 5m1s
Server CI Nightly Race / Race Detector (push) Has been skipped
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (javascript) (push) Has been cancelled
Webapp CI Cache Warm / Warm Webapp node_modules Cache (push) Has been cancelled
E2E CI Cache Warm / Warm E2E npm Registry Cache (push) Has been cancelled
API / build (push) Has been cancelled
Web App CI / check-types (push) Has been cancelled
Web App CI / check-lint (push) Has been cancelled
Web App CI / check-i18n (push) Has been cancelled
Web App CI / check-external-links (push) Has been cancelled
Web App CI / test (platform) (push) Has been cancelled
Web App CI / test (mattermost-redux) (push) Has been cancelled
Web App CI / test (channels shard 1/4) (push) Has been cancelled
Web App CI / test (channels shard 2/4) (push) Has been cancelled
Web App CI / test (channels shard 3/4) (push) Has been cancelled
Web App CI / test (channels shard 4/4) (push) Has been cancelled
Web App CI / upload-coverage (push) Has been cancelled
Web App CI / build (push) Has been cancelled
YAML Lint / yamllint (push) Has been cancelled
Push mirrored docker images / cd/Push mirrored docker images (push) Has been cancelled
docs-cd / Build and deploy docs (push) Has been cancelled
Docs CI / build (push) Has been cancelled
E2E Cache Warm: Cypress deps / Warm Cypress deps cache (push) Has been cancelled
Scorecards supply-chain security / Scorecard analysis (push) Has been cancelled
Server CI Weekly / Postgres FIPS (push) Has been skipped
Server CI Weekly / Run mmctl tests (FIPS) (push) Has been skipped
Server CI Weekly / Postgres with binary parameters (push) Has been skipped
Server CI Weekly / Build Environment (push) Failing after 1s
Server CI Cache Warm / Warm Go Module and Build Cache (push) Failing after 2s
Server CI Nightly Race / Build Environment (push) Failing after 1s
This commit is contained in:
upstream-mirror
@@ -0,0 +1,68 @@
|
||||
---
|
||||
title: "Desktop App Deployment"
|
||||
---
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
The Mattermost desktop app is available for Windows, macOS, and Linux operating systems, and offers [additional functionality](/end-user-guide/preferences/customize-desktop-app-experience) beyond the web-based experience.
|
||||
|
||||
Learn more about desktop app [software requirements](/deployment-guide/software-hardware-requirements#desktop-apps), [releases and server compatibility](/product-overview/mattermost-desktop-releases) as well as [what's changed across releases](/product-overview/desktop-app-changelog).
|
||||
|
||||
<Note>
|
||||
|
||||
Hitting problems with an installation or rollout? See [Desktop app troubleshooting](/deployment-guide/desktop/desktop-troubleshooting) at the end of this section, or [Deployment troubleshooting](/deployment-guide/server/troubleshooting) if the problem might not be specific to the desktop app.
|
||||
|
||||
</Note>
|
||||
|
||||
## Download
|
||||
|
||||
Download and install the Mattermost desktop app from the [App Store (macOS)](https://www.apple.com/app-store/), [Microsoft Store (Windows)](https://apps.microsoft.com/home?hl=en-US&gl=US), or by [using a package manager (Linux)](/deployment-guide/desktop/linux-desktop-install). We strongly recommend installing the desktop app on a local drive. Network shares aren't supported.
|
||||
|
||||
In Matermost, users are notified under **Downloads** when new desktop app releases become available. If managing the distribution of the Desktop app on behalf of users, you can recommend that your users disable desktop update notifications by going to **… \> File \> Settings** on Windows or **Mattermost \> Settings** on Mac and clearing the **Automatically check for updates** option.
|
||||
|
||||
See additional deployment options below to manage distribution of the desktop app to your users.
|
||||
|
||||
### Windows distribution channels
|
||||
|
||||
From desktop v6.1, organizations deploying on Windows have 2 primary distribution options:
|
||||
|
||||
- **Windows Store** (recommended): Provides automatic updates through the Microsoft Store infrastructure. This is the recommended option for most organizations seeking streamlined update management.
|
||||
- **MSI packages**: Traditional deployment method with full control over installation timing. See the [MSI installer and group policy guide](/deployment-guide/desktop/desktop-msi-installer-and-group-policy-install) documentation for details.
|
||||
|
||||
The desktop v6.1 app includes in-app update notifications. All distribution channels (Windows Store, MSI, Mac App Store, Flathub, APT/RPM) release simultaneously to prevent notification and availability mismatches across deployment methods.
|
||||
|
||||
## Deployment options
|
||||
|
||||
Learn about installation, configuration, and management options for deploying the desktop app in your environment.
|
||||
|
||||
- [Distribute a custom desktop app](/deployment-guide/desktop/distribute-a-custom-desktop-app)
|
||||
- [Silent Windows desktop distribution](/deployment-guide/desktop/silent-windows-desktop-distribution)
|
||||
- [MSI installer and group policy guide](/deployment-guide/desktop/desktop-msi-installer-and-group-policy-install)
|
||||
- [Custom dictionaries for Windows and Linux](/deployment-guide/desktop/desktop-custom-dictionaries)
|
||||
- [Managed resources for the desktop app](/deployment-guide/desktop/desktop-app-managed-resources)
|
||||
|
||||
## Privacy and data handling
|
||||
|
||||
### Error reporting
|
||||
|
||||
From Mattermost Desktop v6.1, the desktop app includes automatic error reporting to help identify and fix crashes and stability issues.
|
||||
|
||||
**What information is sent**
|
||||
|
||||
Error reports include:
|
||||
|
||||
- Crash information and stack traces
|
||||
- App version and platform details (OS type, architecture)
|
||||
- Error messages and context
|
||||
|
||||
**What is NOT sent**
|
||||
|
||||
- Message content or user communications
|
||||
- User credentials, passwords, or authentication tokens
|
||||
- Personally identifiable information (PII)
|
||||
- Server URLs or team names
|
||||
|
||||
**Privacy and user control**
|
||||
|
||||
Error reporting is **enabled by default**. Users can disable it at any time by going to **Settings \> Advanced \> Send error reports to help improve the app**. Restart the app to apply the change.
|
||||
|
||||
Organizations with data handling policies should inform users about this feature and provide guidance on whether to disable it. For organizations building the Desktop app from source, error reporting can be disabled at build time by omitting the `MM_DESKTOP_BUILD_SENTRYDSN` environment variable.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: "Desktop managed resources"
|
||||
---
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
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 <code>custom build of the Mattermost desktop app \</deployment-guide/desktop/distribute-a-custom-desktop-app\></code>.
|
||||
|
||||
</Note>
|
||||
|
||||
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.
|
||||
|
||||
In addition to customizing the Mattermost Desktop App, the [Managed Resource Paths](/administration-guide/configure/environment-configuration-settings#managed-resource-paths) setting on the Mattermost server must be configured.
|
||||
|
||||
In the below example we add the managed resource `/video`.
|
||||
|
||||
``` text
|
||||
[...]
|
||||
managedResources: ['trusted', 'video'],
|
||||
[...]
|
||||
```
|
||||
|
||||
Here are two example server URLs each with valid and invalid managed resource URLs:
|
||||
|
||||
- Mattermost server: `https://mattermost.my.org`
|
||||
- A valid video service: `https://mattermost.my.org/video`
|
||||
- A valid conference service: `https://mattermost.my.org/conference`
|
||||
- An invalid video service using a different protocol: `http://mattermost.my.org/video`
|
||||
- An invalid conference service having a different origin: `https://conference.my.org`
|
||||
- Mattermost server: `https://my.org/mattermost`
|
||||
- A valid video service: `https://my.org/video`
|
||||
- A valid conference service: `https://my.org/conference`
|
||||
- An invalid video service using a different protocol: `http://my.org/video`
|
||||
- An invalid conference service having a different origin: `https://conference.my.org`
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: "Desktop App custom dictionaries"
|
||||
---
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
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
|
||||
|
||||
On Windows and Linux, the Mattermost desktop app uses [Hunspell Dictionary definitions](https://hunspell.github.io/) by default. You can download a copy of these dictionary definitions and modify them to fit specific needs.
|
||||
|
||||
To access a copy of these dictionary definitions:
|
||||
|
||||
1. Download a copy of `hunspell_dictionaries.zip` from the [latest electron release](https://github.com/electron/electron/releases/latest).
|
||||
2. Extract the dictionary definitions from the ZIP file.
|
||||
3. Convert the filenames to lowercase. (Chromium expects `en-us` rather than `en-US`). Once renamed, these definition files match the usage of using Chromium's CDN ones, and you can modify the definitions as needed.
|
||||
4. Serve the extracted and converted files from a web server, and note the URL to the root folder of the dictionaries. Specify this URL as the **alternate dictionary URL** in the desktop app.
|
||||
|
||||
## Configure the Desktop App
|
||||
|
||||
1. In the Mattermost Desktop App, go to Settings by selecting <img src={useBaseUrl('/img/ui/dots-vertical_F01D9.svg')} alt="Use the More icon in the top left corner to access Mattermost desktop apps customization settings." className="theme-icon" /> **\> File \> Settings**.
|
||||
2. Under **App Options**, ensure that the **Check spelling** option is enabled.
|
||||
3. Select **Use an alternative dictionary URL** to specify the URL to the root folder of your custom dictionaries, then select **Save**.
|
||||
|
||||
## Remove custom dictionaries
|
||||
|
||||
Select **Revert to default** to stop using the specified dictionary definitions, and revert to default dictionary definitions.
|
||||
@@ -0,0 +1,243 @@
|
||||
---
|
||||
title: "Desktop MSI installer and group policy guide"
|
||||
---
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
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](https://github.com/mattermost/desktop/releases/latest).
|
||||
|
||||
<Important>
|
||||
|
||||
**Per-machine installation from v6.1.0**: From Mattermost Desktop v6.1.0, the Windows MSI installer defaults to per-machine (system-wide) installation to meet enterprise compliance requirements. This changes deployment strategies and upgrade paths. See the [Deployment considerations for v6.1.0+](#deployment-considerations-for-v610) section below for details.
|
||||
|
||||
</Important>
|
||||
|
||||
## Windows distribution options
|
||||
|
||||
From desktop v6.1, organizations deploying on Windows have 2 primary distribution options:
|
||||
|
||||
- **Windows Store**: Primary option for automatic updates. Recommended for most users. The Windows Store version handles updates automatically through the Microsoft Store infrastructure.
|
||||
- **MSI installer**: Direct download option for traditional deployment methods. This guide covers MSI deployment.
|
||||
|
||||
The desktop v6.1 app includes in-app update notifications that check the Mattermost website for new versions. All distribution channels (Windows Store, MSI, Mac App Store, Flathub, APT/RPM) release simultaneously to ensure users receive consistent update notifications regardless of their installation method.
|
||||
|
||||
## Upgrading to v6.1.0 with MSI installer
|
||||
|
||||
Users upgrading from earlier Desktop app versions using the MSI installer may need to recreate taskbar shortcuts once after the upgrade. The v6.1.0 installer uses a more reliable method for shortcut icons that prevents shortcuts from breaking during future upgrades. This fixes a long-standing issue where shortcuts could break during MSI upgrades. This is a one-time action for the upgrade to v6.1.0. Future upgrades to v6.1.2 and later won't require shortcut recreation. Windows Store deployments aren't affected by this change.
|
||||
|
||||
We recommend telling your users in advance that they may need to re-pin the taskbar shortcut after upgrading to desktop app v6.1. Desktop shortcuts are typically unaffected while taskbar shortcuts are most commonly impacted.
|
||||
|
||||
If a user reports a broken shortcut after upgrading to v6.1.0, the user should:
|
||||
|
||||
1. Right-click the broken shortcut on the taskbar and select **Unpin from taskbar**.
|
||||
2. Launch Mattermost Desktop from the Start Menu.
|
||||
3. Right-click the Mattermost icon in the taskbar.
|
||||
4. Select **Pin to taskbar**.
|
||||
|
||||
## 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).
|
||||
|
||||
|
||||
|
||||
2. Navigate to the [Mattermost Desktop](https://github.com/mattermost/desktop) repository on [GitHub.com](https://github.com/).
|
||||
|
||||
|
||||
|
||||
3. Navigate to the release page for [version v6.3.0](https://github.com/mattermost/desktop/releases/tag/v6.3.0) and download the appropriate installer for your version of Windows (32-bit vs. 64-bit).
|
||||
|
||||
4. Download the [source.zip](https://github.com/mattermost/desktop/archive/v6.3.0.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:
|
||||
|
||||
> <table style={{width: '99%'}}>
|
||||
> <colgroup>
|
||||
> <col style={{width: '19%'}} />
|
||||
> <col style={{width: '42%'}} />
|
||||
> <col style={{width: '16%'}} />
|
||||
> <col style={{width: '20%'}} />
|
||||
> </colgroup>
|
||||
> <thead>
|
||||
> <tr>
|
||||
> <th>Group policy</th>
|
||||
> <th>Description</th>
|
||||
> <th>Mattermost release</th>
|
||||
> <th>Setting</th>
|
||||
> </tr>
|
||||
> </thead>
|
||||
> <tbody>
|
||||
> <tr>
|
||||
> <td>Enable Server Management</td>
|
||||
> <td>If disabled, management of servers in the app settings are disabled.</td>
|
||||
> <td>v4.3 or later</td>
|
||||
> <td><code>EnableServerManagement</code></td>
|
||||
> </tr>
|
||||
> <tr>
|
||||
> <td>Default Server List</td>
|
||||
> <td>Define one or more default, permanent servers.</td>
|
||||
> <td>v4.3 or later</td>
|
||||
> <td><code>DefaultServerList</code></td>
|
||||
> </tr>
|
||||
> <tr>
|
||||
> <td>Update Notifications</td>
|
||||
> <td>If disabled, in-app update notifications are not shown.</td>
|
||||
> <td>v5.1 or later</td>
|
||||
> <td><code>EnableAutoUpdater</code></td>
|
||||
> </tr>
|
||||
> </tbody>
|
||||
> </table>
|
||||
|
||||
1. Browse to the folder the above files were downloaded to and unzip the `desktop-6.3.0.zip` file in place.
|
||||
|
||||
|
||||
|
||||
2. Navigate to the unzipped `desktop-6.3.0\resources\windows\gpo` folder and copy the contents.
|
||||
|
||||
|
||||
|
||||
3. Navigate to the `C:\Windows\PolicyDefinitions` folder and paste the files copied in the last step.
|
||||
|
||||
|
||||
|
||||
4. Verify the `mattermost.admx` file is in the `C:\Windows\PolicyDefinitions` folder.
|
||||
|
||||
|
||||
|
||||
5. Verify the `mattermost.adml` file is in the `C:\Windows\PolicyDefinitions\en-US` folder.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
|
||||
- `\\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.
|
||||
|
||||
</Note>
|
||||
|
||||
**Disable update notifications**
|
||||
|
||||
Update notifications 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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](https://community.mattermost.com)).
|
||||
|
||||
5. Select **OK** twice, then close the **Edit group policy** app.
|
||||
|
||||
|
||||
|
||||
## Deployment considerations for v6.1.0+
|
||||
|
||||
From Mattermost Desktop v6.1.0, the Windows MSI installer defaults to per-machine (system-wide) installation to meet enterprise compliance requirements. The application installs to `C:\Program Files\Mattermost` with registry keys in `HKLM` (HKEY_LOCAL_MACHINE), and requires administrator privileges for deployment.
|
||||
|
||||
Users upgrading from v5.9 to v6.0.4 with per-user installations must manually uninstall the old version before installing v6.1.0 to avoid duplicate installs. See [Desktop troubleshooting](./desktop-troubleshooting#upgrade-to-v610-fails-or-installs-duplicate-version-windows-msi) for detailed upgrade instructions.
|
||||
|
||||
## Multi-view and Group Policies
|
||||
|
||||
From desktop v6.0, users can run multiple Mattermost workspaces at the same time in the desktop app. Use existing methods to pre-provision multiple workspaces for users, as follows:
|
||||
|
||||
- On Windows, seed the approved list using the `DefaultServerList` Group Policy.
|
||||
- For scripted installs, seed `config.json` on first run to include multiple entries in the `teams` array. See the [Silent Windows desktop distribution](/deployment-guide/desktop/silent-windows-desktop-distribution) documentation for details.
|
||||
- To prevent users from adding or removing workspaces, use the existing `EnableServerManagement` Group Policy.
|
||||
- Disable `EnableAutoUpdater` to turn off update notifications.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
|
||||
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**.
|
||||
|
||||
|
||||
|
||||
## Install the Mattermost Desktop App using the MSI installer
|
||||
|
||||
<Important>
|
||||
|
||||
- If the desktop app is running when you install via the MSI, Mattermost prompts you to close the app manually. After acknkowledging the prompt, select **Retry** to continue the MSI installation.
|
||||
- Avoid selecting **Ignore**. If you do, force close the desktop app using Task Manager, ensure the `Mattermost.exe` process is stopped, and then restart the MSI installation.
|
||||
|
||||
</Important>
|
||||
|
||||
1. Within the folder the MSI installer was downloaded to, double-click on the MSI installer to begin the Mattermost Desktop 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.
|
||||
|
||||
|
||||
|
||||
3. Select **Finish** when the installation is complete.
|
||||
|
||||
|
||||
|
||||
### Verify group policy settings in the installed desktop app
|
||||
|
||||
1. Launch the newly installed Mattermost app from the **Start** menu.
|
||||
|
||||
2. Verify the app loads the first server you defined in the **Edit group policy** app.
|
||||
|
||||
|
||||
|
||||
## Advanced MSI options
|
||||
|
||||
<Important>
|
||||
|
||||
You must be a system admin to run these commands, or you must run them from an admin command prompt or PowerShell.
|
||||
|
||||
</Important>
|
||||
|
||||
### Silent installation
|
||||
|
||||
Perform a silent installation of the MSI by running the following command:
|
||||
|
||||
<Important>
|
||||
|
||||
Ensure the desktop app is closed before proceeding with a silent installation. Because it's a silent installation, Mattermost won't prompt you to close the desktop app.
|
||||
|
||||
</Important>
|
||||
|
||||
**Command Prompt:** `msiexec /i mattermost-desktop-v6.3.0-x64.msi /qn`
|
||||
|
||||
**PowerShell:** `Start-Process -FilePath "$env:systemroot\system32\msiexec.exe" -ArgumentList '/i mattermost-desktop-v6.3.0-x64.msi /qn'`
|
||||
|
||||
<Note>
|
||||
|
||||
\- Replace `<version>` with the actual version number (e.g., `v6.3.0`). - From v6.1.0, the MSI installs per-machine by default, requiring administrator privileges.
|
||||
|
||||
</Note>
|
||||
|
||||
From version v5.9.0 of the Mattermost desktop app, the following silent MSI installation options are also available.
|
||||
|
||||
### Specify an install directory
|
||||
|
||||
Use the `APPLICATIONFOLDER` parameter to specify an installation directory for the MSI installation:
|
||||
|
||||
- **Command Prompt:** `msiexec /i mattermost-desktop-v6.3.0-x64.msi APPLICATIONFOLDER="<install directory>"`
|
||||
- **PowerShell:** `Start-Process -FilePath "$env:systemroot\system32\msiexec.exe" -ArgumentList '/i mattermost-desktop-v6.3.0-x64.msi APPLICATIONFOLDER="<install directory>"'`
|
||||
|
||||
Change this command as new versions of the Mattermost Desktop App are released.
|
||||
|
||||
## macOS managed configuration (MDM)
|
||||
|
||||
From Mattermost Desktop v6.2.0, admins can manage supported Desktop App configuration on macOS using managed preferences delivered through an MDM solution, in addition to the Windows group policy support described above. macOS managed preferences support the same configuration items as the Windows group policies listed in the [Install group policy files locally](#install-group-policy-files-locally) section, including predefined server lists, server management controls, and update notification controls.
|
||||
|
||||
To apply managed configuration on macOS, deploy a configuration profile that sets the supported keys to client Macs through your MDM solution. The Mattermost Desktop App reads managed preference values on launch; restart the app after changing managed configuration for new values to take effect.
|
||||
229
docs/main/deployment-guide/desktop/desktop-troubleshooting.mdx
Normal file
229
docs/main/deployment-guide/desktop/desktop-troubleshooting.mdx
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
title: "Desktop app troubleshooting"
|
||||
---
|
||||
## Broken shortcuts after upgrading to v6.1.0 (Windows MSI only)
|
||||
|
||||
After upgrading to Mattermost Desktop v6.1.0 using the Windows MSI installer from an older release, the desktop or taskbar shortcut shows the wrong icon or fails to launch. This is due to a one-time icon handling change in the Windows MSI installer to improve shortcut reliability for future upgrades.
|
||||
|
||||
This issue doesn't block app usage and only affects Windows MSI installer upgrades from pre-v6.1.0 versions. Users can launch Mattermost from the Start Menu or a working desktop shortcut.Future upgrades to v6.1.1 and later will not require shortcut recreation.
|
||||
|
||||
To resolve this issue, recreate the shortcut:
|
||||
|
||||
1. Right-click the broken shortcut on the taskbar and select **Unpin from taskbar**.
|
||||
2. Launch Mattermost Desktop from the Start Menu or a working desktop shortcut.
|
||||
3. Right-click the Mattermost icon in the taskbar while the application is running.
|
||||
4. Select **Pin to taskbar**.
|
||||
|
||||
The new shortcut will work correctly for all future upgrades.
|
||||
|
||||
Organizations standardizing on Windows installations can choose between Windows Store (recommended for automatic updates) or MSI packages (traditional deployment). The MSI method includes this one-time shortcut adjustment; the Windows Store method doesn't.
|
||||
|
||||
## 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\<username>\AppData\Roaming\Mattermost`
|
||||
- macOS installer: `/Users/<username>/Library/Application Support/Mattermost`
|
||||
- macOS App Store: `/Users/<username>/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**.
|
||||
|
||||
</Note>
|
||||
|
||||
## Update notifications not appearing
|
||||
|
||||
If you're not seeing in-app update notifications when new versions are available:
|
||||
|
||||
1. **Check your internet connection**: Ensure outbound HTTPS communication to `mattermost.com` is allowed.
|
||||
2. **Manually check for updates**: Go to **Help \> Check for Updates** or **Settings \> General \> Check for Updates Now** to trigger an immediate check.
|
||||
3. **Verify update notifications are enabled**:
|
||||
- On Windows: Go to **… \> File \> Settings** and ensure **Automatically check for updates** is enabled.
|
||||
- On macOS: Go to **Mattermost \> Settings** and ensure **Automatically check for updates** is enabled.
|
||||
4. **Check Group Policy settings** (Enterprise deployments): Your system administrator may have disabled update notifications via the `EnableAutoUpdater` Group Policy. Contact your IT department for clarification.
|
||||
5. **Version previously skipped**: If you selected **Skip This Version** for the current release, manually check for updates to see it again.
|
||||
|
||||
## Update required screen
|
||||
|
||||
From Mattermost server v11.6.0, system admins can set a minimum Desktop App version in **System Console \> Site Configuration \> Customization \> Minimum desktop app version**. If your Desktop App version is below the configured minimum, you will see an update required screen and cannot access Mattermost until you update.
|
||||
|
||||
The screen includes a **Download** button that links to the apps download page configured by your admin. Select **Download** to go to that page, then follow the [manual update steps](/deployment-guide/desktop/desktop-troubleshooting#how-to-manually-update-mattermost-desktop) for your platform.
|
||||
|
||||
If you believe your app is already up to date, contact your system admin to confirm the configured minimum version.
|
||||
|
||||
## How to manually update Mattermost Desktop
|
||||
|
||||
From v6.1.0, Mattermost Desktop updates are manual. Follow these steps for your platform:
|
||||
|
||||
**macOS (App Store)**:
|
||||
|
||||
1. Open the App Store application.
|
||||
2. Go to **Updates** section.
|
||||
3. Find Mattermost Desktop and select **Update**.
|
||||
|
||||
**macOS (DMG installation)**:
|
||||
|
||||
1. Download the latest DMG from [https://mattermost.com/download](https://mattermost.com/download) or the [GitHub releases page](https://github.com/mattermost/desktop/releases/latest).
|
||||
2. Open the downloaded DMG file.
|
||||
3. Drag the Mattermost application to your Applications folder, replacing the existing version.
|
||||
4. Restart Mattermost Desktop.
|
||||
|
||||
**Windows (Microsoft Store)**:
|
||||
|
||||
1. Open the Microsoft Store application.
|
||||
2. Go to **Library \> Get updates**.
|
||||
3. Find Mattermost and select **Update**.
|
||||
|
||||
**Windows (MSI installation)**:
|
||||
|
||||
1. Download the latest MSI installer from the [GitHub releases page](https://github.com/mattermost/desktop/releases/latest).
|
||||
2. Run the MSI installer.
|
||||
3. Follow the installation prompts (it will upgrade your existing installation).
|
||||
|
||||
**Linux**:
|
||||
|
||||
1. Visit the [GitHub releases page](https://github.com/mattermost/desktop/releases/latest).
|
||||
2. Download the appropriate package for your distribution (AppImage, .deb, .rpm, Flatpak, etc.).
|
||||
3. Install using your package manager or standard installation method.
|
||||
|
||||
<Tip>
|
||||
|
||||
For AppImage users: Simply download the new AppImage file and replace the old one. Make sure to make it executable: `chmod +x mattermost-desktop-*.AppImage`
|
||||
|
||||
</Tip>
|
||||
|
||||
## 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.
|
||||
|
||||
## Deep links open in the wrong workspace in multi-view
|
||||
|
||||
If you experience deep links opening in the wrong workspace, ensure all relevant workspaces are pre-provisioned via the Group Policy `DefaultServerList`. See the [multi-view and group policies](/deployment-guide/desktop/desktop-msi-installer-and-group-policy-install#multi-view-and-group-policies) documentation for details.
|
||||
|
||||
- Verify that workspace URLs match exactly (including protocol and subdomain) so links route to the intended workspace.
|
||||
- Edit the workspace list to correct or remove stale entries, then retry the link.
|
||||
|
||||
## High CPU or memory when multiple workspaces open
|
||||
|
||||
Verify the device is powerful enough to run several workspaces concurrently. Close unused tabs and pop-out windows to reduce load.
|
||||
|
||||
Check the [desktop app advanced settings](/end-user-guide/preferences/customize-desktop-app-experience). Toggle **Use GPU hardware acceleration** off on systems with unstable drivers.
|
||||
|
||||
## 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.
|
||||
|
||||
## Upgrade to v6.1.0 fails or installs duplicate version (Windows MSI)
|
||||
|
||||
After installing v6.1.0 MSI, the old version still appears, both versions are present, or the upgrade doesn't seem to work. This is because you had a per-user installation from v5.9 to v6.0.4. From v6.1.0, the MSI installer defaults to per-machine (system-wide) installation. MSI installers cannot automatically upgrade across different installation contexts (per-user to per-machine).
|
||||
|
||||
To check your installation type before upgrading, open File Explorer.
|
||||
|
||||
- If Mattermost is in `C:\Program Files\Mattermost` or `C:\Program Files (x86)\Mattermost`: Per-machine install (upgrade will work normally)
|
||||
- If Mattermost is in `C:\Users\<YourName>\AppData\Local\...`: Per-user install (requires manual uninstall before v6.1.0)
|
||||
|
||||
To resolve this issue, you must manually uninstall the old version before installing v6.1.0:
|
||||
|
||||
1. Uninstall both versions:
|
||||
- Go to **Settings \> Apps** or **Control Panel \> Programs and Features**.
|
||||
- Uninstall all Mattermost Desktop entries.
|
||||
2. Download the v6.1.0 MSI installer again from the [releases page](https://github.com/mattermost/desktop/releases).
|
||||
3. Install v6.1.0 with administrator privileges (it will install to `C:\Program Files\Mattermost`).
|
||||
4. Future upgrades will work normally.
|
||||
|
||||
## "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](https://www.keka.io) or [Unarchiver](https://macpaw.com/the-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> <kbd>Shift</kbd> <kbd>R</kbd> on Windows or Linux, or <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>R</kbd> 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> <kbd>Shift</kbd> <kbd>R</kbd> on Windows or Linux, or <kbd>⌘</kbd> <kbd>⇧</kbd> <kbd>R</kbd> on Mac.
|
||||
2. Go to App Settings via **File \> Settings** (or by pressing <kbd>Ctrl</kbd> <kbd>,</kbd> on Windows or Linux, or <kbd>⌘</kbd> <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](https://forum.mattermost.com/c/trouble-shoot/16) for previously reported errors, or [join the Mattermost user community for troubleshooting help](https://mattermost.com/community/).
|
||||
|
||||
## 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](https://support.mattermost.com/hc/en-us/articles/360060662492-Opening-a-Support-Ticket-for-Self-Managed-Deployments).
|
||||
|
||||
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:
|
||||
|
||||
> ``` javascript
|
||||
> document.getElementsByTagName("webview")[0].openDevTools();
|
||||
> ```
|
||||
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: "Distribute a custom desktop app"
|
||||
---
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
You can customize and distribute your own Mattermost desktop application by configuring [src/common/config/buildConfig.ts](https://github.com/mattermost/desktop/blob/master/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](https://developers.mattermost.com/contribute/more-info/desktop/developer-setup/) 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:
|
||||
|
||||
``` 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:
|
||||
|
||||
``` 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:
|
||||
|
||||
``` text
|
||||
enableServerManagement: true
|
||||
```
|
||||
|
||||
## Managed resources
|
||||
|
||||
[Custom builds](/deployment-guide/desktop/distribute-a-custom-desktop-app) 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 \<administration-guide/configure/environment-configuration-settings:managed resource paths\>\` server configuration setting. For example, adding the `/video` path:
|
||||
|
||||
``` 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)
|
||||
153
docs/main/deployment-guide/desktop/linux-desktop-install.mdx
Normal file
153
docs/main/deployment-guide/desktop/linux-desktop-install.mdx
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: "Install desktop app on Linux"
|
||||
---
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
import Tabs from '@theme/Tabs';
|
||||
import TabItem from '@theme/TabItem';
|
||||
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
This page describes how to install the Mattermost desktop app on Linux.
|
||||
|
||||
<Tabs>
|
||||
<TabItem value="ubuntu-debian" label="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](https://deb.packages.mattermost.com/pubkey.gpg). 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.
|
||||
|
||||
</Important>
|
||||
|
||||
1. At the command line, set up the Mattermost repository on your system:
|
||||
|
||||
> ``` sh
|
||||
> curl -fsS -o- https://deb.packages.mattermost.com/setup-repo.sh | sudo bash
|
||||
> ```
|
||||
|
||||
2. Install the Mattermost desktop app:
|
||||
|
||||
> ``` sh
|
||||
> sudo apt install mattermost-desktop
|
||||
> ```
|
||||
|
||||
3. Update the Mattermost desktop app:
|
||||
|
||||
> ``` 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](https://snapcraft.io/docs/installing-snapd) on the Snapcraft website for details.
|
||||
|
||||
1. At the command line, execute the following command:
|
||||
|
||||
> ``` sh
|
||||
> sudo snap install mattermost-desktop
|
||||
> ```
|
||||
|
||||
2. Run Mattermost as a desktop app.
|
||||
|
||||
<Tip>
|
||||
|
||||
You can review the current version of your desktop app by selecting the **More** <img src={useBaseUrl('/img/ui/dots-vertical_F01D9.svg')} alt="Use the More icon in the top left corner to access Mattermost desktop apps customization settings." className="theme-icon" /> icon located in the top left corner of the desktop app, then selecting **Help \> Version...**.
|
||||
|
||||
</Tip>
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="centos-rhel" label="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-6.3.0-linux-x86_64.rpm](https://releases.mattermost.com/desktop/6.3.0/mattermost-desktop-6.3.0-linux-x86_64.rpm)
|
||||
2. At the command line, execute the following command:
|
||||
|
||||
> ``` sh
|
||||
> sudo rpm -i mattermost-desktop-6.3.0-linux-x86_64.rpm
|
||||
> ```
|
||||
|
||||
3. Run Mattermost as a desktop app.
|
||||
|
||||
To manually update the desktop app, run the following command:
|
||||
|
||||
> ``` sh
|
||||
> sudo rpm -u mattermost-desktop-6.3.0-linux-x86_64.rpm
|
||||
> ```
|
||||
|
||||
<Tip>
|
||||
|
||||
You can review the current version of your desktop app by selecting the **More** <img src={useBaseUrl('/img/ui/dots-vertical_F01D9.svg')} alt="Use the More icon in the top left corner to access Mattermost desktop apps customization settings." className="theme-icon" /> icon located in the top left corner of the desktop app, then selecting **Help \> Version...**.
|
||||
|
||||
</Tip>
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="flatpak" label="Flatpak">
|
||||
|
||||
From Mattermost Desktop v6.1, Flatpak packages are available for Linux systems. Flatpak is a universal Linux package format that provides a sandboxed environment and includes runtime dependencies. The Flatpak version is currently in **beta**.
|
||||
|
||||
<Note>
|
||||
|
||||
Flatpak requires the Flatpak runtime to be installed on your system. The Mattermost Desktop Flatpak package uses Freedesktop Platform/SDK 25.08 and Electron BaseApp 25.08. Wayland display server support is enabled by default.
|
||||
|
||||
</Note>
|
||||
|
||||
## Available architectures
|
||||
|
||||
Flatpak packages are available for:
|
||||
|
||||
- **x86_64** (Intel/AMD 64-bit processors)
|
||||
- **aarch64** (ARM 64-bit processors)
|
||||
|
||||
## Install Flatpak
|
||||
|
||||
1. Ensure Flatpak is installed on your system. If not, see the [Flatpak setup guide](https://flatpak.org/setup/) for your distribution.
|
||||
2. Download the latest Mattermost Desktop Flatpak package for your architecture from the [Desktop App's Github releases page](https://github.com/mattermost/desktop/releases):
|
||||
- For x86_64: `mattermost-desktop-{VERSION}-linux-x86_64.flatpak`
|
||||
- For aarch64: `mattermost-desktop-{VERSION}-linux-aarch64.flatpak`
|
||||
3. Install the Flatpak package:
|
||||
|
||||
> ``` sh
|
||||
> flatpak install mattermost-desktop-{VERSION}-linux-{ARCH}.flatpak
|
||||
>
|
||||
> Replace ``{VERSION}`` with the version number (e.g., ``6.3.0``) and ``{ARCH}`` with your architecture (``x86_64`` or ``aarch64``).
|
||||
> ```
|
||||
|
||||
4. Run Mattermost as a desktop app:
|
||||
|
||||
> ``` sh
|
||||
> flatpak run com.mattermost.Desktop
|
||||
> ```
|
||||
|
||||
## Considerations
|
||||
|
||||
- The Flatpak version runs in a sandboxed environment, which may affect certain integrations or file access patterns.
|
||||
- Automatic app updates are handled through the Flatpak update mechanism.
|
||||
- The application requires access to Flathub or a compatible Flatpak repository for runtime dependencies.
|
||||
|
||||
<Tip>
|
||||
|
||||
You can review the current version of your desktop app by selecting the **More** <img src={useBaseUrl('/img/ui/dots-vertical_F01D9.svg')} alt="Use the More icon in the top left corner to access Mattermost desktop apps customization settings." className="theme-icon" /> icon located in the top left corner of the desktop app, then selecting **Help \> Version...**.
|
||||
|
||||
</Tip>
|
||||
|
||||
</TabItem>
|
||||
<TabItem value="generic-linux" label="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](https://github.com/mattermost/desktop/releases). 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](https://docs.appimage.org/introduction/quickstart.html).
|
||||
|
||||
## Install the Desktop App's compressed tarball
|
||||
|
||||
1. Download the latest version of the Mattermost desktop app for 64-bit systems: [mattermost-desktop-6.3.0-linux-x64.tar.gz](https://releases.mattermost.com/desktop/6.3.0/mattermost-desktop-6.3.0-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.
|
||||
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: "Silent Windows desktop distribution"
|
||||
---
|
||||
<PlanAvailability slug="all-commercial" />
|
||||
|
||||
You can distribute the official Windows desktop app silently to end users using the MSI installer, pre-configured with server URLs and settings. For comprehensive MSI installation options including Group Policy configuration, see the [MSI installer and Group Policy guide](/deployment-guide/desktop/desktop-msi-installer-and-group-policy-install).
|
||||
|
||||
## Silent MSI installation
|
||||
|
||||
1. Download the latest Windows MSI installer from the [Mattermost Desktop releases page on GitHub](https://github.com/mattermost/desktop/releases/latest).
|
||||
|
||||
2. Move the MSI file to a shared location such as a file server with read-only permissions.
|
||||
|
||||
3. Use your software deployment tool (SCCM, Intune, PDQ Deploy, etc.) to deploy the MSI with silent installation parameters:
|
||||
|
||||
**Silent install:**
|
||||
|
||||
``` text
|
||||
msiexec /i \\SERVER\shared_folder\mattermost-desktop-v6.1.0-x64.msi /qn
|
||||
```
|
||||
|
||||
## Pre-configuration with config.json
|
||||
|
||||
To pre-configure servers and settings, create a `config.json` file in the user's Mattermost data directory before first launch:
|
||||
|
||||
**Location**: `%APPDATA%\Mattermost\config.json`
|
||||
|
||||
**Example config.json**:
|
||||
|
||||
``` json
|
||||
{
|
||||
"version": 2,
|
||||
"teams": [
|
||||
{
|
||||
"name": "core",
|
||||
"url": "https://community.mattermost.com",
|
||||
"order": 0
|
||||
},
|
||||
{
|
||||
"name": "hq",
|
||||
"url": "https://hq.example.com",
|
||||
"order": 1
|
||||
}
|
||||
],
|
||||
"showTrayIcon": true,
|
||||
"trayIconTheme": "light",
|
||||
"minimizeToTray": true,
|
||||
"notifications": {
|
||||
"flashWindow": 2,
|
||||
"bounceIcon": true,
|
||||
"bounceIconType": "informational"
|
||||
},
|
||||
"showUnreadBadge": true,
|
||||
"useSpellChecker": true,
|
||||
"enableHardwareAcceleration": true,
|
||||
"autostart": false,
|
||||
"spellCheckerLocale": "en-US",
|
||||
"darkMode": false
|
||||
}
|
||||
```
|
||||
|
||||
**Batch script for silent install with pre-configuration:**
|
||||
|
||||
``` batch
|
||||
rem Install Mattermost desktop app silently
|
||||
msiexec /i \\SERVER\shared_folder\mattermost-desktop-v6.1.0-x64.msi /qn
|
||||
|
||||
rem Wait for installation to complete
|
||||
timeout /t 10
|
||||
|
||||
rem Create config directory if it doesn't exist
|
||||
if not exist "%APPDATA%\Mattermost" mkdir %APPDATA%\Mattermost
|
||||
|
||||
rem Copy pre-configured config.json
|
||||
copy \\SERVER\shared_folder\config.json %APPDATA%\Mattermost\config.json
|
||||
```
|
||||
|
||||
## Windows App: Silently removing the app
|
||||
|
||||
The MSI installer can be silently uninstalled using:
|
||||
|
||||
``` text
|
||||
msiexec /x {PRODUCT-CODE-GUID} /qn
|
||||
```
|
||||
|
||||
To find the product code for your installed version:
|
||||
|
||||
``` powershell
|
||||
Get-WmiObject -Class Win32_Product | Where-Object {$_.Name -like "*Mattermost*"} | Select-Object Name, IdentifyingNumber
|
||||
```
|
||||
|
||||
Alternatively, uninstall by searching for the MSI file:
|
||||
|
||||
``` text
|
||||
msiexec /x mattermost-desktop-v6.1.0-x64.msi /qn
|
||||
```
|
||||
|
||||
## Migration from EXE to MSI
|
||||
|
||||
Organizations currently using the Windows EXE installer must migrate to the MSI installer or Microsoft Store version:
|
||||
|
||||
1. **Uninstall existing EXE version** (if desired, optional):
|
||||
|
||||
``` text
|
||||
%userprofile%\AppData\local\Programs\mattermost-desktop\Uninstall Mattermost.exe /currentuser /S
|
||||
```
|
||||
|
||||
2. **Install MSI version** using silent installation commands above.
|
||||
|
||||
3. **User data preservation**: User settings and credentials are stored in `%APPDATA%\Mattermost` and will be preserved across the migration.
|
||||
|
||||
<Note>
|
||||
|
||||
The EXE installer will not receive v6.1.0 or later updates. Plan your migration accordingly.
|
||||
|
||||
</Note>
|
||||
Reference in New Issue
Block a user