Deploy Mattermost with the mattermost-team-chat template

Stand up Mattermost Team Edition, an open-source team-chat platform, on a single Quake AI instance using the validated OpenTofu template mattermost-team-chat. You apply the template, serve it over HTTPS through Caddy, set the public site URL, sign up the first admin account, create a team and a channel, and invite a teammate.

Mattermost keeps your team's chat on infrastructure you own. You run it yourself; this is a self-hosted tool you operate, not a managed multi-tenant service.

Prerequisites#

You need:

• OpenTofu 1.6.0 or later (or Terraform 1.6.0 or later) installed locally.
• Your OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An SSH keypair that already exists in your project. Record its name for the key_name variable.
• A copy of the mattermost-team-chat template directory from the template reference page.
• A domain you can point at the instance.

Step 1: Apply the template#

Copy the template's example variables file and set key_name:

cp terraform.tfvars.example terraform.tfvars

key_name = "YOUR_KEY_NAME"

Initialize, preview, and apply:

tofu init
tofu plan
tofu apply

OpenTofu provisions a private network, a router, a security group, a block volume mounted at /var/lib/docker, an instance, and a floating IP. On first boot, cloud-init installs Docker Engine, generates the PostgreSQL password into /opt/mattermost/.env, and starts only postgres. Mattermost needs a real public URL before invite links, OAuth, and calls work, so the app container waits until you finish configuration.

Read the outputs and record floating_ip:

tofu output

Step 2: Point a domain at the host and serve HTTPS with Caddy#

1. Create a DNS A record for your domain (for example chat.example.com) pointing at YOUR_FLOATING_IP. Follow How to point a domain at a Quake AI resource. Wait until it resolves:

dig +short chat.example.com

1. SSH to the instance and create /opt/mattermost/Caddyfile:

chat.example.com {
  reverse_proxy 127.0.0.1:8065
}

1. Add Caddy to /opt/mattermost/docker-compose.yml:

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    network_mode: host
    volumes:
      - /opt/mattermost/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
volumes:
  caddy_data:

For background on certificates, see How to issue and auto-renew a TLS certificate with Let's Encrypt.

Step 3: Set the site URL and start Mattermost#

Edit /opt/mattermost/.env and set:

MM_SERVICESETTINGS_SITEURL=https://chat.example.com

Start the full stack:

cd /opt/mattermost
sudo docker compose up -d

Step 4: Sign up the first admin account#

Open https://chat.example.com and sign up. The first account to sign up becomes the System Console admin.

Step 5: Create a team and a channel#

1. Select Create a team, name it, and confirm.
2. Inside the team, select + next to Channels > Create new channel, name it (for example general-eng), and create it.

Step 6: Invite a teammate#

1. Inside the team, select Invite people.
2. Enter a teammate's email, or copy the generated invite link and share it directly.
3. The teammate follows the link to sign up and joins the team.

What you built#

• Applied the mattermost-team-chat template to provision a network, security group, data volume, instance, and floating IP, with PostgreSQL started automatically by cloud-init
• Served Mattermost over HTTPS by pointing a domain at the floating IP and routing it through a Caddy reverse proxy
• Set the public site URL and started the Mattermost app container
• Signed up the first admin account
• Created a team and a channel
• Invited a teammate

Scope of this deployment#

This template runs a single-VM Mattermost host, not a managed team-chat cloud. The instance is CPU-only and runs in one region, and it bundles PostgreSQL as a container on the same host, sized for a small-to-mid team. You operate the instance, Docker, Mattermost, the database, and the data volume yourself: back them up, patch them, and size up the flavor as your team grows. Mattermost's own scaling guidance recommends significantly more compute for large enterprise deployments.

Next steps#

• Mattermost team-chat template: the template reference, parameters, and resource map
• Self-managed PostgreSQL template: the database to point at when you outgrow the bundled one
• Security hardening checklist: tighten SSH access and exposure before you connect production traffic

Clean up#

When you no longer need the deployment, destroy everything the template created:

tofu destroy

Then remove the DNS A record you created in step 2. Because Mattermost and its database both live on the instance and its attached volume, tofu destroy removes them along with the infrastructure.