Como instalar a StackZap self-hosted com Docker

A edição self-hosted da StackZap é destinada a quem deseja operar a API em infraestrutura própria. A versão gratuita está disponível no Docker Hub; nesse modelo, você assume a preparação do servidor e a operação do serviço, banco de dados e conexões de rede.

1. 01Leia os requisitos do manual
2. 02Configure servidor e dependências
3. 03Instale a imagem indicada
4. 04Valide API, banco e backups

Antes de instalar

Confira os manuais atuais para os requisitos mínimos, variáveis de ambiente, banco de dados, portas, volumes persistentes, domínio e versão da imagem. Não reutilize um compose antigo sem confirmar se ele corresponde à versão que pretende executar.

Planeje HTTPS, controle de acesso à API Key, backups restauráveis, monitoramento e atualização da imagem antes de levar a instalação para produção. Mantenha os dados da instância em volumes persistentes conforme o procedimento oficial e teste uma recuperação em ambiente isolado.

Use os manuais oficiais

Os comandos e nomes de imagens podem mudar entre versões. Para evitar instruções desatualizadas, siga o manual em docs.stacklab.digital/manuais e confira endpoints em docs.stacklab.digital/stackzap. Faça uma primeira conexão e chamada usando um ambiente que você possa administrar e monitorar.

Se prefere não operar servidor, banco, firewall e backups, compare com o StackZap Cloud, onde a infraestrutura fica sob gestão da StackLab.

Faça inventário do ambiente

Antes de executar comandos, identifique o sistema operacional, arquitetura, versão do Docker, política de atualização e recursos disponíveis. Leia o manual da versão que será instalada. Registre nome da imagem, tag, variáveis obrigatórias, dependências, portas, volumes persistentes e processo de inicialização. Esses valores podem mudar, então não use um docker-compose.yml antigo encontrado num tutorial sem comparar com a documentação atual.

Decida onde o serviço será executado, quem terá acesso administrativo e como o host será monitorado. Um ambiente que funciona no computador local não está pronto para produção se usa armazenamento efêmero, porta pública sem controle ou uma chave compartilhada. Planeje domínio e HTTPS, regras de firewall e saída de rede antes de conectar uma conta real.

Checklist de responsabilidade antes da instalação

Persistência antes da primeira conexão

Identifique quais dados a instalação mantém e onde ficam volumes e banco. Dados dentro do filesystem efêmero do container podem desaparecer quando ele é removido ou recriado. Use o mecanismo de persistência definido pelo manual e confirme propriedade, permissões e capacidade do disco. Não mova volumes ou troque caminhos sem um plano de backup e recuperação.

Faça um backup inicial antes de upgrade e teste uma restauração em ambiente isolado. Confirme que a cópia inclui o que o manual considera necessário e que a aplicação consegue iniciar com os dados restaurados. Copiar diretório enquanto banco está gravando pode não produzir backup consistente; siga procedimento de snapshot ou dump recomendado para o banco.

Armazene configuração e credenciais fora do código

Mantenha API Key, senhas do banco e segredos de webhook em configuração protegida, não na imagem nem num arquivo versionado. Restrinja permissões no host e no pipeline que inicia os containers. Não mostre configuração completa em logs de deploy ou comandos compartilhados. Planeje rotação e atualização coordenada dos serviços dependentes.

Exponha somente as portas necessárias e use proxy/TLS conforme arquitetura documentada. A API deve ser acessível apenas pelos sistemas autorizados. Se painel e API compartilham host ou processo, use as regras atuais do manual em vez de presumir uma topologia padrão. A responsabilidade de DNS, certificado, firewall e rede pertence ao operador self-hosted.

Atualize de forma controlada

Antes de trocar tag ou imagem, leia notas e documentação de upgrade, confirme compatibilidade de banco e faça cópia restaurável. Em staging, valide startup, endpoints, login, criação de instância, conexão, envio controlado e webhooks. Registre a versão anterior e saiba como voltar se a migração não puder ser revertida automaticamente.

Evite usar uma tag mutável sem saber qual versão será baixada. Mantenha inventário da imagem e digest quando seu processo exigir reprodutibilidade. O comando exato depende da publicação atual; use o manual oficial para pull, recreação e migração. Nunca apague volumes como forma de limpar uma instalação sem compreender o efeito sobre dados.

