Install, operations, plugins, bots, upgrades, and troubleshooting for the Kalymoon Mattermost stack.
| Item | Value |
|---|---|
| Public URL | https://mattermost.kalymoon.com |
| Reverse Proxy | JenKalymoon (Nginx, handles SSL/TLS) |
| Mattermost VM | 192.168.5.131 |
| Upstream port | 8065 |
Traffic flow: Internet → mattermost.kalymoon.com (TLS terminates on JenKalymoon) → http://192.168.5.131:8065
🔒 SSL/TLS is terminated on JenKalymoon, not inside the Mattermost VM.
| Item | Value |
|---|---|
| Install path | /opt/mattermost |
| Systemd service | mattermost.service |
| Config file | /opt/mattermost/config/config.json |
| Plugins folder | /opt/mattermost/plugins |
| Database | PostgreSQL (local, on Mattermost VM) |
Quick health check:
systemctl status mattermost --no-pager
sudo ss -ltnp | grep 8065
curl -sS -I http://127.0.0.1:8065 | head
# Extract tarball to /opt/mattermost, then:
sudo chown -R mattermost:mattermost /opt/mattermost
sudo systemctl daemon-reload
sudo systemctl enable --now mattermost
sudo ss -ltnp | grep 8065 # confirm listening on 8065
Mattermost connects via SqlSettings.DataSource in /opt/mattermost/config/config.json.
Working DataSource:
"DataSource": "postgres://mmuser:mostest@localhost/mattermost?sslmode=disable\u0026connect_timeout=10\u0026binary_parameters=yes"
⚠️
\u0026is just&— a JSON escape. Don't remove it. The DB name must bemattermost(notmattermost_test).
Useful DB commands:
# Check DB exists
sudo -u postgres psql -c "\l" | grep mattermost
# Reset mmuser password
sudo -u postgres psql -c "ALTER USER mmuser WITH PASSWORD 'mostest';"
On the Mattermost VM:
curl -sS -I http://127.0.0.1:8065 | head
sudo ss -ltnp | grep 8065
sudo journalctl -u mattermost -n 120 --no-pager
On JenKalymoon:
curl -sS -I http://192.168.5.131:8065 | head
sudo tail -n 80 /var/log/nginx/error.log
sudo nginx -t && sudo systemctl reload nginx
Once curl http://127.0.0.1:8065 succeeds on the VM, the 502 should clear. ✅
Install using a prebuilt release bundle (not a source zip):
sudo -u mattermost /opt/mattermost/bin/mmctl plugin add /path/to/plugin.tar.gz --local
sudo -u mattermost /opt/mattermost/bin/mmctl plugin enable <plugin_id> --local
sudo systemctl restart mattermost
# Verify
sudo -u mattermost /opt/mattermost/bin/mmctl plugin list --local
# Test in a channel
/todo help
If you see a JS popup error, it's usually cache-related. Try a hard refresh or log out and back in. Slash commands typically still work even when the UI is misbehaving.
Rather than using the archived Giphy plugin (which requires building and often breaks on upgrades), a GIF bot via slash command was implemented instead.
/gifmm-upgrade)The mm-upgrade script does not auto-upgrade — it only runs when called with a version:
sudo mm-upgrade 11.3.0
What it does:
/opt/mattermost/config and /opt/mattermost/dataVerify after upgrade:
/opt/mattermost/bin/mmctl version --local
systemctl status mattermost --no-pager
1. Download blocked (403 Forbidden)
Use a browser user-agent:
sudo curl -fL -A "Mozilla/5.0" -o mattermost-$VERSION-linux-amd64.tar.gz \
https://releases.mattermost.com/$VERSION/mattermost-$VERSION-linux-amd64.tar.gz
2. Extract path mismatch (mv: cannot stat '/opt/mattermost')
Ensure extraction happens into /opt and verify the directory exists after extracting.
3. PostgreSQL auth failure after upgrade
Symptoms: Mattermost won't bind to 8065, Nginx shows 502, logs show password authentication failed for user "mmuser".
Fix:
sudo -u postgres psql -c "ALTER USER mmuser WITH PASSWORD 'mostest';"
4. Wrong DB name in DataSource (mattermost_test vs mattermost)
Symptoms: Mattermost fails to start and never listens on 8065.
Fix: Ensure DataSource points to mattermost, not mattermost_test:
...@localhost/mattermost?...
5. systemd warning after upgrade
sudo systemctl daemon-reload
sudo systemctl restart mattermost
systemctl status mattermost --no-pager
sudo ss -ltnp | grep 8065
curl -sS -I http://127.0.0.1:8065 | head
curl http://127.0.0.1:8065 fails → issue is with Mattermost, DB, or config# Check DataSource
sudo grep -n '"DataSource"' /opt/mattermost/config/config.json
# Reset password
sudo -u postgres psql -c "ALTER USER mmuser WITH PASSWORD 'mostest';"
# Confirm DB exists
sudo -u postgres psql -c "\l" | grep mattermost
mm-upgrade to always extract into /opt, verify directory post-extract, warn if DataSource points to mattermost_test, add GitHub fallback download, and prune old backups| Item | Value |
|---|---|
| Mattermost version | 11.3.0 |
| VM IP | 192.168.5.131 |
| Service | active (running) |
| Listening | *:8065 |
| DataSource | ...@localhost/mattermost?... |
| Reverse proxy | JenKalymoon Nginx + TLS certs |