Posted inHomeLab

Ditch Slack: Self-Host Mattermost with Docker for Total Data Control

HomeLab tutorial - IT technology blog
HomeLab tutorial - IT technology blog

Take Back Your Data Sovereignty

Slack and Microsoft Teams are the industry standards for a reason, but they require a leap of faith. Every message, private file, and internal strategy document lives on a server you don’t control. For many developers, this is a deal-breaker. Mattermost offers a polished, open-source alternative that looks and feels like Slack but keeps your data strictly within your own walls.

Deploying Mattermost is a great way to level up your HomeLab skills. It moves you beyond running single containers and into the world of multi-tier applications where databases and app servers must work in sync. In practice, a small instance for 5-10 users typically idles at around 800MB of RAM, making it a perfect candidate for a modest VPS or an old laptop.

Docker simplifies this entire stack. Instead of manually tuning PostgreSQL or wrestling with Linux dependencies, we can define the whole environment in one file. This portability is a lifesaver. If you ever upgrade your hardware, your entire communication hub moves with you in a single folder migration.

What You’ll Need

Before pulling any images, check that your environment meets these basic requirements:

  • A Linux server (Ubuntu 22.04 LTS or 24.04 LTS works best).
  • Docker Engine (v24.0+) and Docker Compose (v2.0+).
  • At least 2GB of RAM to handle search indexing and file processing comfortably.
  • A basic grasp of the Linux terminal.

Step 1: Organize Your Files

Organization is key to a manageable HomeLab. Keeping your persistent data in a centralized directory makes backups much easier to automate. Let’s create a dedicated space for Mattermost and its database.

mkdir -p ~/homelab/mattermost/volumes/app/mattermost/{data,logs,config,plugins,client-plugins}
mkdir -p ~/homelab/mattermost/volumes/db/data
cd ~/homelab/mattermost

Permissions can be a common stumbling block. The Mattermost container runs as a non-root user with UID 2000. We need to hand over ownership of the application folders so the container can actually write logs and store your uploads:

sudo chown -R 2000:2000 ~/homelab/mattermost/volumes/app/mattermost

Step 2: Define the Stack

Mattermost needs a reliable database to store your messages. While MySQL is an option, PostgreSQL is the gold standard for Mattermost performance. We will use Docker Compose to link the two together seamlessly.

Create your configuration file:

nano docker-compose.yml

Paste this configuration into the editor. Note that I’ve updated the database to PostgreSQL 15 for better performance:

services:
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    volumes:
      - ./volumes/db/data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=mmuser
      - POSTGRES_PASSWORD=mmuser_password
      - POSTGRES_DB=mattermost

  mattermost:
    image: mattermost/mattermost-team-edition:latest
    restart: unless-stopped
    depends_on:
      - db
    environment:
      - MM_SQLSETTINGS_DRIVERNAME=postgres
      - MM_SQLSETTINGS_DATASOURCE=postgres://mmuser:mmuser_password@db:5432/mattermost?sslmode=disable&connect_timeout=10
    volumes:
      - ./volumes/app/mattermost/config:/mattermost/config
      - ./volumes/app/mattermost/data:/mattermost/data
      - ./volumes/app/mattermost/logs:/mattermost/logs
      - ./volumes/app/mattermost/plugins:/mattermost/plugins
      - ./volumes/app/mattermost/client-plugins:/mattermost/client/plugins
    ports:
      - "8065:8065"

Security Tip: Replace mmuser_password with something complex. Even if this is only for home use, using default passwords is a habit you want to break early.

Step 3: Fire It Up

With the file saved, it’s time to pull the images and start the services. Run this command from your Mattermost directory:

docker compose up -d

Docker will now download roughly 300MB of images and initialize the database. You can verify the status by running:

docker compose ps

If the status column shows “Up” for both containers, the hard part is over.

Step 4: The First Login

Navigate to http://your-server-ip:8065 in your browser. The first person to arrive becomes the System Administrator.

  1. Create the Admin: Set up your username and a strong password. This account controls the entire server.
  2. Start a Team: Mattermost uses “Teams” as the top-level container. You might name yours “HomeLab” or “Family Hub”.
  3. Configure the URL: Head to the System Console > Environment > Web Server. Set the Site URL to your server’s IP (e.g., http://192.168.1.50:8065) so links in emails work correctly.

Step 5: Maintenance and Monitoring

A server you can’t monitor is a server that will eventually fail. I recommend checking the logs immediately after the first launch to ensure there aren’t any hidden permission issues.

Watch the logs in real-time with this command:

docker compose logs -f mattermost

If you see “Server is listening on :8065,” you are in the clear. If you see “permission denied” errors, re-run the chown command from Step 1.

Testing Data Persistence

Never trust a volume until you’ve tested it. Post a few test messages, then restart the stack:

docker compose down
docker compose up -d

If your messages are still there when you log back in, your data is safely stored on your host machine’s drive, not just inside the temporary container.

Next Steps: Security

Right now, your traffic is unencrypted. If you plan to access Mattermost over the internet or use the mobile app, you must set up HTTPS. The easiest way to do this is by placing Mattermost behind a reverse proxy like Nginx Proxy Manager or Traefik with a Let’s Encrypt certificate.

Best Practices for the Long Haul

As you start using Mattermost daily, keep these three tips in mind:

  • Automate Backups: Use a tool like Restic or a simple cron job to back up the ~/homelab/mattermost/volumes folder nightly.
  • Easy Updates: When a new version drops, just run docker compose pull and docker compose up -d. Docker will swap the binary while keeping your data intact.
  • Integrations: Mattermost shines when it’s connected. Try setting up an incoming webhook to get notifications from your GitHub repos or your Home Assistant sensors.

You’ve just built a private, secure communication hub. You aren’t just a user anymore; you’re the owner of the platform.

Share:
Tags: