Mailcow - Personalizado para ficar atrás do proxy NPM
publicado em 12/03/2026 às 19:11 atualizado em 19/08/2026 às 12:10
📘 Manual de Arquitetura e Implantação: Mailcow Dockerized
Empresa: MelloAIT
Setor: Infraestrutura de TI
Responsável: Henrique Fagundes
1. Visão Geral da Arquitetura
Esta documentação estabelece o padrão de implantação do Mailcow em servidores Linux, focado em três pilares de infraestrutura:
- Isolamento de Dados: Movimentação dos volumes do caminho padrão do Docker (
/var/lib/docker) para um diretório dedicado (/srv/mailcow-dockerized/data), evitando superlotação da partição raiz. - Proxy Reverso: Integração do Mailcow a uma rede Docker externa para operação segura atrás de proxies (Nginx Proxy Manager, Traefik, etc.), liberando as portas web físicas.
- Segurança de Updates: Preservação do repositório Git original do Mailcow para garantir que o script
./update.shfuncione sem conflitos ou perda de customizações.
2. Configuração de Volumes e Redes (Docker Override)
Regra de Ouro: O arquivo docker-compose.yml nativo do Mailcow nunca deve ser editado. Qualquer modificação direta causará falhas no Git durante as atualizações (ex: erro fatal: No current branch).
Toda a arquitetura customizada deve ser declarada no arquivo de substituição.
2.1. Criação do Arquivo Override
Na raiz da instalação do Mailcow, crie o arquivo de regras sobrepostas:
vim /srv/mailcow-dockerized/docker-compose.override.yml
2.2. Código Padrão de Infraestrutura
Cole a configuração abaixo. Ela é responsável por conectar o Nginx do Mailcow à rede do proxy, desvincular as portas web do host físico e mapear os volumes pesados usando a técnica de bind mount.
services:
nginx-mailcow:
networks:
- echelon
# Isso apaga APENAS as portas 80 e 443 do host físico.
# O Postfix e o Dovecot continuam blindados e intocáveis lendo do arquivo original!
ports: !reset []
networks:
echelon:
external: true
volumes:
vmail-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/vmail-vol-1
o: bind
vmail-index-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/vmail-index-vol-1
o: bind
mysql-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/mysql-vol-1
o: bind
mysql-socket-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/mysql-socket-vol-1
o: bind
redis-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/redis-vol-1
o: bind
rspamd-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/rspamd-vol-1
o: bind
clamd-db-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/clamd-db-vol-1
o: bind
postfix-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/postfix-vol-1
o: bind
crypt-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/crypt-vol-1
o: bind
sogo-web-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/sogo-web-vol-1
o: bind
sogo-userdata-backup-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/sogo-userdata-backup-vol-1
o: bind
postfix-tlspol-vol-1:
driver: local
driver_opts:
type: none
device: /srv/mailcow-dockerized/data/postfix-tlspol-vol-1
o: bind
Após salvar o arquivo, aplique as mudanças recriando os contêineres com docker compose up -d.
Observação importante:
Caso não seja uma migração e sim uma nova implantação, crie os diretórios:
mkdir -p /srv/mailcow-dockerized/data/{vmail-vol-1,vmail-index-vol-1,mysql-vol-1,mysql-socket-vol-1,redis-vol-1,rspamd-vol-1,clamd-db-vol-1,postfix-vol-1,crypt-vol-1,sogo-web-vol-1,sogo-userdata-backup-vol-1,postfix-tlspol-vol-1}
3. Configuração do Proxy Reverso Web
Como as portas 80 e 443 foram liberadas do host físico, o tráfego HTTPS do painel administrativo e do webmail deve ser roteado pelo proxy da infraestrutura.
- Variáveis do Mailcow: Mantenha o arquivo principal mailcow.conf com as portas web padrão habilitadas internamente:
HTTP_PORT=80HTTPS_PORT=443
- Apontamento no Proxy: Configure a rota do seu subdomínio (ex:
mailcow.melloait.com.br) para apontar para o hostname interno do contêiner do Mailcow (nginx-mailcow) utilizando a porta80.
4. Liberação de Relay Autenticado (Múltiplos Domínios)
Para permitir que instâncias externas, contêineres isolados ou sistemas de alerta disparem e-mails se passando por diversos domínios (sem cair em regras de anti-spoofing do Postfix), utilize uma conta curinga em vez de liberar redes inteiras no mynetworks.
Passos na Interface Web Administrativa:
Prevenção de Erros Locais (Virtual Mailbox Table):
Se o sistema autenticado com a conta relay for disparar uma mensagem em que o remetente (FROM) utilize um domínio que já esteja hospedado neste Mailcow (ex: [email protected]), o servidor rejeitará o envio caso este endereço específico não exista.
- Solução: Acesse a aba de Aliases no painel administrativo e crie um redirecionamento fantasma para este endereço, apontando para qualquer caixa válida. Isso valida a existência da conta no banco do Postfix e autoriza o disparo.
5. Resolução de Problemas (Troubleshooting)
Falha ao Executar o ./update.sh
Sintoma: Ao iniciar a atualização, o script aborta retornando a mensagem:
Merging local with remote code... fatal: No current branch. Oh no, what happened?
Causa: O diretório git local perdeu o rastreamento da versão oficial (estado detached HEAD), geralmente provocado por inspeções de versões antigas ou por edições manuais inadvertidas em arquivos do repositório core.
Solução: No terminal, dentro da pasta /srv/mailcow-dockerized, force o repositório a retornar para a ramificação principal antes de rodar o update novamente:
git checkout master
./update.sh
Implementação de Infraestrutura TLS/SSL Automatizada via DNS-01 (Cloudflare API) e SNI no Mailcow
Detalhamento das Modificações no mailcow.conf
O arquivo principal de parametrização do ambiente, mailcow.conf, localizado na raiz do diretório de implantação, recebeu as seguintes atualizações nas seções do contêiner acme-mailcow:
Diretiva / Variável | Valor Atribuído | Descrição Técnica e Impacto Operacional |
|---|---|---|
|
| Habilita formalmente o contêiner interno |
|
| Instrui o validador ACME a ignorar o desafio baseado em conexões HTTP na porta 80 e adotar o ecossistema DNS-01. Elimina a necessidade de manter regras de firewall ou redirecionamentos HTTP externos apontando para o host. |
|
| Especifica o plugin dinâmico do |
| E-mail administrativo de registro junto ao Let's Encrypt. Utilizado estritamente para notificações de segurança corporativa, alertas de expiração e avisos de integridade da conta ACME. | |
|
| Modifica fundamentalmente a arquitetura de armazenamento do SSL. Ativa o Server Name Indication, fazendo com que o Mailcow ordene os certificados em diretórios isolados por domínio, permitindo o uso concomitante de certificados emitidos automaticamente e certificados manuais. |
|
| Define curingas (wildcards) internos que expandem automaticamente as requisições de segurança. Para cada domínio inserido na console administrativa, o sistema gerará requisições incluindo estes prefixos, garantindo conformidade nos principais clientes de e-mail. |
Integração de Credenciais com a API da Cloudflare
Para permitir que o contêiner acme-mailcow realize inserções e deleções em tempo de execução na tabela de zonas DNS dos domínios, as credenciais da infraestrutura foram concentradas no arquivo de escopo restrito do módulo de DNS.
Caminho do arquivo no host: data/conf/acme/dns-01.conf
# Configuração de Autenticação da API Cloudflare - Desafio DNS-01
CF_Key="SUA_GLOBAL_API_KEY_AQUI"
CF_Email="[email protected]"
⚠️ Nota de Segurança: O uso da variável
CF_Keyatrela a validação à Global API Key da conta Cloudflare. Garanta que as permissões de leitura deste arquivo no host estejam restritas ao usuário root ou dono do processo Docker (chmod 600ou640), minimizando a exposição de privilégios globais da zona.
Mecanismo de Execução e Fluxo de Validação
Com a virada de chave para o modo SNI Ativado (ENABLE_SSL_SNI=y), o fluxo operacional do servidor segue os seguintes critérios automatizados:
- O loop do script
acme-mailcowvarre os metadados do banco de dados e compõe a árvore de domínios ativos. - Para cada zona sob gerência da chave Cloudflare configurada, uma requisição HTTPS é disparada à API, inserindo temporariamente um registro do tipo
TXTsob o nome_acme-challenge.dominio.com.brcontendo o token randômico gerado pelo Let's Encrypt. - O Let's Encrypt valida a existência do registro TXT via consulta DNS global externa.
- Após o sucesso (Success/OK), a Cloudflare remove o registro TXT de forma limpa e os certificados finais (arquivos
cert.pemekey.pem) são alocados em suas respectivas subpastas.
Estrutura de Armazenamento de Certificados no Host:
Os arquivos são espelhados dinamicamente no armazenamento local do servidor:
- Hostname Principal:
data/assets/ssl/cert.pemekey.pem - Zonas Adicionais (SNI):
data/assets/ssl/[nome-do-dominio]/cert.pemekey.pem
Nota: Caso um domínio específico não utilize a mesma conta Cloudflare, a arquitetura SNI permite que sua respectiva subpasta seja populada manualmente com certificados de terceiros, sem impactar a automação dos demais domínios.
Comandos Operacionais de Ciclo de Vida e Diagnóstico
Para aplicar a nova matriz de configuração ou forçar uma revalidação imediata da árvore de componentes, utilize a sequência de comandos abaixo a partir do diretório raiz do Mailcow:
Recriar contêineres com as novas variáveis de ambiente:
# Atualizar a pilha docker-compose com o novo mailcow.conf
docker compose up -d
# Forçar a inicialização imediata e leitura do módulo ACME
docker compose restart acme-mailcow
Monitoramento de logs em tempo real (Diagnóstico de Emissão):
# Acompanhar a comunicação com a API Cloudflare e retornos do Let's Encrypt
docker compose logs -f --tail=100 acme-mailcow
Se a validação ocorrer com sucesso, os serviços de borda e transporte do Mailcow (nginx-mailcow, postfix-mailcow e dovecot-mailcow) receberão um sinal interno de reload automático para carregar as chaves criptográficas sem derrubar as sessões active dos usuários.