pyrox.dev
1# Mattermost {#sec-mattermost}
2
3The NixOS Mattermost module lets you build [Mattermost](https://mattermost.com)
4instances for collaboration over chat, optionally with custom builds of plugins
5specific to your instance.
6
7To enable Mattermost using Postgres, use a config like this:
8
9```nix
10{
11 services.mattermost = {
12 enable = true;
13
14 # You can change this if you are reverse proxying.
15 host = "0.0.0.0";
16 port = 8065;
17
18 # Allow modifications to the config from Mattermost.
19 mutableConfig = true;
20
21 # Override modifications to the config with your NixOS config.
22 preferNixConfig = true;
23
24 socket = {
25 # Enable control with the `mmctl` socket.
26 enable = true;
27
28 # Exporting the control socket will add `mmctl` to your PATH, and export
29 # MMCTL_LOCAL_SOCKET_PATH systemwide. Otherwise, you can get the socket
30 # path out of `config.mattermost.socket.path` and set it manually.
31 export = true;
32 };
33
34 # For example, to disable auto-installation of prepackaged plugins.
35 settings.PluginSettings.AutomaticPrepackagedPlugins = false;
36 };
37}
38```
39
40As of NixOS 25.05, Mattermost uses peer authentication with Postgres or
41MySQL by default. If you previously used password auth on localhost,
42this will automatically be configured if your `stateVersion` is set to at least
43`25.05`.
44
45## Using the Mattermost derivation {#sec-mattermost-derivation}
46
47The nixpkgs `mattermost` derivation runs the entire test suite during the
48`checkPhase`. This test suite is run with a live MySQL and Postgres database
49instance in the sandbox. If you are building Mattermost, this can take a while,
50especially if it is building on a resource-constrained system.
51
52The following passthrus are designed to assist with enabling or disabling
53the `checkPhase`:
54
55- `mattermost.withTests`
56- `mattermost.withoutTests`
57
58The default (`mattermost`) is an alias for `mattermost.withTests`.
59
60## Using Mattermost plugins {#sec-mattermost-plugins}
61
62You can configure Mattermost plugins by either using prebuilt binaries or by
63building your own. We test building and using plugins in the NixOS test suite.
64
65Mattermost plugins are tarballs containing a system-specific statically linked
66Go binary and webapp resources.
67
68Here is an example with a prebuilt plugin tarball:
69
70```nix
71{
72 services.mattermost = {
73 plugins = with pkgs; [
74 # todo
75 # 0.7.1
76 # https://github.com/mattermost/mattermost-plugin-todo/releases/tag/v0.7.1
77 (fetchurl {
78 # Note: Don't unpack the tarball; the NixOS module will repack it for you.
79 url = "https://github.com/mattermost-community/mattermost-plugin-todo/releases/download/v0.7.1/com.mattermost.plugin-todo-0.7.1.tar.gz";
80 hash = "sha256-P+Z66vqE7FRmc2kTZw9FyU5YdLLbVlcJf11QCbfeJ84=";
81 })
82 ];
83 };
84}
85```
86
87Once the plugin is installed and the config rebuilt, you can enable this plugin
88in the System Console.
89
90## Building Mattermost plugins {#sec-mattermost-plugins-build}
91
92The `mattermost` derivation includes the `buildPlugin` passthru for building
93plugins that use the "standard" Mattermost plugin build template at
94[mattermost-plugin-demo](https://github.com/mattermost/mattermost-plugin-demo).
95
96Since this is a "de facto" standard for building Mattermost plugins that makes
97assumptions about the build environment, the `buildPlugin` helper tries to fit
98these assumptions the best it can.
99
100Here is how to build the above Todo plugin. Note that we rely on
101package-lock.json being assembled correctly, so must use a version where it is!
102If there is no lockfile or the lockfile is incorrect, Nix cannot fetch NPM build
103and runtime dependencies for a sandbox build.
104
105```nix
106{
107 services.mattermost = {
108 plugins = with pkgs; [
109 (mattermost.buildPlugin {
110 pname = "mattermost-plugin-todo";
111 version = "0.8-pre";
112 src = fetchFromGitHub {
113 owner = "mattermost-community";
114 repo = "mattermost-plugin-todo";
115 # 0.7.1 didn't work, seems to use an older set of node dependencies.
116 rev = "f25dc91ea401c9f0dcd4abcebaff10eb8b9836e5";
117 hash = "sha256-OM+m4rTqVtolvL5tUE8RKfclqzoe0Y38jLU60Pz7+HI=";
118 };
119 vendorHash = "sha256-5KpechSp3z/Nq713PXYruyNxveo6CwrCSKf2JaErbgg=";
120 npmDepsHash = "sha256-o2UOEkwb8Vx2lDWayNYgng0GXvmS6lp/ExfOq3peyMY=";
121 extraGoModuleAttrs = {
122 npmFlags = [ "--legacy-peer-deps" ];
123 };
124 })
125 ];
126 };
127}
128```
129
130See `pkgs/by-name/ma/mattermost/build-plugin.nix` for all the options.
131As in the previous example, once the plugin is installed and the config rebuilt,
132you can enable this plugin in the System Console.