Verifique saúde e logs

Implemente monitoração de processo, uso de CPU e memória, espaço em disco, conectividade do banco, latência, erros de API e estado da instância. Defina alertas para falha persistente, pouco espaço e backup atrasado. Faça logs acessíveis aos responsáveis, com rotação e retenção adequadas, e mascare API Keys, telefones e conteúdo de conversas.

Um container ativo não garante que a aplicação esteja pronta. Verifique endpoints de saúde documentados, dependências, migrations e estado do banco. Após reinicialização do host, confirme que os serviços voltaram na ordem correta e que os dados persistiram. Teste o processo em uma janela planejada antes de depender dele.

Conecte a conta de WhatsApp

Depois de confirmar que a API responde e que o painel está protegido, crie uma instância, inicie o fluxo de conexão e faça o pareamento pelo QR Code ou código apresentado. Use um número sob controle da equipe. Consulte o status e faça uma chamada pequena para um destino de teste autorizado. Não inicie automações amplas até validar autenticação, webhook e reconexão.

Guarde URL e ID da instalação na configuração da aplicação e use API Key protegida. Em self-hosted, não existe a URL automática de um ambiente Cloud: use o domínio ou endereço que o operador configurou. Documente a rota externa e interna para que suporte e integrações não confundam ambiente local com produção.

Prepare recuperação de falhas

Escreva um runbook para serviço parado, banco indisponível, disco cheio, certificado expirado, atualização com falha e sessão desconectada. Para cada evento, inclua responsável, verificações, comandos autorizados pela documentação e condição para escalar. Guarde cópias do runbook fora do host que pode falhar.

Backups precisam de periodicidade, local protegido, controle de acesso e teste de restauração. Uma cópia no mesmo disco não protege contra perda do host. Defina objetivos de recuperação compatíveis com sua operação, sem assumir que a existência de um arquivo representa recuperação garantida. Para ambiente Cloud, as responsabilidades de infraestrutura são gerenciadas pelo serviço; para self-hosted, cabem ao operador.

Checklist de produção

• Manual oficial da versão e imagem consultado.
• Persistência e banco configurados conforme a documentação.
• Backup consistente realizado e restauração testada.
• Secrets fora da imagem, do repositório e dos logs.
• Domínio, TLS, firewall e portas revisados.
• Atualização e rollback documentados.
• Logs rotacionados e monitoramento ativo.
• Inicialização após reboot verificada.
• Pareamento, status e chamada de teste validados.
• Runbook de falha e responsáveis definidos.

Organize os ambientes

Evite testar uma atualização diretamente na única instalação que atende produção. Se possível, crie ambiente de validação com dados sintéticos, versão controlada e número de teste. Mantenha configurações, volumes e secrets distintos para staging e produção. Um arquivo Compose compartilhado pode conter valores de referência, mas senhas e chaves reais devem vir de armazenamento protegido.

Documente diferenças entre ambiente local, teste e produção, incluindo domínio, portas, banco e limites de recursos. Ao alterar uma variável, registre qual serviço precisa reiniciar. Uma variável ausente pode fazer container iniciar parcialmente e falhar somente quando uma operação é executada; inclua checagens no processo de deploy.

DNS, TLS e acesso público

Defina qual endpoint será acessível pelas integrações e pelo painel. Configure DNS para o host certo, valide certificado e redirecionamentos HTTPS e restrinja tráfego administrativo. Se um webhook precisa alcançar sua instalação, exponha somente a rota necessária conforme o desenho suportado, com autenticação e validação de assinatura. Não abra portas de banco ou administração para toda a internet.

Revise regras de firewall de entrada e saída. A API pode precisar alcançar serviços externos e callbacks precisam receber conexões. Registre as regras e faça teste após mudanças de rede. Se usar proxy reverso, confirme encaminhamento de headers, timeouts e tamanho de corpo para que API e webhooks não sejam alterados ou cortados.

Capacidade e disco

Monitore espaço de volumes e banco, memória disponível e crescimento de logs. Configure rotação para que logs não preencham o disco. Planeje capacidade para dados persistentes, arquivos temporários e backups, mantendo folga para atualização. Se o armazenamento se aproxima do limite, investigue crescimento antes de remover dados manualmente.

