From 84c6d60c263aa49c5430dec4ed9cefa9601f73e7 Mon Sep 17 00:00:00 2001 From: Morgan Jones Date: Mon, 30 Dec 2024 19:42:32 -0800 Subject: [PATCH] manual: add mattermost.chapter.md --- .../doc/manual/configuration/configuration.md | 1 + .../configuration/mattermost.chapter.md | 134 ++++++++++++++++++ nixos/doc/manual/redirects.json | 12 ++ 3 files changed, 147 insertions(+) create mode 100644 nixos/doc/manual/configuration/mattermost.chapter.md diff --git a/nixos/doc/manual/configuration/configuration.md b/nixos/doc/manual/configuration/configuration.md index 4c966f3325b9..fae8874b8323 100644 --- a/nixos/doc/manual/configuration/configuration.md +++ b/nixos/doc/manual/configuration/configuration.md @@ -22,6 +22,7 @@ subversion.chapter.md ```{=include=} chapters profiles.chapter.md +mattermost.chapter.md kubernetes.chapter.md ``` diff --git a/nixos/doc/manual/configuration/mattermost.chapter.md b/nixos/doc/manual/configuration/mattermost.chapter.md new file mode 100644 index 000000000000..f247134ce49a --- /dev/null +++ b/nixos/doc/manual/configuration/mattermost.chapter.md @@ -0,0 +1,134 @@ +# Mattermost {#sec-mattermost} + +The NixOS Mattermost module lets you build [Mattermost](https://mattermost.com) +instances for collaboration over chat, optionally with custom builds of plugins +specific to your instance. + +To enable Mattermost using Postgres, use a config like this: + +```nix +{ + services.mattermost = { + enable = true; + + # You can change this if you are reverse proxying. + host = "0.0.0.0"; + port = 8065; + + # Allow modifications to the config from Mattermost. + mutableConfig = true; + + # Override modifications to the config with your NixOS config. + preferNixConfig = true; + + socket = { + # Enable control with the `mmctl` socket. + enable = true; + + # Exporting the control socket will add `mmctl` to your PATH, and export + # MMCTL_LOCAL_SOCKET_PATH systemwide. Otherwise, you can get the socket + # path out of `config.mattermost.socket.path` and set it manually. + export = true; + }; + + # For example, to disable auto-installation of prepackaged plugins. + settings.PluginSettings.AutomaticPrepackagedPlugins = false; + } +} +``` + +As of NixOS 25.05, Mattermost uses peer authentication with Postgres or +MySQL by default. If you previously used password auth on localhost, +this will automatically be configured if your `stateVersion` is set to at least +`25.05`. + +## Using the Mattermost derivation {#sec-mattermost-derivation} + +The nixpkgs `mattermost` derivation runs the entire test suite during the +`checkPhase`. This test suite is run with a live MySQL and Postgres database +instance in the sandbox. If you are building Mattermost, this can take a while, +especially if it is building on a resource-constrained system. + +The following passthrus are designed to assist with enabling or disabling +the `checkPhase`: + +- `mattermost.withTests` +- `mattermost.withoutTests` + +The default (`mattermost`) is an alias for `mattermost.withTests`. + +## Using Mattermost plugins {#sec-mattermost-plugins} + +You can configure Mattermost plugins by either using prebuilt binaries or by +building your own. We test building and using plugins in the NixOS test suite. + +Mattermost plugins are tarballs containing a system-specific statically linked +Go binary and webapp resources. + +Here is an example with a prebuilt plugin tarball: + +```nix +{ + services.mattermost = { + plugins = with pkgs; [ + /* + * todo + * 0.7.1 + * https://github.com/mattermost/mattermost-plugin-todo/releases/tag/v0.7.1 + */ + (fetchurl { + # Note: Don't unpack the tarball; the NixOS module will repack it for you. + url = "https://github.com/mattermost-community/mattermost-plugin-todo/releases/download/v0.7.1/com.mattermost.plugin-todo-0.7.1.tar.gz"; + hash = "sha256-P+Z66vqE7FRmc2kTZw9FyU5YdLLbVlcJf11QCbfeJ84="; + }) + ]; + }; +} +``` + +Once the plugin is installed and the config rebuilt, you can enable this plugin +in the System Console. + +## Building Mattermost plugins {#sec-mattermost-plugins-build} + +The `mattermost` derivation includes the `buildPlugin` passthru for building +plugins that use the "standard" Mattermost plugin build template at +[mattermost-plugin-demo](https://github.com/mattermost/mattermost-plugin-demo). + +Since this is a "de facto" standard for building Mattermost plugins that makes +assumptions about the build environment, the `buildPlugin` helper tries to fit +these assumptions the best it can. + +Here is how to build the above Todo plugin. Note that we rely on +package-lock.json being assembled correctly, so must use a version where it is! +If there is no lockfile or the lockfile is incorrect, Nix cannot fetch NPM build +and runtime dependencies for a sandbox build. + +```nix +{ + services.mattermost = { + plugins = with pkgs; [ + (mattermost.buildPlugin { + pname = "mattermost-plugin-todo"; + version = "0.8-pre"; + src = fetchFromGitHub { + owner = "mattermost-community"; + repo = "mattermost-plugin-todo"; + # 0.7.1 didn't work, seems to use an older set of node dependencies. + rev = "f25dc91ea401c9f0dcd4abcebaff10eb8b9836e5"; + hash = "sha256-OM+m4rTqVtolvL5tUE8RKfclqzoe0Y38jLU60Pz7+HI="; + }; + vendorHash = "sha256-5KpechSp3z/Nq713PXYruyNxveo6CwrCSKf2JaErbgg="; + npmDepsHash = "sha256-o2UOEkwb8Vx2lDWayNYgng0GXvmS6lp/ExfOq3peyMY="; + extraGoModuleAttrs = { + npmFlags = [ "--legacy-peer-deps" ]; + }; + }) + ]; + }; +} +``` + +See `pkgs/by-name/ma/mattermost/build-plugin.nix` for all the options. +As in the previous example, once the plugin is installed and the config rebuilt, +you can enable this plugin in the System Console. diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json index a7ebb49b62b8..443cc445ad69 100644 --- a/nixos/doc/manual/redirects.json +++ b/nixos/doc/manual/redirects.json @@ -47,6 +47,18 @@ "ch-installation": [ "index.html#ch-installation" ], + "sec-mattermost": [ + "index.html#sec-mattermost" + ], + "sec-mattermost-derivation": [ + "index.html#sec-mattermost-derivation" + ], + "sec-mattermost-plugins": [ + "index.html#sec-mattermost-plugins" + ], + "sec-mattermost-plugins-build": [ + "index.html#sec-mattermost-plugins-build" + ], "sec-obtaining": [ "index.html#sec-obtaining" ],