Add consolidated "Install and manage plugins" documentation #9073
+187
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,183 @@ | ||
| .. _manage-plugins: | ||
|
|
||
| Install and manage plugins | ||
| ========================== | ||
|
|
||
| Plugins extend Mattermost with new features and integrations, from pre-built integrations such as GitHub, Jira, and Zoom to custom plugins your team builds in-house. As a system admin, you can install, enable, configure, update, and remove plugins using either the System Console or the :doc:`mmctl command line tool </administration-guide/manage/mmctl-command-line-tool>`. | ||
|
|
||
| This page describes how to manage the plugin lifecycle. For a conceptual overview of pre-built and custom plugins, see the :doc:`plugins </integrations-guide/plugins>` documentation. For the complete list of plugin configuration options, see the :doc:`plugins configuration settings </administration-guide/configure/plugins-configuration-settings>` documentation. To build your own plugin, see the `Mattermost plugin developer <https://developers.mattermost.com/integrate/plugins/>`__ documentation. | ||
|
|
||
| .. note:: | ||
|
|
||
| You must be a system admin to install and manage plugins. Plugins are managed at the server level and apply to your entire Mattermost deployment. | ||
|
|
||
| Before you begin | ||
| ---------------- | ||
|
|
||
| Plugin availability and the actions you can take depend on a few configuration settings found in the System Console under **Plugins > Plugin Management**. Review these settings before installing or updating plugins: | ||
|
|
||
| - **Enable plugins** (``PluginSettings.Enable``) must be set to **true** (the default) for the plugin system to work. When disabled, all plugins are turned off. | ||
| - **Enable Marketplace** (``PluginSettings.EnableMarketplace``) must be set to **true** (the default) to install plugins from the in-product Marketplace. | ||
| - **Enable remote Marketplace** (``PluginSettings.EnableRemoteMarketplace``) must be set to **true** (the default) for the Marketplace to connect to the remote endpoint and list community and Mattermost-provided plugins. Set this to **false** for servers that can't reach the internet; the Marketplace then shows only pre-packaged and installed plugins. | ||
| - **Upload Plugin** (``PluginSettings.EnableUploads``) must be set to **true** to upload plugin bundles from your local computer. This setting applies to self-hosted deployments only. | ||
|
|
||
| .. note:: | ||
|
|
||
| If you receive a ``Received invalid response from the server`` error when uploading a plugin, the :ref:`maximum file size <administration-guide/configure/environment-configuration-settings:maximum file size>` configuration setting is likely too small for the plugin bundle. Increase it, and update any proxy settings as needed. | ||
|
|
||
| See the :doc:`plugins configuration settings </administration-guide/configure/plugins-configuration-settings>` documentation for details on each of these settings, including their ``config.json`` paths and environment variables. | ||
|
|
||
| Plugin installation methods | ||
| --------------------------- | ||
|
|
||
| You can install a plugin from the in-product Marketplace, by uploading a plugin bundle, or by using mmctl. Pre-packaged plugins that ship with the Mattermost Server are installed and upgraded automatically when **Automatic prepackaged plugins** (``PluginSettings.AutomaticPrepackagedPlugins``) is enabled (the default). | ||
|
|
||
| App Marketplace | ||
| ~~~~~~~~~~~~~~~ | ||
|
|
||
| Installing from the Marketplace is the recommended method for pre-built plugins. The Marketplace always installs the latest compatible version, and plugins downloaded from the Marketplace are signature-validated. | ||
|
|
||
| 1. In Mattermost, from the Product menu |product-list|, select **App Marketplace**. | ||
| 2. Search for or scroll to the plugin you want, and then select **Install**. | ||
| 3. Once the plugin is installed, select **Configure** to open its settings in the System Console, or **Enable** to turn it on with the default configuration. | ||
| 4. Confirm the installation succeeded: the plugin appears in the **Installed Plugins** list under **Plugins > Plugin Management**, and its features are available in Mattermost. | ||
|
|
||
| .. tip:: | ||
|
|
||
| The `Mattermost Marketplace <https://mattermost.com/marketplace/>`__ website offers an expanded selection of community-supported integrations. | ||
|
|
||
| Plugin upload | ||
| ~~~~~~~~~~~~~ | ||
|
|
||
| Upload a plugin bundle when you're installing a custom or third-party plugin that isn't in the Marketplace, or when your server runs in an air-gapped or restricted environment. Uploading requires the **Upload Plugin** setting to be enabled and the **Require plugin signature** (``PluginSettings.RequirePluginSignature``) setting to be disabled. | ||
|
|
||
| 1. Download the plugin bundle (a ``.tar.gz`` file), typically from the plugin's GitHub releases page. Many plugins offer a separate, smaller bundle for each platform (for example, ``linux-amd64``) alongside a larger universal bundle that contains the binaries for all supported platforms. Download the bundle that matches your server's operating system and architecture; a bundle built for a different platform won't start. If you use the universal bundle instead, Mattermost automatically selects the correct binary for your server. | ||
| 2. Log in to your Mattermost System Console as a system admin. | ||
| 3. Go to **Plugins > Plugin Management**. | ||
| 4. In the **Upload Plugin** section, select **Choose File**, select the plugin bundle you downloaded, and then select **Upload**. | ||
| 5. The plugin appears in the **Installed Plugins** list. Select **Enable** to turn it on. | ||
|
|
||
| mmctl | ||
| ~~~~~ | ||
|
|
||
| The :doc:`mmctl command line tool </administration-guide/manage/mmctl-command-line-tool>` is useful for scripted or remote plugin management. Plugins must be enabled in the server configuration first. | ||
|
|
||
| Several commands take the plugin's ID, shown as ``<id>`` below. A plugin's ID is the ``id`` value in its ``plugin.json`` manifest. It's often the plugin's name, such as ``github`` or ``playbooks``, but some plugins use a reverse-DNS identifier, such as ``com.mattermost.calls`` for the Calls plugin. To list the IDs of installed plugins, run ``mmctl plugin list``. | ||
|
|
||
| - Install the latest version from the Marketplace by plugin ID: | ||
|
Contributor
There was a problem hiding this comment. Wondering if we should provide some guidance on how to grab the plugin ID? For most plugins it's usually just the name of the plugin (e.g.
Contributor
Author
There was a problem hiding this comment. Added in 648cd72 — the mmctl section now explains that a plugin's ID is the |
||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin marketplace install <id> | ||
|
|
||
| - Install a plugin bundle from your local computer: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin add myplugin.tar.gz | ||
|
|
||
| - Install a plugin bundle from a URL: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin install-url https://example.com/myplugin.tar.gz | ||
|
|
||
| After installing, enable the plugin by its ID: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin enable <id> | ||
|
|
||
| Enable or disable a plugin | ||
| -------------------------- | ||
|
|
||
| Installing a plugin doesn't turn it on automatically. Enable a plugin to make it available to users, and disable it to remove it from the user interface without uninstalling it. | ||
|
|
||
| To enable or disable a plugin in the System Console: | ||
|
|
||
| 1. Go to **Plugins > Plugin Management**. | ||
| 2. In the **Installed Plugins** list, locate the plugin. | ||
| 3. Select **Enable** or **Disable**. | ||
|
|
||
| To enable or disable a plugin with mmctl: | ||
|
Contributor
There was a problem hiding this comment. It might be helpful to have some subheaders here, so you can directly link others to specific sections on how to enable/disable plugins, similar to how "Install a Plugin" is set up. For example, we could have a subheader for From the System Console and one for Using mmctl for a structure like:
I'm like 1/5 on this though so we can leave as-is if we think that the extra headers won't provide much value
Contributor
There was a problem hiding this comment. I think it's fine as is given the content isn't very long, so it's easy enough to scan for the method the reader is looking for. |
||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin enable <id> | ||
| mmctl plugin disable <id> | ||
|
|
||
| .. note:: | ||
|
|
||
| Disabling a plugin immediately removes it from the user interface and stops the plugin from running. The plugin remains installed and can be re-enabled at any time. | ||
|
|
||
| Configure a plugin | ||
| ------------------ | ||
|
|
||
| Most plugins have their own settings page. After a plugin is installed, go to **Plugins** in the System Console and select the plugin by name to configure it, then select **Save**. Refer to the documentation for each plugin for details on its available settings. | ||
|
|
||
| Update a plugin | ||
| --------------- | ||
|
|
||
| We recommend keeping plugins up to date as new versions are released. Updates are generally seamless and don't interrupt the user experience, but you should review each plugin's release notes for compatibility considerations, and test updates in a staging environment before applying them in production. | ||
|
|
||
| You can update a plugin using any of the following methods: | ||
|
Contributor
There was a problem hiding this comment. Similar feedback as before, I wonder if having subheaders/sections would be beneficial here for easier linking. Still like 1/5 on it though.
Contributor
There was a problem hiding this comment. Same as above: I think it's fine as is given the content isn't very long, so it's easy enough to scan for the method the reader is looking for. |
||
|
|
||
| - **Pre-packaged plugins** are upgraded automatically when the **Automatic prepackaged plugins** setting is enabled (the default). If a newer version is already installed, no change is made. | ||
| - **Marketplace plugins** show an **Update** option in the App Marketplace when a newer version is available. Select it to install the latest version. | ||
| - **Uploaded plugins** are updated by uploading a newer bundle with the same plugin ID through **Plugins > Plugin Management**. The new version overwrites the existing one. | ||
| - **mmctl** updates an installed plugin when you add a bundle that has the same plugin ID. Use the ``--force`` (``-f``) flag to overwrite the existing version: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin add myplugin.tar.gz --force | ||
| mmctl plugin install-url https://example.com/myplugin.tar.gz --force | ||
|
|
||
| The ``--force`` flag overwrites the installed plugin without asking for confirmation, so verify the new bundle's compatibility (and ideally test it in a staging environment) before applying it in production. | ||
|
|
||
| You can also reinstall the latest Marketplace version with ``mmctl plugin marketplace install <id>``. | ||
|
|
||
| .. tip:: | ||
|
|
||
| To confirm the version currently installed, go to **Plugins > Plugin Management** and review the **Installed Plugins** list, or run ``mmctl plugin list``. | ||
|
|
||
| Remove a plugin | ||
| --------------- | ||
|
|
||
| Removing a plugin disables it and uninstalls it from the server. | ||
|
|
||
| To remove a plugin in the System Console: | ||
|
Contributor
There was a problem hiding this comment. Same feedback as before regarding subsections. |
||
|
|
||
| 1. Go to **Plugins > Plugin Management**. | ||
| 2. In the **Installed Plugins** list, locate the plugin. | ||
| 3. Select **Remove**. | ||
|
|
||
| To remove a plugin with mmctl: | ||
|
|
||
| .. code-block:: sh | ||
|
|
||
| mmctl plugin delete <id> | ||
|
coderabbitai[bot] marked this conversation as resolved.
|
||
|
|
||
| .. note:: | ||
|
|
||
| Removing a plugin uninstalls it from the server and stops it from running, but Mattermost preserves the plugin's associated data: | ||
|
Contributor
There was a problem hiding this comment. Is there any guidance on how this data can be fully cleared/deleted that we can add here in the event that that removal is a want or requirement for an instance?
Contributor
Author
There was a problem hiding this comment. Added a note in 648cd72. Confirmed against the server source: removing a plugin disables it and deletes the bundle, but intentionally retains its config, KV store data, and any bot accounts — and there's no supported System Console or mmctl command to fully purge that data. Clearing it requires direct database changes, so the note points admins to Mattermost support rather than documenting raw table edits. If you'd prefer we spell out the specific tables, I can expand it. |
||
|
|
||
| - **Configuration**: The plugin's configuration is retained and marked as disabled rather than deleted. Reinstalling the same plugin restores its previous settings. | ||
| - **Key-value store data**: Data the plugin saved to the key-value (KV) store is preserved. It's cleared only by the plugin itself through the plugin API, not by removing the plugin. | ||
| - **Bot accounts**: Bot accounts the plugin created remain on the server and stay active. To remove them, deactivate the bot accounts manually in **System Console > Integrations > Bot Accounts**. | ||
|
|
||
| Because the configuration and KV store data persist, removal is effectively reversible: reinstalling the plugin restores its prior configuration and data. | ||
|
|
||
| Mattermost doesn't provide a built-in way to fully delete a removed plugin's retained configuration or key-value data through the System Console or mmctl. If you must purge this data to meet a data-retention or compliance requirement, contact Mattermost support for guidance, as it requires direct changes to the Mattermost database. | ||
|
|
||
| Air-gapped and restricted environments | ||
| --------------------------------------- | ||
|
|
||
| For deployments without internet access, set **Enable remote Marketplace** to **false** so the Marketplace shows only pre-packaged and installed plugins, and install plugins by uploading the bundle directly through the System Console. See the :doc:`air-gapped deployment </deployment-guide/reference-architecture/deployment-scenarios/air-gapped-deployment>` documentation for details. | ||
|
|
||
| Related documentation | ||
| ---------------------- | ||
|
|
||
| - :doc:`Plugins overview </integrations-guide/plugins>` - Learn about pre-built and custom plugins. | ||
| - :doc:`Popular pre-built integrations </integrations-guide/popular-integrations>` - Browse available pre-built plugins and how to get them. | ||
| - :doc:`Plugins configuration settings </administration-guide/configure/plugins-configuration-settings>` - Review every plugin configuration setting. | ||
| - :doc:`mmctl command line tool </administration-guide/manage/mmctl-command-line-tool>` - Manage plugins from the command line. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we be consistent about including the plugin variable like this with all the settings mentioned in this doc (whenever it is mentioned for the first time)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good call — done in 648cd72. Each plugin setting now shows its
PluginSettings.*key on first mention:Enable,EnableMarketplace,EnableRemoteMarketplace,EnableUploads,AutomaticPrepackagedPlugins, andRequirePluginSignature(now introduced in the Plugin upload section, since the prerequisite bullet was removed per your other comment).