Published

Mattermost

Team chat in the style of Slack: channels, direct messages, threads, file sharing, search, webhooks and slash commands, with desktop and mobile apps. Team Edition is the free MIT-licensed build for small teams: up to 250 activated users and no single sign-on. The stack is Mattermost and PostgreSQL, with files on local disk.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 25 users (one small team), about 500 messages a day, up to 25 MB of files per user a month.	1.5 vCPU · 2 GiB RAM · 16 GiB disk	1.92 vCPU · 3.9 GiB RAM · 27.83 GiB disk
MediumEstimate	Up to 100 users in a few teams, about 3,000 messages a day, screenshots and documents up to 25 MB per user a month.	2 vCPU · 3 GiB RAM · 36.5 GiB disk	2.52 vCPU · 5.1 GiB RAM · 51.405 GiB disk
HeavyEstimate	Up to 250 users (Team Edition's limit), up to 200 online at once, about 12,500 messages a day, up to 25 MB of files per user a month.	4 vCPU · 8 GiB RAM · 123.5 GiB disk	4.92 vCPU · 11.1 GiB RAM · 151.455 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Mattermost Team Edition (web app, API, WebSockets, jobs) (app)	0.5 / 1 / 9.5	1 / 2 / 30	2 / 4 / 72	[8][12][14][24][26]
PostgreSQL (database)	1 / 1 / 6.5	1 / 1 / 6.5	2 / 4 / 51.5	[14][18][29][30][31][32][33][34][35]

How the estimates are worked out

Mattermost Team Edition (web app, API, WebSockets, jobs) · Light: The docs size a whole single server for up to 1,000 users at 1 vCPU and 2 GB RAM, database included; with PostgreSQL as its own container, Mattermost gets half of each (ANAROQ split). Disk: Image 448,271,026 B compressed (0.417 GiB) + 649,274,368 B unpacked (0.605 GiB), both kept by the containerd store = 1.022 GiB. Files: 25 users × 25 MB a month (top of the docs' medium-usage band) × 12 months = 6.985 GiB. + 1 GiB for unpacked plugins, config and logs (assumption) = 9.007, rounded up to 9.5.
Mattermost Team Edition (web app, API, WebSockets, jobs) · Medium: Twice the light figures, half of the 2 vCPU / 4 GiB app node the docs give for 200 concurrent users: more open WebSockets, uploads and image previews (file uploads up to 100 MB drive memory). Disk: Image 448,271,026 B compressed (0.417 GiB) + 649,274,368 B unpacked (0.605 GiB), both kept by the containerd store = 1.022 GiB. Files: 100 users × 25 MB a month (top of the docs' medium-usage band) × 12 months = 27.940 GiB. + 1 GiB plugins, config and logs = 29.962, rounded up to 30.
Mattermost Team Edition (web app, API, WebSockets, jobs) · Heavy: vCPU and RAM: the app node of the docs' reference architecture for up to 200 concurrent users (2 vCPU, 4 GiB). Disk: Image 448,271,026 B compressed (0.417 GiB) + 649,274,368 B unpacked (0.605 GiB), both kept by the containerd store = 1.022 GiB. Files: 250 users × 25 MB a month (top of the docs' medium-usage band) × 12 months = 69.849 GiB. + 1 GiB plugins, config and logs = 71.871, rounded up to 72.
PostgreSQL · Light: Messages, channels, users and the full-text index live in PostgreSQL: 500 messages a day × an assumed 2 KB per post with indexes ≈ 0.4 GB a year, inside the light envelope (≤ 5 GB). The pool may open up to 100 connections (MaxOpenConns), but 25 users keep far fewer than 20 busy. Light method: shared_buffers 25% of RAM, worst-case work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Medium: 3,000 messages a day × an assumed 2 KB per post with indexes ≈ 2.2 GB a year, inside the light envelope (≤ 5 GB) for about two years; 100 users keep under 20 connections busy although the pool may open 100. Light method: shared_buffers 25% of RAM, worst-case work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Heavy: 12,500 messages a day × an assumed 2 KB per post with indexes ≈ 9 GB a year, beyond the 5 GB sidecar envelope, and up to 200 users online can keep more than 20 of the pool's 100 connections busy: the PostgreSQL profile's medium preset (≤ 50 GB, ≤ 100 connections). Medium method: shared_buffers 1 GiB = 25%, worst-case work_mem budget, 0.5 GiB image + 50 GiB data + 1 GiB WAL.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Mattermost Team Edition (web app, API, WebSockets, jobs)	8065/tcp	Public, through a proxy	Web app, REST API and WebSockets (HTTP); put behind TLS	[3][7][8]
PostgreSQL	5432/tcp	Internal only	PostgreSQL connections from Mattermost	[4][34]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Mattermost Team Edition (web app, API, WebSockets, jobs)	2000:2000	`mattermost`	No	`/mattermost/config/mattermost/data/mattermost/logs/mattermost/plugins/mattermost/client/plugins/var/tmp`	[4][6][7]
PostgreSQL	999:999	`postgres`	Yes, prepares its directories, then drops to this user	`/var/lib/postgresql/var/run/postgresql`	[27][28][34]

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
Mattermost Team Edition (web app, API, WebSockets, jobs)Derived	0.582	2.328	5.821	[14][15]
PostgreSQLAssumption	0.03	0.17	0.7	[15]

What the growth figures rest on

Mattermost Team Edition (web app, API, WebSockets, jobs): Uploaded files in /mattermost/data at the top of the docs' medium-usage band, 25 MB per user a month: 25, 100 and 250 users = 625, 2,500 and 6,250 MB a month. Data retention is a compliance feature of the paid plans (not even in the free Entry mode), so nothing is deleted automatically; logs in /mattermost/logs come on top.
PostgreSQL: 500, 3,000 and 12,500 messages a day × 30 days × an assumed 2 KB per post with its indexes = 30, 180 and 750 MB a month. Posts are kept forever: data retention is a compliance feature of the paid plans. Mattermost publishes no per-post figure.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

With Mattermost stopped: pg_dump of the mattermost database, plus copies of the config volume (config.json) and the data volume (uploaded files). [20][22]

Upgrade steps

Read the important upgrade notes for every version between yours and the target, check that PostgreSQL meets the new minimum, and move from one ESR to the next (for example 10.11 → 11.7); jumping two ESRs is supported but untested. [12][17][18]
Back up the database, config and data (see backup), set the new pinned tag of mattermost/mattermost-team-edition in the Compose file, then run docker compose pull and docker compose up -d. [5][20]DerivedThe Docker guide says to set MATTERMOST_IMAGE_TAG to a specific version and redeploy; pull and up -d is how Compose applies a new tag.
Schema migrations run when the new server starts; wait until the container is healthy (mmctl system status) and check docker compose logs mattermost before inviting users back. [6][10][18]

Roll back

Stop the stack, restore the database dump and the config and data copies taken before the upgrade, pin the previous tag and start it again. Downgrading in place needs mattermost db downgrade run with the newer binary, and users who signed in on v11+ may need a password reset on v10. [16][18][21]DerivedThe release policy says to restore the database and the previous version to revert an upgrade; the downgrade guide's schema downgrade inside a container is not documented for Docker, so the restore is the rollback here.

Known breaking changes

In 12.0.0: The minimum PostgreSQL version becomes 15 (the template's sidecar runs 18). RHEL 7 and 8 are no longer supported hosts; containers are unaffected. [12]
In 11.7.3: Do not upgrade from 10.11.17 or later to 11.7.2 or earlier: a bug breaks the database migration numbers. It is fixed in 11.7.3, so go straight to the current 11.7 patch. [18]
In 11.0.0: MySQL is no longer supported and PostgreSQL 14 is the minimum. Team Edition is limited to 250 users and loses GitLab SSO, and Playbooks stops working in it. Bleve search is removed: set DisableDatabaseSearch to false before upgrading if Bleve was on. [18][19][20]
In 11.0.0: Passwords move from bcrypt to PBKDF2 at each sign-in, so after a downgrade to 10.x those users need a password reset. The server refuses to start with ExperimentalViewArchivedChannels=false or ClientSideCertEnable=true. Manually installed plugins are no longer supported; MaxOpenConns drops from 300 to 100. [18]

Limits

Team Edition stops at 250 activated users and has no single sign-on (GitLab SSO was removed in v11.0). Beyond that, the Enterprise image runs free as Mattermost Entry (best under 50 users, with a 10,000-message history limit) or with a paid license; this template doesn't cover it. [15][18][19]
Calls (1:1 calls and screen sharing, up to 40 minutes in Team Edition) send media over UDP 8443 (TCP 8443 as fallback) straight to the server, never through the reverse proxy. The template does not publish 8443, so calls from other machines fail until you open it yourself. [3][11]
A team holds 50 users by default (MaxUsersPerTeam); raise it in the System Console for larger teams. Search runs in PostgreSQL: email addresses and terms with dashes are not found, and only the first 1 MB of a file's text is indexed. [8][12]
The 11.7 Extended Support Release gets security and major bug fixes until 2027-05-15 but no new features; newer monthly releases (11.11, then 12.0) add features and are each supported for three months. [16][17]

Security

Create the first account right after the first start: it becomes the system admin. Open sign-up is off by default, so everyone after that joins through an invite link or an admin. [5][8]
Serve Mattermost only over HTTPS through the reverse proxy. Behind it the template sets the Site URL to https://<domain>; it must match the address users open, or links, OAuth and the mobile apps break. [4][5]
The image enables local mode: a socket in /var/tmp gives full mmctl admin access, without a password, to anyone who can run commands in the container (the healthcheck uses it). Keep access to the Docker host limited to admins. [6][8]
Team Edition is meant for small teams, hobbyists and personal use; Mattermost does not recommend it for government or sensitive commercial workloads. The process runs as uid 2000 on a distroless image with no shell. [6][15]

Backup

Back up three things together: a pg_dump of PostgreSQL (messages, users, channels), the config volume (config.json and any certificates) and the data volume (uploaded files). Stop Mattermost during the backup, or the database and files can drift apart. [22]
To restore, put the database, config.json and the files back where they were backed up from, then start the same image tag that made the backup; upgrade only after the restore works. [20][22]