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

docs/main/deployment-guide/server/linux/deploy-azure-native-vm.mdx

@@ -0,0 +1,144 @@
+---
+title: "Deploy Mattermost on Azure Native (VM)"
+sidebar_label: "Azure Native VM"
+---
+<EditionAvailability tiers="enterprise,enterprise-advanced" />
+
+Mattermost is published as an **Azure Marketplace** solution that provisions a production-ready Mattermost stack in your own subscription using Azure-managed services for compute, database, shared file storage, and load balancing. This option is intended for organizations that want a resilient Mattermost deployment they can scale and operate within their existing Azure tenant.
+
+## Prerequisites
+
+- An active **Azure subscription** with the **Owner** or **Contributor** role on the subscription (required to purchase and deploy Azure Marketplace solutions), permission to create resource groups, and permission to accept **Azure Marketplace** billing terms for the offer.
+- Familiarity with the **Azure portal** (resource groups, networking, virtual machines, and Application Gateway).
+- For multi-node deployments (more than one application instance), a valid **Mattermost Enterprise license** file. The license is optional for single-node deployments.
+- If you plan to enable **HTTPS** at deployment time:
+  - A **PFX (PKCS#12)** certificate bundle and its password.
+  - A **custom domain (FQDN)** that you will point to the Application Gateway after deployment.
+
+## What gets deployed
+
+The template provisions a self-contained, production-ready stack in the resource group you select, including:
+
+1. **Virtual Machine Scale Set (Linux):** Runs Mattermost on Ubuntu Pro 24.04 LTS images published by Mattermost. Instance count and VM size are driven by the scaling tier you choose.
+2. **Application Gateway with public IP:** Acts as the entry point for Mattermost traffic, with optional **HTTPS listener** (using your PFX certificate) and HTTP-to-HTTPS redirection when HTTPS is enabled.
+3. **Azure Database for PostgreSQL Flexible Server:** Managed PostgreSQL service that stores Mattermost data, with optional **same-zone** or **zone-redundant** high availability, backup retention and geo-redundancy.
+4. **Azure Files (NFS) with private endpoint:** Shared storage for Mattermost data (uploads, plugins, and other shared files), reachable only from inside the virtual network.
+5. **Virtual network and subnets:** A dedicated VNet for the deployment, with separate subnets for the Application Gateway, the Mattermost application instances, the database, and the storage private endpoint.
+6. **NAT gateway:** Provides controlled outbound internet access for the application instances (for example, to fetch packages and the Mattermost configuration scripts).
+7. **Private DNS zones:** Used to resolve the PostgreSQL Flexible Server and Azure Files private endpoint from inside the VNet.
+
+## Step 1: Select a plan and start creation
+
+Open the [Mattermost - Azure-Native (VM-based)](https://marketplace.microsoft.com/en-us/product/azure-application/mattermost.mattermost-app-vm) offer in the Azure Marketplace, click **Get it now**, select the plan, and then click **Create** to open the deployment wizard.
+
+## Step 2: Basics
+
+On the **Basics** tab, configure the following:
+
+1. **Subscription:** Choose the Azure subscription where the deployment will live.
+2. **Resource group:** Select an existing resource group or create a new one. A **new** resource group keeps the production stack easy to manage and clean up.
+3. **Region:** Select the deployment region. Choose a region that supports the PostgreSQL Flexible Server SKUs you plan to use, and that has the **availability zones** you need if you intend to enable PostgreSQL high availability.
+4. **Resource name prefix:** Short prefix (2–12 lowercase letters, digits, or hyphens) used to name the Azure resources created by the template (for example, `mm-prod`).
+
+![An example of the Azure Native Basics setup screen.](/images/azure/azure-native-basics.png)
+
+## Step 3: Application
+
+On the **Application** tab, configure how the Mattermost application is sized and how administrators access the VMs.
+
+1. **Scaling tier:** Pick the user scale you are planning for. The wizard uses this to suggest sensible defaults for the **VMSS instance count**, **VM size**, and **PostgreSQL SKU**, and to determine whether **read replicas** are created for the database. The dropdown shows the recommended node count and VM SKU for each tier. For the underlying sizing rationale, see [available reference architectures](/deployment-guide/scale/scaling-for-enterprise#available-reference-architectures).
+2. **VMSS instance count:** Number of Mattermost application nodes (1–5). Defaults to the suggested value for your scaling tier; adjust if needed.
+3. **Enterprise license file:** Required when the instance count is greater than 1 (multi-node high-availability clustering). Upload your Mattermost Enterprise license file. The license is optional for single-node deployments.
+4. **VM SKU:** Size of each VMSS instance. The wizard surfaces recommended Linux sizes first; you can select any supported Linux size available in your region.
+5. **Admin username:** Linux administrator account used to sign in to the VM instances.
+6. **Authentication type:** Choose **Password** or **SSH public key** for Linux sign-in. **SSH public key** is recommended for production deployments.
+7. **Mattermost version:** The Mattermost version to install (for example, `11.6.2`). See the [Mattermost release policy](/product-overview/release-policy) for supported versions.
+
+![An example of the Azure Native Application setup screen.](/images/azure/azure-native-application.png)
+
+## Step 4: Database
+
+On the **Database** tab, configure the managed PostgreSQL service and the shared NFS file share.
+
+1. **PostgreSQL compute SKU:** Memory-optimized Flexible Server SKU. Defaults to the SKU recommended for your scaling tier; pick a SKU that is supported in your region. Available choices are `Standard_E2ds_v5`, `Standard_E4ds_v5`, and `Standard_E8ds_v5`.
+2. **PostgreSQL high availability:** Choose how PostgreSQL is made resilient:
+   - **Disabled:** Single primary instance. Suitable for small deployments.
+   - **Same zone:** Primary and standby in the same availability zone.
+   - **Zone redundant:** Primary and standby in different availability zones.
+
+   For regional support of Flexible Server SKUs and HA modes, see [Azure regions for PostgreSQL Flexible Server](https://learn.microsoft.com/en-us/azure/postgresql/overview#azure-regions).
+3. **Primary availability zone** and **standby availability zone:** Shown when HA is enabled. For zone-redundant HA, the primary and standby zones must be different. Pick zones supported in your region for the PostgreSQL SKU you chose.
+4. **PostgreSQL admin username and password:** Administrator credentials for the Flexible Server. Avoid reserved names such as `azure_superuser`. The password must meet [Azure Flexible Server password complexity requirements](https://learn.microsoft.com/azure/postgresql/flexible-server/concepts-security#password).
+5. **Mattermost database user password:** In the **Mattermost database connection** section, set the password for the dedicated Mattermost database user that the application nodes use to connect to PostgreSQL. This is separate from the PostgreSQL administrator credentials. The password must meet the same complexity rules as the admin password.
+6. **Geo-redundant backup:** Replicates PostgreSQL backups to Azure's paired region for cross-region disaster recovery. **This setting cannot be changed after deployment.**
+7. **NFS share size (GiB):** Size of the Azure Files (NFS) share used by Mattermost for shared application data. Minimum 100 GiB.
+
+:::note
+Backup retention for PostgreSQL is set to 35 days at deployment time. You can change retention from the Azure portal after the deployment completes.
+:::
+
+![An example of the Azure Native Database setup screen.](/images/azure/azure-native-database.png)
+
+## Step 5: Networking
+
+On the **Networking** tab, configure the virtual network and how Mattermost is exposed to users.
+
+1. **VNet address space (CIDR):** The address space for the virtual network created by the template. Defaults to `10.0.0.0/22`. Pick a range that does not overlap with other VNets you plan to peer with.
+2. **Public IP DNS label:** You must set a **DNS prefix** (label) that is **globally unique** across Azure public cloud; it forms part of your URL and allows public access to your workspace. If the label is already taken, deployment will fail.
+3. **Enable HTTPS on Application Gateway:** When enabled, the Application Gateway terminates TLS using your PFX certificate and HTTP traffic is redirected to HTTPS. When disabled, Mattermost is served over HTTP on the Azure-assigned hostname (suitable for testing, **not recommended for production**).
+4. **PFX certificate** and **PFX password:** Shown when HTTPS is enabled. Upload your PKCS#12 bundle and provide the password used to protect it.
+5. **Custom domain (FQDN):** Shown when HTTPS is enabled. The public hostname Mattermost will use (for example, `mattermost.example.com`). After deployment, point this hostname to the Azure-assigned DNS name of the Application Gateway public IP (typically using a **CNAME** record for subdomains).
+
+![An example of the Azure Native Networking setup screen.](/images/azure/azure-native-networking.png)
+
+## Step 6: Review and create
+
+Review your settings, accept any **Marketplace** terms if prompted, then select **Create**. Provisioning typically takes 20–50 minutes, depending on your PostgreSQL configuration. Allow a few additional minutes after Azure reports the deployment as Succeeded before the application is reachable.
+
+**After deployment completes:**
+
+- In the Azure portal, open the **resource group** you used.
+- Open the **public IP resource attached to your Application Gateway** (often named `<prefix>-ag-pip`). Under **Essentials**, note the **DNS name** (Azure-assigned FQDN).
+- If you deployed **without HTTPS**, your site URL is:
+
+  `http://<dns-label>.<region>.cloudapp.azure.com`
+
+- If you deployed **with HTTPS**, create a DNS record that points your **custom domain** to the Azure-assigned DNS name of the Application Gateway public IP (typically **CNAME** for subdomains; use your provider's apex-compatible record type if using a root domain). Once DNS propagates, your site URL is:
+
+  `https://<your-custom-domain>`
+
+Congratulations! You've successfully deployed a production-ready Mattermost stack on Azure.
+
+## Next steps
+
+- For sizing guidance and reference architectures, see [high-availability-cluster-based-deployment](/deployment-guide/server/high-availability-cluster-based-deployment) and [server architecture](/deployment-guide/scale/server-architecture).
+- For ongoing operations (upgrades, backups, monitoring), follow the standard Mattermost server administration documentation.
+
+## Runbooks
+
+### Upgrade Mattermost server
+
+The VM scale set runs a Mattermost **Marketplace VM image** matching the version you selected in Step 3. Mattermost publishes new image versions for each supported release. To upgrade, point the VMSS at a newer image version in your deployment region. Application data stays in **PostgreSQL** and on the **Azure Files** share; the upgrade rolls application instances to VMs built from the updated image.
+
+#### Before you upgrade
+
+- Review the [important upgrade notes](/administration-guide/upgrade/important-upgrade-notes), and [prepare to upgrade](/administration-guide/upgrade/prepare-to-upgrade-mattermost) for the target version.
+- Confirm **PostgreSQL** backups are current and that you can restore if needed.
+- Pick a target version from the [Mattermost release policy](/product-overview/release-policy).
+
+#### Upgrade steps
+
+1. **Update the VMSS** to the new image version:
+
+   ```sh
+   az vmss update \
+     --resource-group <resource-group> \
+     --name <resource-name-prefix>-vmss \
+     --set virtualMachineProfile.storageProfile.imageReference.version=<new-version>
+   ```
+
+   The VMSS uses a **rolling** upgrade policy and an application health probe on `/api/v4/system/ping`, so instances are replaced in batches while the Application Gateway keeps serving traffic to healthy nodes.
+
+2. **Monitor the rollout** in the Azure portal: open your VMSS → **Instances** (or **Rolling upgrades**) and wait until all instances are healthy and running the new model.
+
+3. **Verify Mattermost**: Verify Mattermost uses the new version via **System Console → About**.

docs/main/deployment-guide/server/linux/deploy-rhel.mdx

@@ -0,0 +1,356 @@
+---
+title: "Deploy Mattermost on Red Hat Enterprise Linux"
+sidebar_label: "Red Hat (RHEL)"
+---
+
+<EditionAvailability tiers="free,professional,enterprise,enterprise-advanced" />
+<DeploymentAvailability modes="self-hosted" />
+
+Install Mattermost Server on Red Hat Enterprise Linux (RHEL), Rocky Linux, AlmaLinux, Oracle Linux 7+, or CentOS Stream. RHEL doesn't have a signed APT-style repository, so this guide installs from the release tarball with manual systemd setup, then walks through the security configuration RHEL deployments typically need (SELinux contexts, firewalld rules, fapolicyd allow rules).
+
+<Note title="Minimum requirements">
+
+- **Operating system**: RHEL 7+, Rocky / Alma 8+, Oracle Linux 7+, CentOS Stream 8+.
+- **Hardware**: 1 vCPU and 2 GB RAM (supports up to ~1,000 users).
+- **Database**: [PostgreSQL 14+](/administration-guide/manage/admin/postgres-migration).
+- **Network**: TCP 80/443 inbound (TLS), 8065 inbound (System Console), 10025 outbound (SMTP relay if used).
+
+</Note>
+
+## Step 1: Get a PostgreSQL database
+
+Choose one of:
+
+- **Install PostgreSQL locally** on the same host. See the [PostgreSQL installation documentation](https://www.postgresql.org/download/).
+- **Use an external PostgreSQL server** and collect connection credentials before Step 2.
+- **Use a managed database service** (AWS RDS, Azure Database for PostgreSQL, etc.).
+
+## Step 2: Prepare the database
+
+Follow the [database preparation](/deployment-guide/server/prepare-database) instructions to create the Mattermost database, user, and grants.
+
+## Step 3: Download the Mattermost Server tarball
+
+SSH onto the target host and download the release. Replace `amd64` with `arm64` for ARM-based hardware.
+
+<Tabs>
+<TabItem value="latest" label="Latest release" default>
+
+```sh
+wget https://releases.mattermost.com/11.10.2/mattermost-11.10.2-linux-amd64.tar.gz
+```
+
+</TabItem>
+<TabItem value="esr" label="Current ESR">
+
+```sh
+wget https://releases.mattermost.com/11.7.11/mattermost-11.7.11-linux-amd64.tar.gz
+```
+
+</TabItem>
+<TabItem value="archive" label="Older releases">
+
+Enterprise and Team Edition releases are listed in the [version archive](/product-overview/version-archive).
+
+</TabItem>
+</Tabs>
+
+## Step 4: Install Mattermost Server
+
+Update existing system packages first:
+
+```sh
+sudo dnf update
+sudo dnf upgrade
+```
+
+Extract the tarball, move it into place, and set ownership:
+
+```sh
+tar -xvzf mattermost*.gz
+sudo mv mattermost /opt
+sudo mkdir /opt/mattermost/data
+sudo useradd --system --user-group mattermost
+sudo chown -R mattermost:mattermost /opt/mattermost
+sudo chmod -R g+w /opt/mattermost
+```
+
+<Note title="Custom paths and users">
+
+If you use a path other than `/opt/mattermost` or a user/group name other than `mattermost`, use that name in every step that follows.
+
+</Note>
+
+Create the systemd unit file at `/etc/systemd/system/mattermost.service`:
+
+<Note>
+
+Earlier versions of this guide had you create the unit file under `/lib/systemd/system/`, which is reserved for unit files installed and owned by a package manager.
+
+</Note>
+
+```ini
+[Unit]
+Description=Mattermost
+After=network.target
+
+[Service]
+Type=notify
+ExecStart=/opt/mattermost/bin/mattermost
+TimeoutStartSec=3600
+KillMode=mixed
+Restart=always
+RestartSec=10
+WorkingDirectory=/opt/mattermost
+User=mattermost
+Group=mattermost
+LimitNOFILE=49152
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Reload systemd:
+
+```sh
+sudo systemctl daemon-reload
+```
+
+## Step 5: Configure and start the server
+
+Back up the default config before editing:
+
+```sh
+sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json
+```
+
+Edit `/opt/mattermost/config/config.json` and set:
+
+- `SqlSettings.DriverName`: `"postgres"`
+- `SqlSettings.DataSource`: `"postgres://mmuser:<mmuser-password>@<host>:5432/mattermost?sslmode=disable&connect_timeout=10"` — replace each placeholder.
+- `ServiceSettings.SiteURL`: the public URL of your deployment (e.g., `https://mattermost.example.com`).
+- (Recommended) [`SupportSettings.SupportEmail`](/administration-guide/configure/site-configuration-settings#support-email-address): the email address users contact for help.
+
+Start the server:
+
+```sh
+sudo systemctl start mattermost
+curl http://localhost:8065
+```
+
+You should see the Mattermost HTML response. Enable on boot:
+
+```sh
+sudo systemctl enable mattermost.service
+```
+
+If start fails on a hardened RHEL system, continue to the [Hardened RHEL configuration](#hardened-rhel-configuration) section below before troubleshooting elsewhere — it's almost always SELinux, firewalld, or fapolicyd.
+
+## Step 6: Update the server
+
+Tarball-based installs are upgraded manually. See [Upgrading Mattermost Server](/administration-guide/upgrade/upgrading-mattermost-server).
+
+## Hardened RHEL configuration
+
+Hardened RHEL installs typically require additional configuration for SELinux, firewalld, and fapolicyd. Each is covered below.
+
+<Tabs>
+<TabItem value="selinux" label="SELinux" default>
+
+RHEL 9 ships with SELinux in enforcing mode. Verify with `sestatus`. If it's enforcing, set the appropriate contexts before starting Mattermost.
+
+**Set the binary context** for `/opt/mattermost/bin`:
+
+```sh
+sudo semanage fcontext -a -t bin_t "/opt/mattermost/bin(/.*)?"
+sudo restorecon -RF /opt/mattermost/bin
+```
+
+**Set the directory context** for `/opt/mattermost`. Check current context:
+
+```sh
+ls -Z /opt/mattermost
+```
+
+If the type is `default_t`, set a web-application context:
+
+```sh
+sudo semanage fcontext -a -t httpd_sys_content_t "/opt/mattermost(/.*)?"
+sudo restorecon -R /opt/mattermost
+```
+
+**Allow Mattermost to bind to port 8065** (or your configured port):
+
+```sh
+sudo semanage port -l | grep 8065
+sudo semanage port -a -t http_port_t -p tcp 8065
+```
+
+**Generate a custom policy** if SELinux blocks something specific. Check denials:
+
+```sh
+sudo ausearch -m avc -ts recent
+sudo cat /var/log/audit/audit.log | grep denied
+```
+
+Generate a policy module from those denials:
+
+```sh
+sudo yum install -y policycoreutils-python-utils
+sudo grep mattermost /var/log/audit/audit.log | audit2allow -M mattermost_policy
+sudo semodule -i mattermost_policy.pp
+```
+
+**Restart and verify**:
+
+```sh
+sudo systemctl restart mattermost
+```
+
+<Tip title="Testing-only fallback">
+
+For debugging, you can temporarily switch SELinux to permissive mode with `sudo setenforce 0`. Re-enable enforcement with `sudo setenforce 1` once contexts are correct. Don't ship a production deployment in permissive mode.
+
+</Tip>
+
+**References**
+
+- [SELinux User's and Administrator's Guide](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/index)
+- [SELinux Project Wiki](https://github.com/SELinuxProject/selinux)
+
+</TabItem>
+<TabItem value="firewalld" label="firewalld">
+
+firewalld is the default firewall on RHEL. Check status:
+
+```sh
+sudo systemctl status firewalld
+```
+
+**Open the Mattermost ports**:
+
+```sh
+sudo firewall-cmd --permanent --add-port=8065/tcp
+sudo firewall-cmd --permanent --add-service=http
+sudo firewall-cmd --permanent --add-service=https
+sudo firewall-cmd --reload
+sudo firewall-cmd --list-all
+```
+
+The output should show `8065/tcp` and the `http` / `https` services.
+
+**Mattermost Calls ports** (if you're running the Calls plugin or the standalone rtcd service):
+
+```sh
+# Integrated Calls plugin
+sudo firewall-cmd --permanent --add-port=8443/udp
+sudo firewall-cmd --permanent --add-port=8443/tcp
+sudo firewall-cmd --reload
+
+# Standalone rtcd (adds API port)
+sudo firewall-cmd --permanent --add-port=8045/tcp
+sudo firewall-cmd --reload
+```
+
+- Port 8443 (UDP/TCP) carries RTC media (audio, video, screen share).
+- Port 8045 (TCP) is the rtcd API.
+- TCP support for RTC requires Calls v0.17+ and rtcd v0.11+.
+
+See the [Calls deployment guide](/deployment-guide/calls/calls-deployment-guide) for the full topology.
+
+</TabItem>
+<TabItem value="fapolicyd" label="fapolicyd">
+
+fapolicyd (File Access Policy Daemon) blocks execution of untrusted binaries. In secure RHEL environments it commonly blocks Mattermost binaries and plugins — the symptom is "operation not permitted" errors in `mattermost.log`.
+
+**Confirm fapolicyd is the cause** by temporarily stopping it:
+
+```sh
+sudo systemctl stop fapolicyd
+sudo systemctl start mattermost
+```
+
+If Mattermost now works, restart fapolicyd and configure an allow rule.
+
+**Identify the denial**:
+
+```sh
+sudo fapolicyd --debug
+```
+
+Look for a line like:
+
+```text
+rule=15 dec=deny_audit perm=execute auid=-1 pid=19735
+  exe=/opt/mattermost/bin/mattermost : path=/opt/mattermost/plugins/focalboard/server/dist/plugin-linux-amd64
+  ftype=application/x-executable trust=0
+```
+
+Note the rule number — your allow rule must be numbered lower so it's evaluated first.
+
+**Create an allow rule** at `/etc/fapolicyd/rules.d/80-mattermost.rules`:
+
+```text
+allow perm=execute exe=/usr/bin/sudo trust=1 : dir=/opt/mattermost/ all trust=0
+allow perm=execute exe=/opt/mattermost/bin/mattermost : dir=/opt/mattermost all trust=0
+allow perm=execute exe=/usr/lib/systemd/systemd trust=1 : dir=/opt/mattermost/ all trust=0
+```
+
+**Validate and load**:
+
+```sh
+sudo fagenrules --check
+sudo fagenrules --load
+sudo systemctl restart fapolicyd
+sudo systemctl restart mattermost
+```
+
+Verify:
+
+```sh
+curl http://localhost:8065
+sudo systemctl status mattermost
+```
+
+**Rules for the standalone rtcd service** (if deployed): create `/etc/fapolicyd/rules.d/80-rtcd.rules`:
+
+```text
+allow perm=execute exe=/usr/bin/sudo trust=1 : dir=/opt/rtcd/ all trust=0
+allow perm=execute exe=/opt/rtcd/bin/rtcd : dir=/opt/rtcd all trust=0
+allow perm=execute exe=/usr/lib/systemd/systemd trust=1 : dir=/opt/rtcd/ all trust=0
+```
+
+Then reload fapolicyd as above. See [RTCD Setup and Configuration](/deployment-guide/calls/calls-rtcd-setup) for the full rtcd install path.
+
+<Note title="Rule numbering">
+
+fapolicyd rules are evaluated in order. Your allow rules must be numbered lower than the deny rule that's blocking Mattermost — `80-` is usually safe with a stock configuration. If denials persist, re-check the rule number from `fapolicyd --debug` and renumber accordingly.
+
+</Note>
+
+**Reference**: [Mattermost and fapolicyd](https://support.mattermost.com/hc/en-us/articles/12167526545172-Mattermost-and-fapolicyd) support article.
+
+</TabItem>
+</Tabs>
+
+## Remove Mattermost
+
+Stop the server, back up any data you need, then remove the install directory:
+
+```sh
+sudo systemctl stop mattermost
+sudo rm -rf /opt/mattermost
+sudo rm /lib/systemd/system/mattermost.service
+sudo userdel mattermost
+```
+
+<Important title="Back up before removing">
+
+`/opt/mattermost` contains `config/`, `logs/`, `plugins/`, `client/plugins/`, and `data/`. Back these up before running `rm -rf` if you may need to restore.
+
+</Important>
+
+## Next steps
+
+- [Set up an NGINX reverse proxy](/deployment-guide/server/setup-nginx-proxy)
+- [Set up TLS](/deployment-guide/server/setup-tls)

docs/main/deployment-guide/server/linux/deploy-tar.mdx

@@ -0,0 +1,200 @@
+---
+title: "Deploy Mattermost manually from the tarball"
+sidebar_label: "Manual (tarball)"
+---
+
+<EditionAvailability tiers="free,professional,enterprise,enterprise-advanced" />
+<DeploymentAvailability modes="self-hosted,air-gapped" />
+
+Install Mattermost Server on any 64-bit Linux distribution directly from the release tarball. This is the most flexible install method and usually the choice for:
+
+- Distributions Mattermost doesn't package directly (Arch, SUSE, Gentoo, Alpine, …)
+- Air-gapped environments where tarballs are staged on an internal mirror
+- Custom paths, users, or systemd unit configurations
+- Environments where you control every version pin and don't want a package manager auto-upgrade
+
+<Tip title="Use a packaged install if it fits">
+
+If you're on **Ubuntu / Debian**, use the [APT-based install](./deploy-ubuntu) for automatic security updates. If you're on **RHEL / Rocky / Alma / Oracle**, use the [RHEL install](./deploy-rhel) — it covers SELinux, firewalld, and fapolicyd configuration too.
+
+</Tip>
+
+<Note title="Minimum requirements">
+
+- **Operating system**: any 64-bit Linux distribution with `systemd` (or a comparable service manager).
+- **Hardware**: 1 vCPU and 2 GB RAM (supports up to ~1,000 users).
+- **Database**: [PostgreSQL 14+](/administration-guide/manage/admin/postgres-migration).
+- **Network**: TCP 80/443 inbound (TLS), 8065 inbound (System Console), 10025 outbound (SMTP relay if used).
+
+</Note>
+
+## Step 1: Get a PostgreSQL database
+
+Choose one of:
+
+- **Install PostgreSQL locally** on the same host. See the [PostgreSQL installation documentation](https://www.postgresql.org/download/).
+- **Use an external PostgreSQL server** and collect connection credentials before Step 2.
+- **Use a managed database service** (AWS RDS, Azure Database for PostgreSQL, etc.).
+
+## Step 2: Prepare the database
+
+Follow the [database preparation](/deployment-guide/server/prepare-database) instructions to create the Mattermost database, user, and grants.
+
+## Step 3: Download the Mattermost Server tarball
+
+SSH onto the target host and download the release. Replace `amd64` with `arm64` for ARM-based hardware.
+
+<Tabs>
+<TabItem value="latest" label="Latest release" default>
+
+```sh
+wget https://releases.mattermost.com/11.10.2/mattermost-11.10.2-linux-amd64.tar.gz
+```
+
+</TabItem>
+<TabItem value="esr" label="Current ESR">
+
+```sh
+wget https://releases.mattermost.com/11.7.11/mattermost-11.7.11-linux-amd64.tar.gz
+```
+
+</TabItem>
+<TabItem value="archive" label="Older releases">
+
+Enterprise and Team Edition releases are listed in the [version archive](/product-overview/version-archive).
+
+</TabItem>
+</Tabs>
+
+<Note title="Air-gapped installs">
+
+In an air-gapped environment, stage the tarball on your operator workstation, verify the SHA-256 and PGP signature, then transfer it across the boundary. See the [air-gapped deployment runbook](/deployment-guide/air-gapped-operations/quick-start-runbook) for the full procedure.
+
+</Note>
+
+## Step 4: Install Mattermost Server
+
+Extract the tarball, move it into place, and set ownership.
+
+```sh
+tar -xvzf mattermost*.gz
+sudo mv mattermost /opt
+sudo mkdir /opt/mattermost/data
+sudo useradd --system --user-group mattermost
+sudo chown -R mattermost:mattermost /opt/mattermost
+sudo chmod -R g+w /opt/mattermost
+```
+
+<Note title="Custom paths and users">
+
+If you use a path other than `/opt/mattermost` or a user/group name other than `mattermost`, use that name in every step that follows.
+
+</Note>
+
+Create the systemd unit file at `/etc/systemd/system/mattermost.service`:
+
+<Note>
+
+Earlier versions of this guide had you create the unit file under `/lib/systemd/system/`, which is reserved for unit files installed and owned by a package manager.
+
+</Note>
+
+```ini
+[Unit]
+Description=Mattermost
+After=network.target
+
+[Service]
+Type=notify
+ExecStart=/opt/mattermost/bin/mattermost
+TimeoutStartSec=3600
+KillMode=mixed
+Restart=always
+RestartSec=10
+WorkingDirectory=/opt/mattermost
+User=mattermost
+Group=mattermost
+LimitNOFILE=49152
+
+[Install]
+WantedBy=multi-user.target
+```
+
+<Note title="Local database">
+
+If PostgreSQL is on the same host, add to the `[Unit]` section so Mattermost won't start before the database is ready:
+
+```ini
+After=postgresql.service
+BindsTo=postgresql.service
+```
+
+</Note>
+
+Reload systemd:
+
+```sh
+sudo systemctl daemon-reload
+```
+
+## Step 5: Configure and start the server
+
+Back up the default config before editing:
+
+```sh
+sudo cp /opt/mattermost/config/config.json /opt/mattermost/config/config.defaults.json
+```
+
+Edit `/opt/mattermost/config/config.json` and set:
+
+- `SqlSettings.DriverName`: `"postgres"`
+- `SqlSettings.DataSource`: `"postgres://mmuser:<mmuser-password>@<host>:5432/mattermost?sslmode=disable&connect_timeout=10"` — replace each placeholder.
+- `ServiceSettings.SiteURL`: the public URL of your deployment (e.g., `https://mattermost.example.com`).
+- (Recommended) [`SupportSettings.SupportEmail`](/administration-guide/configure/site-configuration-settings#support-email-address): the email address users contact for help.
+
+Start the server:
+
+```sh
+sudo systemctl start mattermost
+curl http://localhost:8065
+```
+
+You should see the Mattermost HTML response. Enable on boot:
+
+```sh
+sudo systemctl enable mattermost.service
+```
+
+## Step 6: Update the server
+
+Tarball installs are upgraded manually — there's no package manager to pull the new version. See [Upgrading Mattermost Server](/administration-guide/upgrade/upgrading-mattermost-server) for the step-by-step procedure. The summary:
+
+1. Stop the running server (`sudo systemctl stop mattermost`).
+2. Back up `config/`, `data/`, `plugins/`, and your PostgreSQL database.
+3. Download the new tarball.
+4. Extract over the install directory (preserving `config/`, `data/`, `plugins/`).
+5. Reset ownership and permissions.
+6. Start the server.
+
+## Remove Mattermost
+
+Stop the server, back up data you need to keep, then remove the install:
+
+```sh
+sudo systemctl stop mattermost
+sudo rm -rf /opt/mattermost
+sudo rm /lib/systemd/system/mattermost.service
+sudo userdel mattermost
+```
+
+<Important title="Back up before removing">
+
+`/opt/mattermost` contains `config/`, `logs/`, `plugins/`, `client/plugins/`, and `data/`. Back these up before running `rm -rf` if you may need to restore.
+
+</Important>
+
+## Next steps
+
+- [Set up an NGINX reverse proxy](/deployment-guide/server/setup-nginx-proxy)
+- [Set up TLS](/deployment-guide/server/setup-tls)
+- For air-gapped deployments: [Air-gapped deployment runbook](/deployment-guide/air-gapped-operations/quick-start-runbook), [Configure for Air-Gapped Operation](/deployment-guide/air-gapped-operations/disable-phone-home-features)

docs/main/deployment-guide/server/linux/deploy-ubuntu.mdx

@@ -0,0 +1,144 @@
+---
+title: "Deploy Mattermost on Ubuntu or Debian"
+sidebar_label: "Ubuntu / Debian"
+---
+
+<EditionAvailability tiers="free,professional,enterprise,enterprise-advanced" />
+<DeploymentAvailability modes="self-hosted" />
+
+Install Mattermost Server on Ubuntu or Debian from the signed Mattermost APT repository. The same `.deb` packages cover single-host installs and clustered deployments via tools like Packer.
+
+:::info[Minimum requirements]
+- **Operating system**: Ubuntu 20.04 / 22.04 / 24.04 LTS, or Debian (current stable). Other Debian-family distributions usually work but aren't tested by Mattermost.
+- **Hardware**: 1 vCPU and 2 GB RAM (supports up to ~1,000 users).
+- **Database**: [PostgreSQL 14+](/administration-guide/manage/admin/postgres-migration).
+- **Network**: TCP 80/443 inbound (TLS), 8065 inbound (System Console), 10025 outbound (SMTP relay if used).
+:::
+
+## Step 1: Get a PostgreSQL database
+
+Mattermost requires PostgreSQL. Choose one of:
+
+- **Install PostgreSQL locally** on the same host. Follow the [PostgreSQL installation documentation](https://www.postgresql.org/download/).
+- **Use an external PostgreSQL server**. Collect the connection credentials (hostname, port, database, username, password) before starting Step 2.
+- **Use a managed database service** (AWS RDS, Azure Database for PostgreSQL, etc.).
+
+## Step 2: Prepare the database
+
+Follow the [database preparation](/deployment-guide/server/prepare-database) instructions to create the Mattermost database, user, and grants.
+
+## Step 3: Add the Mattermost APT repository
+
+:::important[GPG key change]
+The GPG public key has changed. Either [import the new public key](https://deb.packages.mattermost.com/pubkey.gpg) or run the repository setup script in the next step (recommended). Existing installations should remove the old key before adding the new one:
+
+For Ubuntu 22.04 LTS and 24.04 LTS:
+
+```sh
+sudo rm /usr/share/keyrings/mattermost-archive-keyring.gpg
+curl -sL -o- https://deb.packages.mattermost.com/pubkey.gpg \
+  | gpg --dearmor \
+  | sudo tee /usr/share/keyrings/mattermost-archive-keyring.gpg > /dev/null
+```
+:::
+
+Run the repository setup script:
+
+```sh
+curl -o- https://deb.packages.mattermost.com/repo-setup.sh | sudo bash -s mattermost
+```
+
+This configures the Mattermost APT repository, a PostgreSQL repository, an NGINX web server (used as a reverse proxy), and certbot for issuing and renewing SSL certificates.
+
+## Step 4: Install Mattermost Server
+
+Update your APT cache and any pending system packages:
+
+```sh
+sudo apt update
+```
+
+Install the latest Mattermost Server:
+
+```sh
+sudo apt install mattermost -y
+```
+
+Mattermost installs to `/opt/mattermost`. The package creates a `mattermost` user and group and a systemd unit file. The service is **not** enabled or started at this point.
+
+:::note[systemd dependencies]
+The Mattermost package doesn't declare a database dependency in its systemd unit (the package is used for both single-host and external-database installs). If you installed PostgreSQL on the same host, add the following to the `[Unit]` section of `/lib/systemd/system/mattermost.service`:
+
+```ini
+After=postgresql.service
+BindsTo=postgresql.service
+```
+:::
+
+## Step 5: Configure the server
+
+Copy the default configuration to the active config file with the right ownership and permissions:
+
+```sh
+sudo install -C -m 600 -o mattermost -g mattermost \
+  /opt/mattermost/config/config.defaults.json \
+  /opt/mattermost/config/config.json
+```
+
+Edit `/opt/mattermost/config/config.json` and set:
+
+- `SqlSettings.DriverName`: `"postgres"`
+- `SqlSettings.DataSource`: `"postgres://mmuser:<mmuser-password>@<host>:5432/mattermost?sslmode=disable&connect_timeout=10"` — replace each placeholder.
+- `ServiceSettings.SiteURL`: the public URL of your deployment (e.g., `https://mattermost.example.com`).
+- (Recommended) [`SupportSettings.SupportEmail`](/administration-guide/configure/site-configuration-settings#support-email-address): the email address users contact for help.
+
+:::note[TLS mode for `DataSource`]
+The `sslmode` value depends on your database environment. The two relevant options are `disable` and `require`. Managed services such as AWS Lightsail require `sslmode=require`. Check your provider's documentation.
+:::
+
+Start the server:
+
+```sh
+sudo systemctl start mattermost
+```
+
+Verify it's running:
+
+```sh
+curl http://localhost:8065
+```
+
+You should see the Mattermost HTML response. Enable the service on boot:
+
+```sh
+sudo systemctl enable mattermost.service
+```
+
+## Step 6: Update Mattermost
+
+When a new release is published, update through APT:
+
+```sh
+sudo systemctl stop mattermost
+sudo apt update && sudo apt upgrade
+sudo systemctl start mattermost
+```
+
+:::important[Stop the server before upgrading]
+`apt upgrade` will replace the Mattermost binary while it's running. Stop the systemd service first to avoid corrupt state.
+:::
+
+## Remove Mattermost
+
+```sh
+sudo systemctl stop mattermost
+sudo apt remove --purge mattermost
+```
+
+This removes the package but leaves `/opt/mattermost/data`, `/opt/mattermost/logs`, `/opt/mattermost/plugins`, and `/opt/mattermost/config` in place. Back these up before deleting if you may need to restore.
+
+## Next steps
+
+- [Set up an NGINX reverse proxy](/deployment-guide/server/setup-nginx-proxy)
+- [Set up TLS](/deployment-guide/server/setup-tls)
+- [Configure Mattermost](/administration-guide/configure/configure-index) and [onboard your users](/administration-guide/onboard/onboard-index)