> For the complete documentation index, see [llms.txt](https://ajuda.zdg.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.zdg.com.br/avancado-recursos-tecnicos/infraestrutura/guia-para-instalacao-com-docker.md).

# Guia para Instalação com Docker (Autoinstalador e Stacks)

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.

{% hint style="info" %}
**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).
  {% endhint %}

***

### 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).

{% hint style="warning" %}
**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.
{% endhint %}

{% embed url="<https://youtu.be/O2bJzhgAdAU?t=169>" %}

***

### Etapa 1: Instalar via Autoinstalador

1. Baixe o autoinstalador na versão mais recente (hotfix) e extraia a pasta.
2. Acesse a pasta extraída e torne o arquivo executável.
3. Execute o autoinstalador (`./zpro`).
4. 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)

1. O autoinstalador verifica se o Docker Desktop e o Docker Compose estão disponíveis.
2. Ele informa **duas portas livres** que serão usadas — uma para o backend e uma para o frontend.
3. 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.
4. Informe ao autoinstalador os subdomínios gerados para backend e frontend.

**No Ubuntu**

1. O autoinstalador não pergunta portas — ele pede diretamente os **subdomínios** de backend e frontend.
2. 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.

{% hint style="danger" %}
**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.
{% endhint %}

***

### 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 `latest` no Docker Hub**. Para atualizar com as imagens mais recentes do Hub, é necessário editar manualmente os arquivos do `docker-compose`, o que exige mais familiaridade com Docker.
* **Opção "Limpar pastas legacy":** toda atualização cria uma pasta `legacy` como 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.

{% hint style="danger" %}
**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.
{% endhint %}

***

### 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`](https://docker-hub.zip/) você encontra:

| Arquivo                                 | Uso                                                              |
| --------------------------------------- | ---------------------------------------------------------------- |
| `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).

{% hint style="info" %}
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**.
{% endhint %}

1. Extraia o [`docker-hub.zip`](https://docker-hub.zip/) (vem junto com o autoinstalador) e localize o arquivo de stack correspondente ao seu ambiente: `portainer-stack.windows-localhost.yml` ou `portainer-stack.ubuntu-traefik.yml`.
2. No Portainer, acesse **Stacks > Add stack**.
3. Dê um nome para a stack.
4. Cole o conteúdo do arquivo de stack escolhido.
5. Preencha as variáveis obrigatórias no topo do arquivo (ex.: senha do PostgreSQL, secret do JWT).
6. Desmarque a opção **Enable access control**.
7. 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).

{% hint style="warning" %}
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.
{% endhint %}

***

### Resumo das Funcionalidades

| Funcionalidade                            | Onde acessar                                                       |
| ----------------------------------------- | ------------------------------------------------------------------ |
| 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.

{% hint style="info" %}
*Prefere montar o `docker-compose.yml` manualmente? Veja o* *Guia para* [*Instalação com Docker.*](/avancado-recursos-tecnicos/infraestrutura/guia-para-instalacao-com-docker/instalacao-com-docker-manual.md)
{% endhint %}

***

### 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ajuda.zdg.com.br/avancado-recursos-tecnicos/infraestrutura/guia-para-instalacao-com-docker.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.