snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/develop/integrate/plugins/components/server/best-practices.md

@@ -0,0 +1,26 @@
+---
+title: "Best practices"
+sidebar_position: 0
+---
+
+## How should plugins serve publicly available static files?
+
+Add all static files under a file directory named `public` within the plugin directory, and include the files in the plugin bundle using the Makefile.
+
+## How do plugins make sure http requests are authentic?
+
+Plugins can implement the [`ServeHTTP`](/developers/integrate/reference/server#Hooks.ServeHTTP) to listen to http requests. This can be used to receive post action requests when [Interactive Messages Buttons and Menus](https://docs.mattermost.com/developer/interactive-messages.html) are triggered by users.
+
+When plugins act as an HTTP server, they serve requests from Mattermost clients (which are authenticated in a Mattermost sense), but may also serve HTTP requests from external services like webhooks. These requests from external services might use the Authorization header to authorize themselves against the plugin.
+
+Since these requests are just HTTP requests, anyone can send them to the plugin. Hence, the plugin must make sure the requests are authentic. The Mattermost Server sets the HTTP header ``Mattermost-User-Id`` when the request is made by an authenticated client. If the plugin is expecting the request to come from an authenticated Mattermost user, and the ``Mattermost-User-Id`` is blank, it's the plugin's responsibility to reject the request.
+
+From Mattermost v9.4, external systems can use the ``Authorization`` header to authenticate with the plugin. HTTP requests to server-side plugins can use an ``Authorization`` header in the request for the plugin to use, and the header value will be present in the request received by the plugin, as long as the token provided in the header is not a user token issued by the Mattermost server. This is useful for connecting external systems that require authentication through an Authorization header with their own token.
+
+## How should plugins handle request cancellation?
+
+Long-running `ServeHTTP` handlers should pass `r.Context()` to downstream operations and stop work when it is canceled. Mattermost v12.0 and later propagates deadlines and explicit cancellation for server-to-plugin and inter-plugin HTTP requests when the destination plugin is built with a context-aware plugin runtime.
+
+Inter-plugin callers can opt in with `http.NewRequestWithContext` or `req.WithContext`. If cancellation happens before response headers arrive, `PluginHTTP` returns `nil` and the caller can inspect `request.Context().Err()`. If it happens after headers arrive, reading the response body returns `context.Canceled` or `context.DeadlineExceeded`. Callers must close response bodies as usual.
+
+Context values are not propagated. Use headers or `plugin.Context` for supported cross-process metadata. Plugins that require end-to-end cancellation should declare Mattermost v12.0 as their minimum server version. Older servers retain legacy behavior: they continue to process the request without context propagation, and the call may not return promptly after cancellation.

docs/develop/integrate/plugins/components/server/debugging.md

@@ -0,0 +1,9 @@
+---
+title: "Debug Server plugins"
+---
+
+Plugins communicate with the main Mattermost Server by [RPC](https://github.com/hashicorp/go-plugin). In order to debug them with Delve, a few steps are necessary.
+### macOS
+1. After starting the main Mattermost application, run `ps aux | grep name.of.your.plugin`. This will print a list of running processes that match that name, as such: `username      78836   0.0  0.1  4397696  12492 s006  S     7:07AM   0:00.03 plugins/name.of.your.plugin/server/dist/plugin-darwin-amd64`.
+2. Grab the `pid`, which is the second number after your username in the output above. Run `dlv attach pid`, where `pid` is that number. let the plugin continue executing soon after connecting; Otherwise, the server will detect it as stopped and attempt to restart it.
+3. You're done. You should have access to your plugin's code through Delve and be able to set breakpoints, etc.

docs/develop/integrate/plugins/components/server/ha.md

@@ -0,0 +1,42 @@
+---
+title: "High availability"
+sidebar_position: 60
+---
+
+Mattermost Enterprise Edition servers with an E20 license have the ability to run in [High Availability (HA)](https://docs.mattermost.com/deployment/cluster.html) mode, meaning a cluster of Mattermost app servers running together as a single Mattermost deployment.
+
+It is important that all plugins consider HA environments when being built.
+
+Plugins are started as subprocesses of the main Mattermost process on each app server. This means a Mattermost deployment that has three app servers will have three separate copies of the same plugin running. Each running copy of the plugin will be isolated from one another on different servers. Therefore, to run properly in HA the plugin's server-side code must be stateless.
+
+To be stateless, the plugin must not retain any information or status in memory that may be needed across multiple events (e.g. HTTP requests or in other hooks). This data should instead be stored in a place that all running copies of the plugin have access to. For example, the [key-value store](/developers/integrate/reference/server#API.KVSet) the plugin API provides.
+
+To better explain the problem with having a plugin store data in-memory, consider this case:
+
+Let's say we have two Mattermost app servers running together in HA and an installed plugin with a feature that alerts a user any time a trigger word is posted in a channel.
+
+1. The user uses the web app side of the plugin to set the word `hello` as the trigger word
+2. An HTTP request is made to the server-side of the plugin to set `hello`
+3. The plugin process running on app server 1 handles the request and stores `hello` in a variable
+
+In this scenario, the trigger word is now only set for the plugin process running on app server 1. The plugin process running on app server 2 is unaware that the trigger word is `hello`. This means when someone posts a message containing `hello` and the request is load balanced to app server 2, the plugin is not going to alert our user when it should.
+
+The proper way to deal with this case would be for the plugin to store the trigger word in a global store, such as the KV store. Then any time a user posts the plugin can pull the trigger word from the store and properly alert the user, regardless of which app server handles the request.
+
+## Run a scheduled job in high availability mode
+
+Using the [mattermost/public/pluginapi/cluster](https://github.com/mattermost/mattermost/blob/d2c3710265c293281c2b445d4f72f27871c2e127/server/public/pluginapi/cluster/job.go#L115-L116) package, we can schedule jobs to perform background activity at regular intervals, without having to explicitly coordinate with other instances of the same plugin. Here's an example from the [Demo Plugin](https://github.com/mattermost/mattermost-plugin-demo/blob/d647f1ed7fdc384f5bc163a6bba689ab4293704e/server/activate_hooks.go#L72):
+
+```go
+job, cronErr := cluster.Schedule(
+    p.API,
+    "BackgroundJob",
+    cluster.MakeWaitForRoundedInterval(15*time.Minute),
+    p.BackgroundJobFunc,
+)
+if cronErr != nil {
+    return errors.Wrap(cronErr, "failed to schedule background job")
+}
+
+p.backgroundJob = job
+```

docs/develop/integrate/plugins/components/server/hello-world.md

@@ -0,0 +1,113 @@
+---
+title: "Plugin quick start"
+sidebar_position: -10
+---
+
+This tutorial will walk you through the basics of writing a Mattermost plugin with a server component.
+
+Note that the steps below are intentionally very manual to explain all of the pieces fitting together. In practice, we recommend referencing [mattermost-plugin-starter-template](https://github.com/mattermost/mattermost-plugin-starter-template) for helpful build scripts. Also, the plugin API changed in Mattermost 5.2. Consult the [migration](/developers/integrate/plugins/migration) document to upgrade older plugins.
+
+## Prerequisites
+
+Mattermost plugins extend the server using a Go API. In the future, gRPC may be supported, allowing you to write plugins in any language. For now, you'll need a functioning Go environment, so follow [Go's Getting Started](https://golang.org/doc/install) guide if needed.
+
+You'll also need a Mattermost server to install and test the plugin. This server must have [Enable](https://docs.mattermost.com/administration/config-settings.html#enable-plugins) set to true in the [PluginSettings](https://docs.mattermost.com/administration/config-settings.html#plugins-beta) section of its config file. If you want to upload plugins via the System Console or API, you'll also need to set [EnableUploads](https://docs.mattermost.com/administration/config-settings.html#enable-plugin-uploads) to true in the same section.
+
+## Build the plugin
+
+The process that will communicate with the Mattermost server is built using a set of APIs provided by the source code for the Mattermost server.
+
+Download the source code for the Mattermost server:
+
+```bash
+go get -u github.com/mattermost/mattermost/server/v8
+```
+
+Define `$GOPATH`. By default, this is already `$HOME/go`, but it's helpful to make this explicit:
+```shell
+export GOPATH=$HOME/go
+```
+
+Now, create a directory to act as your workspace:
+
+```bash
+mkdir -p $GOPATH/src/my-plugin
+cd $GOPATH/src/my-plugin
+```
+
+Create a file named `plugin.go` with the following contents:
+
+<PluginGoExample name="_helloWorld" />
+
+This plugin will register an HTTP handler that will respond with "Hello, world!" when requested.
+
+Build the executable that will be distributed with your plugin:
+
+```bash
+go build -o plugin.exe plugin.go
+```
+
+
+<Note title="Note">
+Your executable is platform specific! If you're building the plugin for a server running on a different operating system, you'll need to use a slightly different command. For example, if you're developing the plugin from MacOS and deploying to a Linux server, you'll need to use this command:
+</Note>
+
+
+```bash
+GOOS=linux GOARCH=amd64 go build -o plugin.exe plugin.go
+```
+
+Also note that the ".exe" extension is required if you'd like your plugin to run on Windows, but is otherwise optional. Consider referencing [mattermost-plugin-starter-template](https://github.com/mattermost/mattermost-plugin-starter-template) for helpful build scripts.
+
+Now, we'll need to define the required manifest describing your plugin's entry point. Create a file named `plugin.json` with the following contents:
+
+```json
+{
+    "id": "com.mattermost.server-hello-world",
+    "name": "Hello World",
+    "server": {
+        "executable": "plugin.exe"
+    }
+}
+```
+
+This manifest gives the server the location of your executable within your plugin bundle. Consult the [manifest reference](/developers/integrate/plugins/manifest-reference) for more details, including how to define a cross-platform bundle by defining multiple executables, and how to define a minimum required server version for your plugin.
+
+Note that you may also use `plugin.yaml` to define the manifest.
+
+Bundle the manifest and executable into a tar file:
+
+```bash
+tar -czvf plugin.tar.gz plugin.exe plugin.json
+```
+
+You should now have a file named `plugin.tar.gz` in your workspace. Congratulations! This is your first server plugin!
+
+## Install the plugin
+
+Install the plugin in one of the following ways:
+
+1) Through System Console UI:
+
+```text
+- Log in to Mattermost as a System Admin.
+- Open the System Console at `/admin_console`
+- Navigate to *Plugins > Plugin Management** and upload the `plugin.tar.gz` you generated above.
+- Click **Enable** under the plugin after it has uploaded.
+```
+
+2) Or, manually:
+
+    - Extract `plugin.tar.gz` to a folder with the same name as the plugin id you specified in ``plugin.json``, in this case `com.mattermost.server-hello-world/`.
+    - Add the plugin to the directory set by **PluginSettings > Directory** in your ``config.json`` file. If none is set, defaults to `./plugins` relative to your Mattermost installation directory. The resulting directory structure should look something like:
+
+      ```
+      mattermost/
+          plugins/
+              com.mattermost.server-hello-world/
+                  plugin.json
+                  plugin.exe
+      ```
+    - Restart the Mattermost server.
+
+Once you've installed the plugin in one of the ways above, browse to `https://<your-mattermost-server>/plugins/com.mattermost.server-hello-world`, and you'll be greeted by your plugin.

docs/develop/integrate/plugins/components/server/index.md

@@ -0,0 +1,48 @@
+---
+title: "Server plugins"
+sidebar_position: 10
+---
+
+Server plugins are subprocesses invoked by the server that communicate with Mattermost using remote procedure calls (RPC).
+
+Looking for a quick start? [See our "Hello, world!" tutorial](/developers/integrate/plugins/components/server/hello-world).
+
+Want the Server SDK reference doc? [Find it here](/developers/integrate/reference/server).
+
+## Features
+
+#### RPC API
+
+Use the [RPC API](/developers/integrate/reference/server#API) to execute create, read, update and delete (CRUD) operations on server data models.
+
+For example, your plugin can consume events from a third-party webhook and create corresponding posts in Mattermost, without having to host your code outside Mattermost.
+
+#### Hooks
+
+Register for [hooks](/developers/integrate/reference/server#Hooks) and get alerted when certain events occur.
+
+For example, consume the [OnConfigurationChange](/developers/integrate/reference/server#Hooks.OnConfigurationChange) hook to respond to server configuration changes, or the [MessageHasBeenPosted](/developers/integrate/reference/server#Hooks.MessageHasBeenPosted) hook to respond to posts.
+
+#### REST API
+
+Implement the [ServeHTTP](/developers/integrate/) hook to extend the existing Mattermost REST API.
+
+Plugins with both a web app and server component can leverage this REST API to exchange data. Alternatively, expose your REST API to services and developers connecting from outside Mattermost.
+
+## How it works
+
+When starting a plugin, the server consults the [plugin's manifest](/developers/integrate/plugins/manifest-reference) to determine if a server component was included. If found, the server launches a new process using the executable included with the plugin.
+
+The server will trigger the [OnActivate](/developers/integrate/reference/server#Hooks.OnActivate) hook if the plugin is successfully started, allowing you to perform startup events. If the plugin is disabled, the server will trigger the [OnDeactivate](/developers/integrate/reference/server#Hooks.OnDeactivate) hook. While running, the server plugin can consume hook events, make API calls, launch threads or subprocesses of its own, interact with third-party services or do anything else a regular program can do.
+
+## High availability
+
+Considerations for plugins in a high availability configuration are documented here: [High Availability](/developers/integrate/plugins/components/server/ha)
+
+## Best practices
+
+Some best practices for working with the server component of a plugin are documented here: [Best Practices](/developers/integrate/plugins/components/server/best-practices)
+
+## Debug Server plugins
+
+Guidelines for debugging the server-side of plugins are documented here: [Debug Server plugins](/developers/integrate/plugins/components/server/debugging)