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 /*
75 * todo
76 * 0.7.1
77 * https://github.com/mattermost/mattermost-plugin-todo/releases/tag/v0.7.1
78 */
79 (fetchurl {
80 # Note: Don't unpack the tarball; the NixOS module will repack it for you.
81 url = "https://github.com/mattermost-community/mattermost-plugin-todo/releases/download/v0.7.1/com.mattermost.plugin-todo-0.7.1.tar.gz";
82 hash = "sha256-P+Z66vqE7FRmc2kTZw9FyU5YdLLbVlcJf11QCbfeJ84=";
83 })
84 ];
85 };
86}
87```
88
89Once the plugin is installed and the config rebuilt, you can enable this plugin
90in the System Console.
91
92## Building Mattermost plugins {#sec-mattermost-plugins-build}
93
94The `mattermost` derivation includes the `buildPlugin` passthru for building
95plugins that use the "standard" Mattermost plugin build template at
96[mattermost-plugin-demo](https://github.com/mattermost/mattermost-plugin-demo).
97
98Since this is a "de facto" standard for building Mattermost plugins that makes
99assumptions about the build environment, the `buildPlugin` helper tries to fit
100these assumptions the best it can.
101
102Here is how to build the above Todo plugin. Note that we rely on
103package-lock.json being assembled correctly, so must use a version where it is!
104If there is no lockfile or the lockfile is incorrect, Nix cannot fetch NPM build
105and runtime dependencies for a sandbox build.
106
107```nix
108{
109 services.mattermost = {
110 plugins = with pkgs; [
111 (mattermost.buildPlugin {
112 pname = "mattermost-plugin-todo";
113 version = "0.8-pre";
114 src = fetchFromGitHub {
115 owner = "mattermost-community";
116 repo = "mattermost-plugin-todo";
117 # 0.7.1 didn't work, seems to use an older set of node dependencies.
118 rev = "f25dc91ea401c9f0dcd4abcebaff10eb8b9836e5";
119 hash = "sha256-OM+m4rTqVtolvL5tUE8RKfclqzoe0Y38jLU60Pz7+HI=";
120 };
121 vendorHash = "sha256-5KpechSp3z/Nq713PXYruyNxveo6CwrCSKf2JaErbgg=";
122 npmDepsHash = "sha256-o2UOEkwb8Vx2lDWayNYgng0GXvmS6lp/ExfOq3peyMY=";
123 extraGoModuleAttrs = {
124 npmFlags = [ "--legacy-peer-deps" ];
125 };
126 })
127 ];
128 };
129}
130```
131
132See `pkgs/by-name/ma/mattermost/build-plugin.nix` for all the options.
133As in the previous example, once the plugin is installed and the config rebuilt,
134you can enable this plugin in the System Console.