Guia para Instalação com Docker (Autoinstalador e Stacks)
Este guia explica como instalar o Z-PRO com Docker usando o autoinstalador (Windows e Ubuntu) ou stacks prontas via Portainer
O Z-PRO pode ser instalado em ambiente Docker de duas formas: pelo autoinstalador (opção de instalação Docker) ou por stacks prontas para quem já usa Portainer. As imagens oficiais de backend e frontend ficam publicadas no Docker Hub e são atualizadas a cada nova versão. Este artigo mostra os dois caminhos, as diferenças entre Windows e Ubuntu, e como atualizar ou limpar espaço em disco depois.
Pré-requisitos:
Windows: Docker Desktop instalado e em execução.
Ubuntu: Docker e Docker Compose instalados.
Autoinstalador do Z-PRO baixado (versão mais recente/hotfix) e extraído.
Terminal com Bash disponível (Git Bash no Windows; nativo no Ubuntu/Mac).
Domínio com subdomínios de backend e frontend apontando para o servidor (para uso em produção com SSL).
Como funciona
A instalação Docker roda o backend, o frontend e o PostgreSQL isolados em containers, usando as imagens oficiais publicadas no Docker Hub pela ZDG. Isso facilita replicar o ambiente e aplicar estratégias de contingência, mas é um caminho diferente da instalação tradicional via PM2 — não existe migração automática entre os dois modelos (veja Perguntas Frequentes).
Licenças: o modo localhost (sem subdomínio) só está disponível para licenças Unlimited. Licenças limitadas a um domínio precisam configurar subdomínios de backend e frontend normalmente.
Etapa 1: Instalar via Autoinstalador
Baixe o autoinstalador na versão mais recente (hotfix) e extraia a pasta.
Acesse a pasta extraída e torne o arquivo executável.
Execute o autoinstalador (
./zpro).No menu de opções, selecione a instalação Docker (Beta).
O comportamento a partir daqui muda conforme o sistema operacional:
No Windows (com Docker Desktop)
O autoinstalador verifica se o Docker Desktop e o Docker Compose estão disponíveis.
Ele informa duas portas livres que serão usadas — uma para o backend e uma para o frontend.
Você precisa expor essas portas manualmente com um proxy reverso para ter subdomínios com SSL. Uma forma prática de fazer isso em ambiente de testes é usar a aba Ports do VS Code ou do Cursor: conecte a extensão à sua conta, encontre a porta informada, clique com o botão direito e escolha Public, depois copie o subdomínio gerado.
Informe ao autoinstalador os subdomínios gerados para backend e frontend.
No Ubuntu
O autoinstalador não pergunta portas — ele pede diretamente os subdomínios de backend e frontend.
O proxy reverso e o certificado SSL são configurados automaticamente por ferramentas nativas do Ubuntu.
Em ambos os casos, o autoinstalador faz o build das imagens e sobe os containers (backend, frontend, PostgreSQL). A primeira instalação pode demorar alguns minutos, já que as imagens precisam ser construídas.
Importante: se você reinstalar usando as mesmas portas/subdomínios de uma instalação anterior sem apagar os dados do container do PostgreSQL, o autoinstalador pode acusar erro de senha/autenticação no banco, pois ele reaproveita os dados já existentes.
Etapa 2: Atualizar a instalação Docker
No menu do autoinstalador:
Opção "Atualizar Docker": usa o pacote de arquivos que vem dentro do próprio ZIP do autoinstalador — não busca automaticamente a imagem
latestno Docker Hub. Para atualizar com as imagens mais recentes do Hub, é necessário editar manualmente os arquivos dodocker-compose, o que exige mais familiaridade com Docker.Opção "Limpar pastas legacy": toda atualização cria uma pasta
legacycomo fallback de segurança — se a atualização falhar, o autoinstalador consegue voltar para essa versão anterior. Depois de confirmar que uma atualização deu certo, essas pastas acumulam espaço em disco; use esta opção para liberá-lo.
Antes de atualizar em produção, faça um backup completo do banco de dados e dos arquivos da aplicação (pasta public do backend). Recomendação oficial da ZDG sempre que uma nova versão latest é publicada.
Etapa 3: Alternativa — instalar via Stack no Portainer
O pacote do autoinstalador inclui o arquivo docker-hub.zip, com exemplos e stacks prontos usando as imagens oficiais do Docker Hub — para Portainer, Docker Swarm e Traefik. O objetivo é facilitar atualizações e novas implantações sem depender do fluxo guiado do autoinstalador.
Dentro do docker-hub.zip você encontra:
docker-compose.test.yml
Subir localmente via docker compose, sem Portainer
portainer-stack.test.yml
Stack de teste genérica para o Portainer
portainer-stack.windows-localhost.yml
Stack para Windows/Docker Desktop, expõe o Z-PRO em localhost
portainer-stack.ubuntu-traefik.yml
Stack para Ubuntu, já integrada ao Traefik (proxy reverso + SSL)
Este artigo cobre o fluxo pelo Portainer, demonstrado na live. Para quem já usa Portainer (via Docker Desktop no Windows ou via Ubuntu com Traefik), essas stacks sobem o Z-PRO sem precisar de uma VPS limpa — funcionam em conjunto com outros serviços que já estejam rodando no mesmo ambiente (ex.: N8N, Typebot).
O Portainer já vem instalado por padrão quando você usa o autoinstalador. Para instalá-lo manualmente no Docker Desktop: Extensions > Manage > buscar "Portainer" > instalar Portainer Community Edition Server.
Extraia o
docker-hub.zip(vem junto com o autoinstalador) e localize o arquivo de stack correspondente ao seu ambiente:portainer-stack.windows-localhost.ymlouportainer-stack.ubuntu-traefik.yml.No Portainer, acesse Stacks > Add stack.
Dê um nome para a stack.
Cole o conteúdo do arquivo de stack escolhido.
Preencha as variáveis obrigatórias no topo do arquivo (ex.: senha do PostgreSQL, secret do JWT).
Desmarque a opção Enable access control.
Clique em Deploy the stack.
Depois do deploy, acesse o frontend pela porta/subdomínio configurado na stack (no modelo Windows, isso costuma ser localhost na porta do frontend).
Este artigo não cobre o passo a passo de Docker Swarm — o docker-hub.zip já traz exemplo pronto para esse modelo, mas o fluxo de deploy não foi demonstrado na live que originou este guia.
Resumo das Funcionalidades
Instalar via autoinstalador (Docker Beta)
Menu do autoinstalador > opção de instalação Docker
Atualizar instalação Docker
Menu do autoinstalador > opção "Atualizar Docker"
Limpar pastas legacy
Menu do autoinstalador > opção "Limpar pastas legacy"
Instalar via Stack
Portainer > Stacks > Add stack, usando arquivo de docker-hub.zip
Encerramento
Com a instalação Docker ativa, você tem o Z-PRO rodando em containers isolados, seja pelo caminho guiado do autoinstalador, seja por uma stack no Portainer integrada ao seu ambiente já existente. O arquivo docker-hub.zip, incluído no pacote do autoinstalador, é atualizado a cada nova versão latest publicada no Docker Hub — vale conferir o aviso de atualização da comunidade sempre que uma nova versão sair.
Perguntas Frequentes
A instalação Docker pode substituir com confiança a instalação direta na VPS? Sim — as imagens públicas no Docker Hub já estão em uso e recebem as mesmas atualizações de versão que a instalação tradicional.
Dá para migrar automaticamente uma instalação PM2 existente para Docker? Não existe essa rotina no autoinstalador. A migração precisa ser feita manualmente: exportar o dump do banco de dados e a pasta public do backend, e importar esses dados na nova instalação Docker. Ferramentas de agente de IA com acesso ao terminal (ex.: Claude Code) podem ajudar a executar esse processo manual.
Existe rotina de backup para a instalação Docker? Não pelo autoinstalador. O backup precisa ser feito manualmente, cobrindo dois pontos: o dump do banco de dados e a pasta public do backend (onde ficam os arquivos enviados/recebidos). Recomenda-se contratar uma VPS com backup automático recorrente.
Como migro um tenant específico entre instalações/servidores? Use a opção de migração do Super Admin, que já cobre esse cenário — veja o artigo Migração de Tenants. Isso é diferente de migrar toda a instalação de um servidor para outro — nesse caso, veja Migração Z-PRO entre servidores.
Prefere montar o docker-compose.yml manualmente? Veja o Guia para Instalação com Docker.
Possíveis Erros e Soluções
Erro de senha/autenticação ao subir o PostgreSQL
Causa: já existia uma instalação anterior usando a mesma porta, e os dados do volume do banco não foram apagados — o container reaproveita a configuração antiga. Solução: remova o volume de dados do PostgreSQL antes de reinstalar, ou use uma porta diferente.
No Windows, o subdomínio não abre / SSL não funciha
Causa: as portas informadas pelo autoinstalador não foram expostas via proxy reverso. Solução: confirme se o proxy (ex.: extensão Ports do VS Code/Cursor, ou outra ferramenta de proxy reverso) está ativo e apontando para as portas corretas de backend e frontend.
Atualização não trouxe a versão mais recente do Docker Hub
Causa: a opção "Atualizar Docker" do autoinstalador usa os arquivos do próprio ZIP, não busca a imagem latest automaticamente. Solução: edite manualmente os arquivos do docker-compose para apontar para a tag de imagem desejada, ou baixe uma versão mais recente do autoinstalador.
Pouco espaço em disco depois de várias atualizações
Causa: pastas legacy acumuladas de atualizações anteriores. Solução: use a opção "Limpar pastas legacy" do autoinstalador — só faça isso depois de confirmar que a atualização mais recente está funcionando corretamente.
Atualizado
Isto foi útil?