Mattermost es una plataforma de mensajería para equipos, de código abierto y autohospedada, con canales, mensajes directos, hilos, búsqueda y webhooks. Es una alternativa a Slack en la que los mensajes y archivos se quedan en tu servidor. En este tutorial instalarás Mattermost en Ubuntu 24.04 a partir del paquete oficial, con PostgreSQL como base de datos y Nginx como proxy inverso con HTTPS.
Requisitos previos
- Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 2 vCPU y 4 GB de RAM (suficiente para equipos de unos cientos de usuarios).
- Un usuario no root con privilegios
sudo. - Un subdominio (en esta guía,
chat.your_domain) con un registro DNS A que apunte a la IP pública del servidor. - Los puertos 80 y 443 accesibles desde Internet.
Paso 1: Instalar y preparar PostgreSQL
Mattermost usa PostgreSQL como base de datos. Instala la versión que incluye Ubuntu 24.04 (PostgreSQL 16):
sudo apt update
sudo apt install postgresql
Abre la consola de PostgreSQL como el superusuario postgres:
sudo -u postgres psql
Crea el usuario mmuser y una base de datos de la que sea propietario. Al ser propietario, tiene permisos sobre el esquema public, algo que desde PostgreSQL 15 ya no se concede a todos los usuarios. Sustituye your_strong_password por una contraseña larga y aleatoria:
CREATE USER mmuser WITH PASSWORD 'your_strong_password';
CREATE DATABASE mattermost OWNER mmuser;
\q
Comprueba que el usuario puede conectarse por TCP, que es como lo hará Mattermost:
psql -h 127.0.0.1 -U mmuser -d mattermost -c "SELECT current_user;"
current_user
--------------
mmuser
(1 row)
Paso 2: Descargar Mattermost
Consulta la última versión estable en la página de descargas de Mattermost (https://mattermost.com/download/) o en sus notas de versión, y guárdala en una variable. Sustituye X.Y.Z por el número real:
MM_VERSION=X.Y.Z
cd /tmp
wget "https://releases.mattermost.com/${MM_VERSION}/mattermost-${MM_VERSION}-linux-amd64.tar.gz"
Extrae el paquete en /opt y crea el directorio donde Mattermost guardará los archivos que suban los usuarios:
sudo tar -xzf "mattermost-${MM_VERSION}-linux-amd64.tar.gz" -C /opt
sudo mkdir /opt/mattermost/data
Crea un usuario de sistema sin shell para ejecutar el servicio y dale la propiedad del directorio:
sudo useradd --system --user-group mattermost
sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost
Comprueba la versión instalada:
sudo -u mattermost /opt/mattermost/bin/mattermost version
Version: X.Y.Z
...
Paso 3: Configurar la conexión a la base de datos
La configuración de Mattermost está en un archivo JSON. Ábrelo:
sudo nano /opt/mattermost/config/config.json
Dentro de ServiceSettings, cambia estas dos claves. SiteURL debe ser la URL pública exacta, y ListenAddress hace que Mattermost escuche solo en local, ya que el acceso externo pasará por Nginx:
"SiteURL": "https://chat.your_domain",
"ListenAddress": "127.0.0.1:8065",
Dentro de SqlSettings, ajusta el controlador y la cadena de conexión con la contraseña del paso 1:
"DriverName": "postgres",
"DataSource": "postgres://mmuser:[email protected]:5432/mattermost?sslmode=disable&connect_timeout=10",
Notasi la contraseña contiene caracteres especiales como
@,:o/, codifícalos en formato URL (por ejemplo@pasa a ser%40), o la cadena de conexión no será válida.
Protege el archivo, ya que contiene la contraseña de la base de datos:
sudo chmod 600 /opt/mattermost/config/config.json
sudo chown mattermost:mattermost /opt/mattermost/config/config.json
Paso 4: Crear el servicio de systemd
Crea una unidad de systemd para que Mattermost arranque con el sistema y se reinicie si falla:
sudo nano /etc/systemd/system/mattermost.service
[Unit]
Description=Mattermost
After=network.target postgresql.service
BindsTo=postgresql.service
[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
Type=notify hace que systemd espere a que Mattermost confirme que ha arrancado. En el primer inicio, Mattermost crea todas las tablas, por eso el tiempo de arranque permitido es tan amplio.
Recarga systemd, activa el servicio y arráncalo:
sudo systemctl daemon-reload
sudo systemctl enable --now mattermost
Comprueba el estado y el endpoint de salud de la API:
systemctl status mattermost --no-pager
curl -s http://127.0.0.1:8065/api/v4/system/ping
● mattermost.service - Mattermost
Active: active (running) since ...
{"ActiveSearchBackend":"database",...,"status":"OK"}
Si el servicio no arranca, revisa el registro con sudo journalctl -u mattermost -n 50: el error más habitual es una cadena DataSource incorrecta.
Paso 5: Configurar Nginx como proxy inverso
Instala Nginx y abre los puertos en el cortafuegos. Permite SSH antes de activar UFW para no perder la conexión:
sudo apt install nginx
sudo ufw allow OpenSSH
sudo ufw allow "Nginx Full"
sudo ufw enable
Crea el sitio de Mattermost:
sudo nano /etc/nginx/sites-available/mattermost
La aplicación mantiene una conexión WebSocket abierta para recibir mensajes en tiempo real, por eso la ruta del WebSocket necesita las cabeceras Upgrade y Connection y un tiempo de lectura más largo:
upstream mattermost_backend {
server 127.0.0.1:8065;
keepalive 32;
}
server {
listen 80;
listen [::]:80;
server_name chat.your_domain;
client_max_body_size 100M;
location ~ /api/v[0-9]+/(users/)?websocket$ {
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 600s;
proxy_pass http://mattermost_backend;
}
location / {
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 600s;
proxy_pass http://mattermost_backend;
}
}
client_max_body_size limita el tamaño de los archivos adjuntos; ajústalo al valor de Tamaño máximo de archivo que configures en Mattermost.
Activa el sitio, desactiva el sitio por defecto y recarga Nginx:
sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
Paso 6: Activar HTTPS con Let's Encrypt
Instala Certbot con el plugin de Nginx y solicita el certificado. Certbot añade la configuración TLS al sitio y la redirección de HTTP a HTTPS:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d chat.your_domain
Comprueba que la renovación automática funcionará:
sudo certbot renew --dry-run
Congratulations, all simulated renewals succeeded:
/etc/letsencrypt/live/chat.your_domain/fullchain.pem (success)
Y que el sitio responde por HTTPS:
curl -s https://chat.your_domain/api/v4/system/ping
{"ActiveSearchBackend":"database",...,"status":"OK"}
Paso 7: Crear el administrador y el primer equipo
Abre https://chat.your_domain en el navegador. La primera cuenta que se registra se convierte en administrador del sistema, así que hazlo en cuanto termines la instalación:
- Crea tu cuenta con correo, nombre de usuario y contraseña.
- Indica el nombre de tu organización y crea el primer equipo.
- Sáltate o completa el resto del asistente inicial.
A continuación, entra en Consola del sistema (menú de productos, arriba a la izquierda) y revisa estos ajustes:
- Autenticación > Registro: desactiva la creación abierta de cuentas si solo quieres que entren usuarios invitados.
- Entorno > SMTP: configura un servidor de correo para que funcionen las invitaciones, el restablecimiento de contraseñas y las notificaciones por email.
- Entorno > Almacenamiento de archivos: el valor por defecto guarda los adjuntos en
/opt/mattermost/data. Puedes cambiarlo a un almacenamiento compatible con S3.
Los cambios de la consola se guardan en config.json, por eso el usuario mattermost necesita permiso de escritura sobre él.
Para verificar que el tiempo real funciona, abre Mattermost en dos navegadores con dos usuarios distintos y envía un mensaje directo: debe aparecer al instante sin recargar la página. Si solo aparece al recargar, la ruta del WebSocket en Nginx no está bien configurada.
Paso 8: Hacer copias de seguridad
Una copia de Mattermost se compone de la base de datos, el directorio data (adjuntos) y el archivo config.json. Crea un script para generarla:
sudo nano /usr/local/bin/mattermost-backup
#!/usr/bin/env bash
set -euo pipefail
BACKUP_DIR="/var/backups/mattermost"
STAMP="$(date +%F_%H%M)"
mkdir -p "$BACKUP_DIR"
sudo -u postgres pg_dump -Fc mattermost > "$BACKUP_DIR/db_${STAMP}.dump"
tar -czf "$BACKUP_DIR/files_${STAMP}.tar.gz" -C /opt/mattermost data config/config.json
# Conserva solo las copias de los últimos 7 días
find "$BACKUP_DIR" -type f -mtime +7 -delete
Hazlo ejecutable y pruébalo:
sudo chmod 750 /usr/local/bin/mattermost-backup
sudo /usr/local/bin/mattermost-backup
sudo ls -lh /var/backups/mattermost
-rw-r--r-- 1 root root 2.1M ... db_2026-09-25_0300.dump
-rw-r--r-- 1 root root 15M ... files_2026-09-25_0300.tar.gz
Programa la copia cada noche a las 03:00 con el crontab de root:
sudo crontab -e
0 3 * * * /usr/local/bin/mattermost-backup
Para restaurar la base de datos en un servidor nuevo, detén Mattermost y usa sudo -u postgres pg_restore --clean -d mattermost db_FECHA.dump. Copia las copias fuera del servidor para que sirvan si este se pierde.
Paso 9: Actualizar Mattermost
Para actualizar, detén el servicio, haz una copia de seguridad y sustituye los binarios conservando config, data, logs y los plugins. Descarga y extrae la nueva versión en /tmp:
sudo systemctl stop mattermost
sudo /usr/local/bin/mattermost-backup
MM_VERSION=X.Y.Z
cd /tmp
wget "https://releases.mattermost.com/${MM_VERSION}/mattermost-${MM_VERSION}-linux-amd64.tar.gz"
tar -xzf "mattermost-${MM_VERSION}-linux-amd64.tar.gz" --transform='s,^[^/]\+,mattermost-upgrade,'
Borra de la instalación actual todo excepto los directorios con datos (incluidos los plugins del cliente), copia los archivos nuevos y restablece los permisos:
sudo find /opt/mattermost/ -mindepth 1 -maxdepth 1 \
! -name config ! -name data ! -name logs ! -name plugins ! -name client \
-exec rm -rf {} +
sudo find /opt/mattermost/client/ -mindepth 1 -maxdepth 1 ! -name plugins -exec rm -rf {} +
sudo cp -an /tmp/mattermost-upgrade/. /opt/mattermost/
sudo chown -R mattermost:mattermost /opt/mattermost
sudo systemctl start mattermost
cp -an no sobrescribe archivos existentes, así que tu config.json se conserva. Lee siempre las notas de versión antes de saltar varias versiones mayores: algunas requieren pasos adicionales.
Solución de problemas
- Error 502 Bad Gateway: Mattermost no está escuchando. Comprueba
systemctl status mattermostycurl http://127.0.0.1:8065/api/v4/system/ping. - "Please check connection, Mattermost unreachable" en el navegador: falla el WebSocket. Revisa el bloque
locationdel WebSocket en Nginx y queSiteURLcoincide exactamente con la URL que usas. - "pq: password authentication failed for user mmuser" en
journalctl -u mattermost: la contraseña deDataSourceno coincide con la de PostgreSQL o contiene caracteres sin codificar. - Los adjuntos grandes fallan con error 413: aumenta
client_max_body_sizeen Nginx y recarga el servicio.
Conclusión
Ya tienes Mattermost funcionando en Ubuntu 24.04 con PostgreSQL, Nginx y HTTPS, con copias de seguridad diarias. Como siguientes pasos, configura el SMTP para enviar invitaciones, conecta tus herramientas con webhooks entrantes desde Integraciones y valida el acceso desde las aplicaciones de escritorio y móvil de Mattermost.