How to Install Mattermost on the Latest Ubuntu and Debian Server

Mattermost is an open-source collaboration platform for team messaging, file sharing, channels, and integrations. It is a good fit when you want a private alternative to hosted chat services and need control over your data.

This guide uses the official Mattermost Docker deployment on a fresh Ubuntu or Debian server. Docker keeps the application and PostgreSQL database together in a repeatable setup, while the included NGINX service can handle the public web endpoint.

Before You Start

You will need:

• A fresh 64-bit Ubuntu LTS or Debian server with SSH access
• A sudo-enabled user
• A domain or subdomain, such as chat.example.com, pointing to the server
• At least 1 vCPU and 2 GB RAM for a small team; allow more room as users and file uploads grow
• Ports 22, 80, and 443 available

Use a domain that resolves before requesting a certificate. If another web server is already listening on ports 80 or 443, stop it or plan the deployment around an existing reverse proxy.

Update the Server

Connect to the VPS and apply the latest system updates:

sudo apt update
sudo apt full-upgrade -y

Install a few utilities used by the setup:

sudo apt install -y ca-certificates curl git ufw

Allow SSH and web traffic through UFW before enabling it:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Install Docker and Compose

Install Docker Engine and then add the Compose plugin:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo apt install -y docker-compose-plugin
sudo systemctl enable --now docker
rm get-docker.sh

Verify the installation:

docker --version
docker compose version

The current Mattermost deployment uses the docker compose command with a space. The older docker-compose binary is not required.

Download the Mattermost Deployment

Create a directory for the deployment and clone Mattermost's official Docker repository:

sudo mkdir -p /opt/mattermost-docker
sudo chown "$USER":"$USER" /opt/mattermost-docker
cd /opt/mattermost-docker
git clone https://github.com/mattermost/docker.git .

Copy the example environment file:

cp env.example .env

Open it for editing:

nano .env

At minimum, set these values. Replace the examples with your own domain, email address, and long database password:

DOMAIN=chat.example.com
POSTGRES_PASSWORD=replace-with-a-long-random-password
MM_SUPPORTSETTINGS_SUPPORTEMAIL=admin@example.com
MATTERMOST_IMAGE=team-edition
MATTERMOST_IMAGE_TAG=11.9.0
MM_SERVICESETTINGS_SITEURL=https://chat.example.com

The exact Mattermost release changes over time. Before a new deployment, check the current Mattermost release and use a specific published image tag rather than an unpinned latest tag.

Create the persistent application directories and give the container's application user ownership:

mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
sudo chown -R 2000:2000 ./volumes/app/mattermost

The PostgreSQL volume is created by Compose and should not be deleted during normal troubleshooting or upgrades.

Configure HTTPS

The repository includes an NGINX deployment. If the DNS record already points to this server and port 80 is open, request a certificate using the helper script:

bash scripts/issue-certificate.sh -d chat.example.com -o "${PWD}/certs"

Open .env again and configure the certificate paths:

CERT_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/fullchain.pem
KEY_PATH=./certs/etc/letsencrypt/live/${DOMAIN}/privkey.pem

If you already manage TLS outside this stack, you can instead use the supplied certificate files and the paths documented in the official Mattermost Docker guide.

Start Mattermost

Start the database, application, and included NGINX service:

docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

Check the containers:

docker compose ps
docker compose logs -f --tail=100

When the services are healthy, open:

https://chat.example.com

Create the first system administrator account from the setup screen, then sign in and review System Console before inviting your team.

For a quick, temporary check without the included NGINX service, you can use:

docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d

That mode is useful for testing at http://SERVER_IP:8065, but HTTPS through a domain and reverse proxy is the better production setup.

Configure Mattermost

After signing in, review these settings:

1. Set the site URL to the final HTTPS address.
2. Configure SMTP under System Console → Environment → SMTP so the server can send invitations and password-reset messages.
3. Set file storage and maximum upload size for your workload.
4. Enable only the integrations and plugins your team needs.
5. Invite users and create channels for the teams or projects you want to organize.

If you prefer object storage for files, configure an S3-compatible bucket instead of keeping every upload on the VPS disk.

Maintain and Update Mattermost

Back up .env and the volumes directory before upgrades. The database, configuration, uploaded files, logs, plugins, and search indexes are stored there.

To update the deployment:

cd /opt/mattermost-docker
git pull
nano .env
docker compose pull
docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

Review changes to env.example whenever you pull the repository. Keep the Mattermost image tag pinned to a specific release in production so an unexpected image update does not happen during a routine restart.

Troubleshooting

The site does not load

Confirm that the DNS record resolves to the VPS and that ports 80 and 443 are reachable. Then inspect the service status:

docker compose ps
docker compose logs --tail=200 mattermost

The application cannot connect to PostgreSQL

Make sure the POSTGRES_PASSWORD value in .env is consistent with the database configuration. If you changed credentials after the database was initialized, do not delete the volume; review the official PostgreSQL troubleshooting guidance and recover the credentials carefully.

File uploads fail

Check free disk space and ownership of the Mattermost directories:

df -h
sudo chown -R 2000:2000 /opt/mattermost-docker/volumes/app/mattermost

Also review the configured upload limit and the NGINX request-size setting if large files are expected.

Frequently Asked Questions

Is Docker suitable for a production Mattermost server?

Yes for many small and medium deployments. Mattermost officially documents Docker for Linux, but larger or high-availability installations should be designed with separate database, storage, and scaling components.

Can I use Debian instead of Ubuntu?

Yes. The Docker deployment runs on a Docker-compatible Linux host, so the same workflow applies to current Debian releases. Use the Docker installation method appropriate for your exact operating system.

Where is Mattermost data stored?

The Docker deployment persists data in the volumes directory, including the PostgreSQL data and Mattermost application files. Back up this directory before upgrades or server migrations.

How do I remove the installation?

Stop the stack first and back up any data you need. Never remove the volumes directory as a casual troubleshooting step because it contains the database and uploaded files.

Get Started

Deploy a fresh CloudBlast VPS, point a domain to it, and run Mattermost with persistent storage and HTTPS. Review CloudBlast plans and pricing to choose a server size that fits your team.

For version-specific changes, consult the official Mattermost Docker guide, server requirements, and official Docker repository.