Observe picos de CPU e memória durante criação de instância, envio de mídia e atualização. A quantidade de containers não basta para dimensionar: dependências e volume real determinam o consumo. Faça observação de um piloto e ajuste com margem, sem publicar limites inventados como requisito oficial.

Processo de backup e atualização

Defina frequência conforme a perda de dados aceitável para seu negócio, local de cópia separado do host, criptografia e pessoas autorizadas. Documente como validar e restaurar. Faça exercício em ambiente isolado, registre duração e revise instruções quando uma versão muda. Backups devem ter alerta de falha e retenção controlada.

Antes do deploy, capture versão atual, faça backup e leia notas de migração. Atualize um ambiente por vez, valide health checks e operações essenciais e só então avance. Se uma migration altera dados, entenda se o rollback é suportado; voltar a imagem antiga não necessariamente reverte o schema. Mantenha janela e responsáveis definidos.

Operação após reinício ou manutenção

Após reboot do host, confirme que containers iniciaram, dependências estão disponíveis, banco terminou recovery, API responde e dados persistiram. Consulte status da instância e faça um teste seguro. Monitore fila e webhooks atrasados. Um serviço pode estar “running” sem estar pronto, então use os checks e endpoints documentados.

Antes de uma janela de manutenção, pause integrações que não toleram indisponibilidade e comunique a equipe. Ao finalizar, retome gradualmente, verifique se os callbacks chegam e reconcilie jobs em estado desconhecido. Registre o início, fim, versão e resultado da intervenção.

Runbook mínimo

Para cada alerta, escreva o sintoma, comandos de diagnóstico aprovados, serviço responsável, risco de cada ação, condição de escalonamento e método de recuperação. Mantenha instruções acessíveis se o host estiver indisponível. Inclua contatos dos operadores, sem guardar senhas. Um runbook claro evita reinicializações destrutivas feitas sob pressão.

Revise a superfície exposta

Faça inventário de portas publicadas, rotas do proxy, serviços internos e acessos administrativos. Remova exposição que não seja necessária e limite acesso por rede ou autenticação. Verifique se a API Key não aparece em imagem, arquivo de configuração versionado, log de start ou interface pública. Uma instalação Docker não isola por si só as aplicações de um host mal configurado.

Mantenha Docker, sistema operacional e dependências atualizados segundo processo de mudança. Acompanhe avisos de segurança das versões usadas, teste a atualização em ambiente isolado e registre a imagem implantada. Evite aplicar correções diretamente no host de produção sem entender o efeito sobre volumes e containers.

Separe logs, métricas e dados de negócio

Logs operacionais ajudam a investigar, mas não devem virar uma cópia completa de conversas. Defina retenção, acesso e rotação. Armazene métricas de disponibilidade e uso separadas de conteúdo de mensagem. Se enviar logs a um serviço externo, revise redaction, localização, acesso e prazo antes de incluir payloads ou identificadores pessoais.

Documente quem recebe alertas e como confirmar se o problema é na API, banco, rede ou sessão de WhatsApp. Essa separação evita que uma reconexão seja tentada quando o verdadeiro problema é o container parado. Um painel de infraestrutura deve mostrar saúde de dependências e espaço do host, não apenas estado “running”.

Prepare a retirada da instalação

Se encerrar o serviço ou migrar para outro ambiente, identifique dados que precisam ser exportados, integrações que apontam ao domínio, callbacks, tarefas pendentes e política de retenção. Faça backup verificável, desative envios e desconecte a sessão conforme documentação. Depois remova secrets, tokens de deploy e regras de firewall que não serão mais usadas.

Não apague volumes para liberar espaço antes de confirmar que a migração e a retenção foram concluídas. Arquive a versão do runbook e a data da retirada. Esse encerramento evita uma instância esquecida, com credenciais ativas e domínio ainda acessível.

Faça uma revisão final de acesso e desative serviços auxiliares, DNS e monitoramentos que não são mais necessários.

Registre um inventário do host com versão do sistema, Docker, imagem StackZap, domínio, volumes e responsável. Atualize esse inventário após cada release. Em uma falha, ele ajuda a saber qual serviço e versão estão em execução sem vasculhar arquivos de configuração nem expor segredos. Mantenha o documento acessível a quem cobre a operação, com instruções que não incluam senhas ou API Keys.