Tutoriais de VPS
Mattermost na VPS (2026): Docker, PostgreSQL, Caddy HTTPS e backups
Instale Mattermost 11.7 ESR no Ubuntu 24.04 com Docker Compose oficial, PostgreSQL e Caddy. Configure SMTP, push móvel e Calls, e teste backups, restauração e atualização segura.

Um chat de equipe parece leve até entrar em produção. A parte difícil é fazer domínio, WebSocket, anexos, notificações no celular, chamadas e backups recuperáveis funcionarem juntos.
Este guia usa Ubuntu 24.04, Mattermost 11.7 ESR, o Docker Compose oficial, PostgreSQL e Caddy instalado no host. Inclui HTTPS, primeiro administrador, SMTP, notificações móveis, Calls, backup, restauração e atualização, com os limites de uma VPS pequena.
Contexto de versão: o texto de setembro de 2026 usa a linha 11.7 ESR. A imagem 11.7.9 do exemplo existe, mas isso não comprova que seja o patch de segurança mais recente hoje. Fixe um patch suportado e acompanhe avisos de segurança. Confira
env.examplee as notas do repositório Docker oficial antes da instalação, além da licença da edição.
Mattermost oferece canais, mensagens diretas, arquivos, busca, webhooks, bots, plugins e clientes de desktop e celular. Considere quando:
- Mensagens, anexos ou auditoria precisam de controle fora de um SaaS público.
- Desenvolvimento, operações ou suporte precisam de comunicação interna centralizada.
- GitLab, Jira, CI/CD, alertas e ChatOps devem integrar os mesmos canais.
- Há alguém para manter Linux, Docker, PostgreSQL, backups e atualizações.
- É possível começar com 10–50 pessoas e ampliar conforme a carga medida.
Para poucas pessoas conversando temporariamente sem responsável pela recuperação, um serviço gerenciado costuma ser mais simples. Hospedagem própria oferece controle e integração, mas exige VPS, domínio, e-mail, armazenamento de objetos, espaço de backup e tempo de manutenção.
| Serviço | Melhor uso | Vantagem | Responsabilidade ou limite |
|---|---|---|---|
| Mattermost | Colaboração interna e ChatOps de desenvolvimento/operações | Dados controlados, webhooks/plugins, rede privada | Servidores, banco, backup, push e atualização |
| Slack | Adoção rápida, colaboração externa e integrações SaaS | Menos manutenção de infraestrutura | Preços e políticas de dados do SaaS |
| Discord | Comunidades, salas de voz e público externo | Ferramentas de comunidade conhecidas | Adequação limitada a dados empresariais estritamente controlados |
Compare usuários ativos, anexos, conformidade, push, SSO e tamanho das chamadas. A semelhança visual com Slack não determina o custo de operação.
O original cita uma referência da aplicação de 1 vCPU/2 GB para até cerca de 1.000 usuários cadastrados. Cadastros não equivalem a usuários ativos simultâneos nem garantem a capacidade da VPS completa. Plugins, busca, arquivos e chamadas mudam a demanda; PostgreSQL, Docker e Caddy também precisam de recursos.
| Carga | Ponto de partida prático | Disco | Condições |
|---|---|---|---|
| Piloto de 10–30 pessoas | 2 vCPU / 4 GB RAM | 60 GB NVMe | Texto e poucos anexos |
| 30–100 usuários diários | 4 vCPU / 8 GB RAM | 100–200 GB NVMe | Mais plugins, webhooks e arquivos |
| Mais de 100 ou alta atividade | 4–8 vCPU / 16 GB+ RAM | Avaliar banco/objetos separados | Testar carga antes de separar serviços |
Estime anexos anuais como usuários ativos × volume mensal por pessoa × 12 × margem de segurança 1,5. A fórmula original é:
一年附件容量 ≈ 活跃用户数 × 每人每月附件量 × 12 × 1.5 安全系数
Com 50 pessoas enviando 100 MB por mês cada uma, os arquivos brutos somam cerca de 60 GB ao ano, antes da margem, banco, logs, índices e backups. Um disco de 100 GB pode acabar rapidamente. Para muitos anexos, considere S3 compatível; veja o guia de MinIO.
Navegador, desktop e celular acessam Caddy no host por HTTPS 443. Caddy encaminha a Mattermost em loopback 8065; a aplicação chega ao PostgreSQL pela rede Docker. A mídia de Calls chega diretamente por UDP/TCP 8443. O diagrama original é:
浏览器 / 桌面端 / 手机端
│ HTTPS 443
▼
Caddy(宿主机)
│ 127.0.0.1:8065
▼
Mattermost 容器
│ Docker 内网 5432
▼
PostgreSQL 容器
Calls 媒体:客户端 ── UDP/TCP 8443 ──> Mattermost
Abra apenas o necessário para os recursos habilitados:
22/tcp: SSH, de preferência limitado a endereços administrativos.80/tcpe443/tcp: certificados e acesso web.8443/udpe8443/tcp: quando Calls estiver ativo.8065/tcp: somente em127.0.0.1, sem acesso público.5432/tcp: apenas na rede Docker.
O proxy HTTP de Caddy não transporta a mídia de 8443. Avalie fallback TCP ou TURN para redes que bloqueiam UDP e RTCD para mais carga. Confira publicações Docker e firewall da nuvem: portas publicadas podem contornar expectativas baseadas apenas em regras UFW.
Use um subdomínio como chat.example.com, com A apontando ao IPv4 público. Publique AAAA apenas com IPv6 funcional; um registro sem conectividade provoca falhas intermitentes de certificado ou cliente.
export MM_DOMAIN="chat.example.com"
getent ahosts "$MM_DOMAIN"
curl -4 https://ifconfig.me
Atualize o sistema e configure o firewall preservando SSH antes de habilitá-lo:
sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl git openssl ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8443/tcp
sudo ufw allow 8443/udp
sudo ufw enable
sudo ufw status verbose
Deixe 8443 fechado se não usar Calls.
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
Veja a lista Compose para produção para healthchecks, rotação de logs e limites de recursos.
Não use mattermost-preview em produção: Preview possui senhas conhecidas, e-mail desativado, dados não persistentes e nenhum caminho normal de atualização.
sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/mattermost
cd /opt/mattermost
git clone https://github.com/mattermost/docker.git
cd docker
cp env.example .env
Confira checkout e configuração:
git status --short
git log -1 --oneline
grep -E '^(POSTGRES_IMAGE_TAG|MATTERMOST_IMAGE|MATTERMOST_IMAGE_TAG)=' env.example
Registre o commit testado. Atualizar o repositório pode alterar caminhos de volumes, variáveis e Compose mesmo com a imagem da aplicação fixada.
Gere uma senha forte:
openssl rand -base64 36
Edite /opt/mattermost/docker/.env, alterando pelo menos estes valores e preservando outras entradas necessárias do exemplo copiado:
DOMAIN=chat.example.com
TZ=Asia/Shanghai
RESTART_POLICY=unless-stopped
POSTGRES_IMAGE_TAG=18-alpine
POSTGRES_USER=mmuser
POSTGRES_PASSWORD=replace-with-a-long-random-password
POSTGRES_DB=mattermost
MATTERMOST_IMAGE=mattermost-team-edition
MATTERMOST_IMAGE_TAG=11.7.9
APP_PORT=8065
CALLS_PORT=8443
MM_SERVICESETTINGS_SITEURL=https://chat.example.com
O fuso horário é uma escolha de configuração: use o adequado à equipe. Team Edition permite iniciar a avaliação, sem prometer todos os recursos de produção. Confira os limites atuais de Entry, Professional e Enterprise para permissões, conformidade, push e Calls. Escolha um patch seguro suportado, sem copiar cegamente 11.7.9. Fixe PostgreSQL também: mudar a versão principal sobre dados existentes exige migração, não reinício. O Compose oficial atual monta os dados PostgreSQL 18 no diretório pai esperado; preserve o mapeamento do commit testado.
Proteja o arquivo:
chmod 600 .env
O usuário Mattermost oficial tem UID/GID 2000. Propriedade incorreta costuma provocar reinícios com permission denied:
cd /opt/mattermost/docker
mkdir -p ./volumes/app/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}
sudo chown -R 2000:2000 ./volumes/app/mattermost
PostgreSQL inicializa seu próprio diretório. Não misture arquivos da aplicação e dados do banco em um único ponto de montagem.
O arquivo oficial docker-compose.without-nginx.yml publica 8065 em todos os endereços do host. Use este override separado com o Compose base para restringir web ao loopback e manter a mídia Calls:
cd /opt/mattermost/docker
cat >docker-compose.caddy.yml <<'YAML'
services:
mattermost:
ports:
- "127.0.0.1:${APP_PORT}:8065"
- "${CALLS_PORT}:${CALLS_PORT}/udp"
- "${CALLS_PORT}:${CALLS_PORT}/tcp"
YAML
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml config >/tmp/mattermost-compose.yml
grep -A12 'ports:' /tmp/mattermost-compose.yml
Compose expandido contém a senha. Inspecione com umask privado, não compartilhe o arquivo e exclua-o depois de conferir HostIp de 8065 em 127.0.0.1. Não inclua também o override público: Compose pode combinar listas de portas.
Inicie após confirmar a configuração efetiva:
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml pull
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml ps
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml logs --tail=100 postgres mattermost
Confira a saúde local:
curl -fsS http://127.0.0.1:8065/api/v4/system/ping
ss -lntup | grep -E ':8065|:8443'
Ping deve retornar JSON com status: OK, e 8065 deve escutar apenas em 127.0.0.1. Exclua /tmp/mattermost-compose.yml após a inspeção.
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
sudo apt-get update
sudo apt-get install -y caddy
Crie /etc/caddy/Caddyfile:
chat.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:8065 {
header_up X-Real-IP {remote_host}
header_up X-Forwarded-Proto {scheme}
}
log {
output file /var/log/caddy/mattermost-access.log {
roll_size 100MiB
roll_keep 7
}
}
}
Antes de recarregar, permita a gravação do serviço no diretório de logs: sudo install -d -o caddy -g caddy -m 0750 /var/log/caddy. reverse_proxy do Caddy trata WebSocket por padrão, sem regras Upgrade manuais.
Valide e recarregue:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -I https://chat.example.com
curl -fsS https://chat.example.com/api/v4/system/ping
O guia completo Caddy explica HTTPS, logs e vários domínios.
Abra https://chat.example.com, crie a primeira conta/equipe e confirme seu papel de administrador do sistema. Depois:
- Defina nome do site, e-mail de suporte e política de cadastro.
- Desative cadastro público desnecessário; prefira convites ou domínios controlados.
- Configure SMTP e confira convites, redefinições e menções.
- Revise tamanhos e tipos de arquivos permitidos.
- Instale apenas plugins necessários e registre versões/permissões.
- Teste com usuário comum além do administrador.
Se o e-mail falhar, confira saída 587/465 e logs. Muitos provedores bloqueiam 25. Ausência de erro não comprova entrega: confira a caixa do destinatário.
Notificações web/desktop não comprovam push com tela bloqueada. Há três opções comuns:
- HPNS hospedado para planos comerciais elegíveis, conforme seus termos de produção.
- TPNS gratuito para testes, sem garantia de notificação de produção.
- Push Proxy próprio, exigindo apps móveis compilados de forma compatível e credenciais APNs/FCM.
Configure Push Notification Server no System Console. A conta A entra no celular e deixa o app em segundo plano; B envia mensagem direta pelo navegador. Confirme a chegada. Para dados sensíveis, avalie o conteúdo que passa pela infraestrutura push de terceiros.
Comece com Calls integrado para equipe pequena. Abra 8443 UDP/TCP no host e na nuvem, depois confira o plugin:
sudo ufw status numbered
sudo ss -lunp | grep ':8443'
sudo ss -ltnp | grep ':8443'
Use duas contas em redes diferentes, como banda larga residencial e celular. Testar somente na mesma LAN não revela problemas de endereço público, NAT e bloqueio UDP.
Para chamadas frequentes com mais de 50 pessoas, mídia confiável ou gravação, avalie RTCD, TURN e Calls Offloader oficiais. Gravação, transcrição e grupos maiores podem exigir licença comercial; confira direitos antes de comprar infraestrutura.
Um backup recuperável inclui:
- PostgreSQL.
volumes/app/mattermost/config.- Anexos locais em
volumes/app/mattermost/data. - Plugins e configuração de índices Bleve.
.enve arquivos Compose personalizados.- Configuração Caddy e credenciais externas necessárias.
Pare Mattermost mantendo PostgreSQL ativo para obter um ponto consistente. A sequência original é:
cd /opt/mattermost/docker
set -a
. ./.env
set +a
BACKUP_DIR="/var/backups/mattermost/$(date +%F-%H%M%S)"
sudo install -d -m 0700 "$BACKUP_DIR"
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml stop mattermost
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml exec -T postgres \
pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc >"$BACKUP_DIR/mattermost.pgdump"
sudo tar -C /opt/mattermost/docker -czf "$BACKUP_DIR/mattermost-files.tgz" \
.env docker-compose.caddy.yml volumes/app
sudo cp /etc/caddy/Caddyfile "$BACKUP_DIR/Caddyfile"
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml start mattermost
sudo sha256sum "$BACKUP_DIR"/* | sudo tee "$BACKUP_DIR/SHA256SUMS"
sudo du -sh "$BACKUP_DIR"
Não rode essa sequência sem mudanças como usuário comum: o shell redireciona antes que sudo dê acesso ao diretório 0700 de root. Ela também não trata falhas e pode deixar a aplicação parada. Use este script como root para o layout local documentado; ele evita executar dotenv como shell, impede backups sobrepostos e tenta reiniciar na falha:
#!/usr/bin/env bash
set -euo pipefail
test "$(id -u)" -eq 0
cd /opt/mattermost/docker
umask 077
exec 9>/run/lock/mattermost-backup.lock
flock -n 9
MM_BACKUP="/var/backups/mattermost/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$MM_BACKUP"
mm_compose() {
docker compose -f docker-compose.yml -f docker-compose.caddy.yml "$@"
}
trap 'mm_compose start mattermost >&2' EXIT
mm_compose stop mattermost
mm_compose exec -T postgres sh -eu -c \
'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
>"$MM_BACKUP/mattermost.pgdump"
tar -czf "$MM_BACKUP/mattermost-files.tgz" \
.env docker-compose.yml docker-compose.caddy.yml volumes/app
cp /etc/caddy/Caddyfile "$MM_BACKUP/Caddyfile"
git rev-parse HEAD >"$MM_BACKUP/deployment-commit.txt"
mm_compose config >"$MM_BACKUP/compose.rendered.yaml"
(
cd "$MM_BACKUP"
sha256sum mattermost.pgdump mattermost-files.tgz Caddyfile \
deployment-commit.txt compose.rendered.yaml >SHA256SUMS
sha256sum -c SHA256SUMS
)
mm_compose start mattermost
trap - EXIT
touch "$MM_BACKUP/COMPLETE"
chmod -R go-rwx "$MM_BACKUP"
printf 'Backup complete: %s\n' "$MM_BACKUP"
O trap solicita reinício; o monitoramento precisa confirmar a saúde. Aceite apenas backups com COMPLETE e checksums verificados. Armazenamento externo precisa de snapshot coordenado. /var/backups fica no disco da VPS: criptografe e copie para outro servidor ou objetos, com retenção. Veja o guia de backup automático.
Não espere uma falha para testar pg_restore. Em uma VPS isolada:
- Use versões Docker, Mattermost e PostgreSQL iguais ou compatíveis.
- Restaure
.env, Compose e diretórios da aplicação. - Inicie PostgreSQL com banco destino vazio.
- Importe usando
pg_restore --clean --if-exists, conferindo destino e credenciais. - Restaure propriedade
2000:2000. - Inicie Mattermost e confira canais, mensagens, anexos, plugins e busca.
- Use domínio de teste para login, envio/download, e-mail e Calls.
Mantenha a aplicação parada durante a restauração. Confira mensagens históricas e anexos originais; registre tempo e interrupção aceitável. Código de saída correto não basta.
Patches de segurança são frequentes. Leia cada etapa exigida entre versões; não salte várias versões principais para uma imagem latest.
cd /opt/mattermost/docker
git fetch --all --tags
git status --short
git diff env.example
Após verificar um backup completo, altere MATTERMOST_IMAGE_TAG em .env e execute:
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml pull mattermost
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml ps
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml logs --tail=200 mattermost
curl -fsS https://chat.example.com/api/v4/system/ping
Atualizações migram o banco. Voltar apenas a imagem pode falhar com schema alterado. Restaure banco, arquivos e configuração do mesmo ponto anterior e inicie a imagem original. Prepare manutenção, condições de parada e restauração testada em clone.
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml ps
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml logs --tail=200 postgres mattermost
sudo namei -l volumes/app/mattermost/config
sudo chown -R 2000:2000 volumes/app/mattermost
Confira credenciais do banco, propriedade dos volumes montados, disco cheio e caracteres especiais em .env.
Confira WebSocket do navegador, logs Caddy e Site URL:
sudo journalctl -u caddy -n 100 --no-pager
sudo tail -n 100 /var/log/caddy/mattermost-access.log
grep '^MM_SERVICESETTINGS_SITEURL=' /opt/mattermost/docker/.env
Causas comuns: Site URL HTTP, DNS antigo ou CDN/proxy adicional sem suporte adequado a WebSocket.
df -h
df -i
sudo du -sh /opt/mattermost/docker/volumes/app/mattermost/data
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml logs --tail=100 mattermost
Confira limites da aplicação/CDN e propriedade de diretórios. Aumentar só o limite do proxy não altera o de Mattermost.
Confira 8443 UDP/TCP, regras da nuvem, IP público de NAT e bloqueio UDP. Caddy trata sinalização HTTPS/WebSocket em 443, sem transportar mídia 8443.
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml exec -T postgres pg_isready -U mmuser -d mattermost
sudo docker compose -f docker-compose.yml -f docker-compose.caddy.yml logs --tail=100 postgres
Mantenha 5432 privado durante o diagnóstico. Veja o guia de conexões PostgreSQL.
- Domínio, certificados e
/api/v4/system/pingfuncionam. - 8065 fica em loopback e 5432 não é público.
- Usuários comuns entram, enviam mensagens e fazem upload/download.
- Web e desktop recebem mensagens em tempo real.
- Convites e redefinições SMTP chegam.
- Duas contas reais verificam push com tela bloqueada.
- Calls funciona entre duas redes diferentes.
- Banco, arquivos, configuração e chaves têm backups criptografados externos.
- Uma restauração isolada foi concluída.
- Versões fixadas e avisos de segurança acompanhados.
Não habilite todos os plugins, SSO, busca, gravação de chamadas e objetos no primeiro dia. Deixe 10–20 pessoas usarem por duas semanas. Meça CPU, RAM, disco, banco, crescimento de anexos e problemas de chamadas; depois decida o que ampliar ou separar.
Inclua mensagens em tempo real, push móvel, anexos recuperáveis e retorno testado na aceitação. Essas verificações sustentam um serviço de colaboração além da demonstração inicial Docker.