~/conhecimento/mailcow-personalizado-para-ficar-atras-do-proxy-npm

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:

  1. 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.
  2. 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.
  3. Segurança de Updates: Preservação do repositório Git original do Mailcow para garantir que o script ./update.sh funcione 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.

  1. Variáveis do Mailcow: Mantenha o arquivo principal mailcow.conf com as portas web padrão habilitadas internamente:
  • HTTP_PORT=80
  • HTTPS_PORT=443
  1. 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 porta 80.

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:

  1. Navegue até Configuração de E-mail > Caixas de Correio.
  2. Crie uma conta dedicada à infraestrutura (ex: [email protected]).
  3. Edite as configurações desta caixa recém-criada.
  4. Localize a seção Permitir envio como (Allow to send as).
  5. Selecione e ative a flag: Desativar verificação de remetente para domínio * (+ domínios de alias).
  6. Salve as alterações.

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

SKIP_LETS_ENCRYPT

n

Habilita formalmente o contêiner interno acme-mailcow. Quando definido como n (no), o Mailcow assume a responsabilidade de gerenciar as requisições, emissões e renovações de certificados junto à autoridade certificadora Let's Encrypt.

ACME_DNS_CHALLENGE

y

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.

ACME_DNS_PROVIDER

dns_cf

Especifica o plugin dinâmico do acme.sh que será carregado. O valor dns_cf injeta as rotas de chamadas exclusivas para a API oficial da Cloudflare, permitindo a automação da criação de registros temporários.

ACME_ACCOUNT_EMAIL

[email protected]

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.

ENABLE_SSL_SNI

y

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.

ADDITIONAL_SAN

imap.*,smtp.*,pop.*,pop3.*,imap3.*

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_Key atrela 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 600 ou 640), 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:

  1. O loop do script acme-mailcow varre os metadados do banco de dados e compõe a árvore de domínios ativos.
  2. Para cada zona sob gerência da chave Cloudflare configurada, uma requisição HTTPS é disparada à API, inserindo temporariamente um registro do tipo TXT sob o nome _acme-challenge.dominio.com.br contendo o token randômico gerado pelo Let's Encrypt.
  3. O Let's Encrypt valida a existência do registro TXT via consulta DNS global externa.
  4. Após o sucesso (Success/OK), a Cloudflare remove o registro TXT de forma limpa e os certificados finais (arquivos cert.pem e key.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.pem e key.pem
  • Zonas Adicionais (SNI): data/assets/ssl/[nome-do-dominio]/cert.pem e key.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.

Precisa disso implementado na sua empresa?

Eu faço o trabalho para você, com segurança e documentação.

>_ SOLICITAR ORÇAMENTO