# Instale o FZAP no seu servidor

> Escolha o método que combina com a sua infraestrutura. A mesma imagem Docker atende o plano Free e todas as licenças pagas.

https://flouds.com.br/produtos/fzap/instalacao

## Manual: Instalação manual pelo Portainer

Use este caminho se Docker Swarm, Portainer, PostgreSQL, rede e proxy já estão preparados. Você revisa a stack e cada variável antes do deploy.

**Antes de começar** (15–25 min)

- Docker Swarm ativo
- Portainer acessível
- PostgreSQL disponível
- Traefik e domínio configurados

1. **Crie os volumes**  
   Crie os volumes externos usados pelos dados locais e pelos arquivos do FZAP.

   ```bash
   docker volume create fzap_dbdata
   docker volume create fzap_files
   ```

2. **Cole a stack no Portainer**  
   No Portainer, abra **Stacks → Add stack**, dê o nome `fzap` e cole a stack oficial abaixo.

   ```yaml
   version: "3.7"

   services:
     fzap:
       image: dncarbonell/fzap:latest

       networks:
         - FloudsNet

       volumes:
         - fzap_dbdata:/app/dbdata
         - fzap_files:/app/files
         - fzap_data:/app/data

       environment:
         # --- Configurações Gerais e Sistema ---
         - TZ=America/Sao_Paulo
         - FZAP_LANGUAGE=pt-BR                               # pt-BR, en-US, es-LATAM
         - PUBLIC_BASE_URL=https://exemplo.com               # URL completa onde a fzap está instalada - Se instalado em subdomínio colocar o subdomínio completo, sempre com "https://". Ex: https://api.exemplo.com
         #- GLOBAL_PROXY_URL=                                # Proxy global opcional para todas as instâncias; o proxy de cada instância tem prioridade e o substitui

         # --- Armazenamento S3 Global (Backblaze B2 - Opcional) ---
         # Instâncias sem S3 próprio usam este bucket; a configuração individual tem prioridade.
         # Os arquivos são separados por instância no caminho users/<id>/...
         # O S3 global é ativado automaticamente ao preencher bucket, access key e secret key.
         #- GLOBAL_S3_BUCKET=seu-bucket
         #- GLOBAL_S3_ACCESS_KEY=seu-application-key-id
         #- GLOBAL_S3_SECRET_KEY=sua-application-key
         #- GLOBAL_S3_ENDPOINT=https://s3.us-west-004.backblazeb2.com
         #- GLOBAL_S3_REGION=us-west-004
         #- GLOBAL_S3_PATH_STYLE=false
         #- GLOBAL_S3_PUBLIC_URL=                             # URL pública ou CDN opcional
         #- GLOBAL_S3_MEDIA_DELIVERY=both                    # base64, s3 ou both
         #- GLOBAL_S3_RETENTION_DAYS=0                       # 0 mantém os arquivos indefinidamente

         #- LOG_LEVEL=info                                   # trace, debug, info, warn, error, fatal, panic
         #- CHATWOOT_SYSTEM_IDENTIFIER=flouds.com.br         # Uso interno no Chatwoot - é o identificador do contato de onboarding - Antes era FZAP_SYSTEM_IDENTIFIER
         #- CHATWOOT_SYSTEM_NAME=FZAP                        # Nome exibido no contato de onboarding - Antes era FZAP_SYSTEM_NAME
         #- CHATWOOT_PLATFORM_NAME=Chatwoot                  # Nome da plataforma white label do Chatwoot - Antes era PLATFORM_NAME
         #- CHATWOOT_SERVICE_URL=https://app.chatwoot.com    # Url de exemplo de conexão e integração do Chawtoot - Antes era DEFAULT_SERVICE_URL

         # --- Autenticação e Licença ---
         - ADMIN_TOKEN=admin_token_exemplo                   # Token de autenticação da API. Escolha um valor seguro
         - FLOUDS_LICENCE_KEY=                               # Deixe vazio para usar a versão free - Em caso de assinatura, a key estará no seu dashboard
         - FLOUDS_LIFETIME_LICENCE_KEY=                      # Caso tenha versão vitalícia (licença fixa por domínio - legado)

         # --- Banco de Dados (PostgreSQL) ---
         - DB_DRIVER=postgres
         - DB_HOST=postgres
         - DB_PORT=5432
         - DB_NAME=fzap
         - DB_USER=postgres
         - DB_PASSWORD=senha_exemplo

         # --- Banco de Dados do Chatwoot (Global - Opcional) ---
         #- CHATWOOT_GLOBAL_DB_HOST=                         # Host global opcional do PostgreSQL do Chatwoot; os campos de cada instância têm prioridade e o substituem
         #- CHATWOOT_GLOBAL_DB_PORT=5432                     # Porta global opcional do PostgreSQL do Chatwoot
         #- CHATWOOT_GLOBAL_DB_NAME=                         # Nome global opcional do banco de dados do Chatwoot
         #- CHATWOOT_GLOBAL_DB_USER=                         # Usuário global opcional do banco de dados do Chatwoot
         #- CHATWOOT_GLOBAL_DB_PASS=                         # Senha global opcional do banco de dados do Chatwoot

         # --- WhatsApp e Webhooks ---
         - SESSION_DEVICE_NAME=Fzap                          # Nome da dispositivo conectado (aparece no celular)
         - WEBHOOK_FORMAT=json
         #- IMAGE_QUALITY_HD=false                           # true para HD, false para padrão

         # --- Transcrição de Áudio (IA) ---
         #- TRANSCRIPTION_ENABLED=false                       # Habilita a transcrição global de áudio (true/false, padrão: false)
         #- TRANSCRIPTION_PROVIDER=openai                     # Provedor de transcrição: openai (padrão) ou groq
         #- TRANSCRIPTION_API_KEY=                            # Chave de API do provedor de transcrição selecionado
         #- TRANSCRIPTION_MODEL=                              # Substituição de modelo (padrão: whisper-1 para openai, whisper-large-v3 para groq)
         #- TRANSCRIPTION_BASE_URL=                           # Substituição opcional de endpoint (URL) para o provedor selecionado

         # --- WhatsApp Cloud API (Meta Embedded Signup) ---
         # Configurações para habilitar o fluxo guiado de cadastro direto pela Meta Cloud API.
         # ATENÇÃO: Recurso exclusivo para planos pagos (requer licença válida, não funciona na versão free).
         #- META_APP_ID=                                     # Meta App ID (obtido em developers.facebook.com)
         #- META_APP_SECRET=                                 # Meta App Secret (chave secreta do aplicativo)
         #- META_CONFIG_ID=                                  # Meta Business Login Config ID (ID de configuração do login)

         # --- Mensageria (RabbitMQ) ---
         #- RABBITMQ_ENABLED=true
         #- RABBITMQ_URL=amqp://fzap:fzap@rabbitmq:5672/
         #- RABBITMQ_EXCHANGE=fzap_events
         #- RABBITMQ_PREFIX=fzap
         #- RABBITMQ_FRAME_MAX=131072                        # Tamanho máx de frame (128KB)
         #- RABBITMQ_HEARTBEAT=30                            # Em segundos
         #- RABBITMQ_MAX_RECONNECT=10
         #- RABBITMQ_RECONNECT_DELAY=5                       # Em segundos

         # --- Monitoramento de Erros (Sentry) - Opcional ---
         # O Sentry é uma ferramenta de rastreamento que captura *somente erros* e falhas da aplicação em tempo real.
         # Isso permite que o desenvolvedor identifique e corrija os problemas de forma ativa, sem precisar esperar uma reclamação ou feedback do usuário.
         # A URL (DSN) de integração deve ser obtida com a equipe no grupo de suporte oficial. Deixe vazio caso não queira utilizar.
         #- SENTRY_DSN=
         
       deploy:
         mode: replicated
         replicas: 1
         placement:
           constraints:
             - node.role == manager
         labels:
           # Configuração Traefik
           - traefik.enable=true
           - traefik.http.routers.fzap.rule=Host(`exemplo.com`)
           - traefik.http.routers.fzap.entrypoints=websecure
           - traefik.http.routers.fzap.tls=true
           - traefik.http.routers.fzap.tls.certresolver=letsencryptresolver
           - traefik.http.routers.fzap.service=fzap
           - traefik.http.services.fzap.loadbalancer.server.port=8080

   volumes:
     fzap_dbdata:
       name: fzap_dbdata
       external: true
     fzap_files:
       name: fzap_files
       external: true
     fzap_data:
       name: fzap_data
       external: true

   networks:
     FloudsNet:
       name: FloudsNet
       external: true
   ```

   [Abrir stack oficial no GitHub](https://github.com/flouds-dncarbonell/projeto-fzap/blob/main/stack.yml)

3. **Defina o token e revise as variáveis**  
   Troque `ADMIN_TOKEN` por um valor seu e revise o banco, o domínio, `FZAP_LANGUAGE` e o timezone. Se tiver licença, preencha `FLOUDS_LICENCE_KEY`.

   > **Atenção:** Não deixe `ADMIN_TOKEN` vazio: sem ele, o FZAP gera um token novo a cada reinício e o acesso ao dashboard muda junto.

4. **Faça o deploy**  
   Clique em **Deploy the stack** e acompanhe o serviço `fzap` até ficar ativo.

5. **Entre no dashboard**  
   Abra o domínio configurado, entre com o `ADMIN_TOKEN` e teste a API.

   > **Observação:** Abra sempre pelo domínio, não pelo IP. É esse endereço que a licença valida.

## Instalador: Prepare e instale com um comando

Ideal para uma VPS nova. O instalador detecta o sistema, prepara a infraestrutura e conduz a instalação do FZAP pelo terminal.

**Antes de começar** (10–20 min)

- Acesso root à VPS
- 2 vCPU e 2 GB de RAM
- Portas 80 e 443 liberadas
- Dois domínios apontados para a VPS

**O instalador prepara a infraestrutura**. Você não precisa instalar ou configurar estes componentes manualmente.

- Docker e Docker Swarm
- Traefik com HTTPS
- Portainer
- PostgreSQL 17 com pgvector
- Rede Docker compartilhada
- Volumes e serviço FZAP

[A instalação pelo terminal em vídeo](https://www.youtube.com/watch?v=ANKm_9I-Rno)

1. **Conecte-se à VPS**  
   Entre por SSH com um usuário que possa executar `sudo`.

2. **Rode o instalador**  
   Execute o comando abaixo e aguarde a preparação do ambiente.

   ```bash
   curl -fsSL https://raw.githubusercontent.com/flouds-dncarbonell/installer-flouds/main/Setup | sudo bash
   ```

3. **Escolha instalar o FZAP**  
   No menu, escolha **Instalar FZAP neste servidor**.

4. **Informe domínios e licença**  
   Informe os domínios pedidos e, se tiver, a chave de licença. Deixe a chave vazia para usar o Free.

5. **Confirme e aguarde**  
   Confirme os dados e aguarde o instalador verificar se todos os serviços ficaram online.

## Coolify: Instale como um recurso do Coolify

O Coolify cuida do proxy, HTTPS, rede, volumes e credenciais. Você só precisa criar o recurso, colar o Compose oficial e configurar o domínio.

**Antes de começar** (8–15 min)

- Coolify funcionando
- Domínio apontado para o servidor
- Projeto criado no Coolify

1. **Crie o recurso**  
   No projeto desejado, clique em **New Resource** e escolha **Docker Compose Empty**.

2. **Cole o Compose oficial**  
   Copie todo o `docker-compose.yml` abaixo e cole no editor do recurso.

   ```yaml
   # documentation: https://github.com/flouds-dncarbonell/installer-flouds
   # slogan: Plataforma de automacao WhatsApp da Flouds
   # category: communication
   # tags: whatsapp,automation,chatwoot
   # port: 8080

   services:
     fzap:
       image: dncarbonell/fzap:latest
       pull_policy: always
       environment:
         # --- URL, sistema e interface ---
         - SERVICE_URL_FZAP_8080
         - PUBLIC_BASE_URL=${SERVICE_URL_FZAP}
         - TZ=${TZ:-America/Sao_Paulo}
         - FZAP_LANGUAGE=${FZAP_LANGUAGE:-pt-BR}
         - LOG_LEVEL=${LOG_LEVEL:-info}
         - LOG_CALLER=${LOG_CALLER:-false}
         - GLOBAL_PROXY_URL=${GLOBAL_PROXY_URL:-}
         - PASSKEY_EXTENSION_URL=${PASSKEY_EXTENSION_URL:-}

         # --- Integração com Chatwoot ---
         - CHATWOOT_SYSTEM_IDENTIFIER=${CHATWOOT_SYSTEM_IDENTIFIER:-}
         - CHATWOOT_SYSTEM_NAME=${CHATWOOT_SYSTEM_NAME:-}
         - CHATWOOT_PLATFORM_NAME=${CHATWOOT_PLATFORM_NAME:-Chatwoot}
         - CHATWOOT_SERVICE_URL=${CHATWOOT_SERVICE_URL:-}
         - CHATWOOT_GLOBAL_DB_HOST=${CHATWOOT_GLOBAL_DB_HOST:-}
         - CHATWOOT_GLOBAL_DB_PORT=${CHATWOOT_GLOBAL_DB_PORT:-5432}
         - CHATWOOT_GLOBAL_DB_NAME=${CHATWOOT_GLOBAL_DB_NAME:-}
         - CHATWOOT_GLOBAL_DB_USER=${CHATWOOT_GLOBAL_DB_USER:-}
         - CHATWOOT_GLOBAL_DB_PASS=${CHATWOOT_GLOBAL_DB_PASS:-}

         # --- Autenticação e licença ---
         - ADMIN_TOKEN=${SERVICE_PASSWORD_FZAP}
         - FLOUDS_LICENCE_KEY=${FLOUDS_LICENCE_KEY:-}
         - FLOUDS_LIFETIME_LICENCE_KEY=${FLOUDS_LIFETIME_LICENCE_KEY:-}

         # --- Banco principal ---
         - DB_DRIVER=postgres
         - DB_HOST=postgres
         - DB_PORT=5432
         - DB_NAME=${POSTGRES_DB:-fzap}
         - DB_USER=${POSTGRES_USER:-postgres}
         - DB_PASSWORD=${SERVICE_PASSWORD_POSTGRES}

         # --- WhatsApp, webhooks e mídia ---
         - SESSION_DEVICE_NAME=${SESSION_DEVICE_NAME:-Fzap}
         - WEBHOOK_FORMAT=json
         - IMAGE_QUALITY_HD=${IMAGE_QUALITY_HD:-false}
         - MAX_FILE_SIZE_MB=${MAX_FILE_SIZE_MB:-40}
         - DOWNLOAD_TIMEOUT_SECONDS=${DOWNLOAD_TIMEOUT_SECONDS:-120}
         - MESSAGE_DELIVERY_TIMEOUT_SECONDS=${MESSAGE_DELIVERY_TIMEOUT_SECONDS:-30}

         # --- Armazenamento S3 global ---
         - GLOBAL_S3_BUCKET=${GLOBAL_S3_BUCKET:-}
         - GLOBAL_S3_ACCESS_KEY=${GLOBAL_S3_ACCESS_KEY:-}
         - GLOBAL_S3_SECRET_KEY=${GLOBAL_S3_SECRET_KEY:-}
         - GLOBAL_S3_ENDPOINT=${GLOBAL_S3_ENDPOINT:-}
         - GLOBAL_S3_REGION=${GLOBAL_S3_REGION:-}
         - GLOBAL_S3_PATH_STYLE=${GLOBAL_S3_PATH_STYLE:-}
         - GLOBAL_S3_PUBLIC_URL=${GLOBAL_S3_PUBLIC_URL:-}
         - GLOBAL_S3_MEDIA_DELIVERY=${GLOBAL_S3_MEDIA_DELIVERY:-both}
         - GLOBAL_S3_RETENTION_DAYS=${GLOBAL_S3_RETENTION_DAYS:-}

         # --- Transcrição de áudio ---
         - TRANSCRIPTION_ENABLED=${TRANSCRIPTION_ENABLED:-false}
         - TRANSCRIPTION_PROVIDER=${TRANSCRIPTION_PROVIDER:-openai}
         - TRANSCRIPTION_API_KEY=${TRANSCRIPTION_API_KEY:-}
         - TRANSCRIPTION_MODEL=${TRANSCRIPTION_MODEL:-}
         - TRANSCRIPTION_BASE_URL=${TRANSCRIPTION_BASE_URL:-}

         # --- WhatsApp Cloud API (Meta Embedded Signup) ---
         - META_APP_ID=${META_APP_ID:-}
         - META_APP_SECRET=${META_APP_SECRET:-}
         - META_CONFIG_ID=${META_CONFIG_ID:-}

         # --- RabbitMQ ---
         - RABBITMQ_ENABLED=${RABBITMQ_ENABLED:-false}
         - RABBITMQ_URL=${RABBITMQ_URL:-}
         - RABBITMQ_EXCHANGE=${RABBITMQ_EXCHANGE:-fzap_events}
         - RABBITMQ_PREFIX=${RABBITMQ_PREFIX:-fzap}
         - RABBITMQ_FRAME_MAX=${RABBITMQ_FRAME_MAX:-131072}
         - RABBITMQ_HEARTBEAT=${RABBITMQ_HEARTBEAT:-30}
         - RABBITMQ_MAX_RECONNECT=${RABBITMQ_MAX_RECONNECT:-10}
         - RABBITMQ_RECONNECT_DELAY=${RABBITMQ_RECONNECT_DELAY:-5}
         - RABBITMQ_MAX_DELIVERY_ATTEMPTS=${RABBITMQ_MAX_DELIVERY_ATTEMPTS:-5}
         - RABBITMQ_DLQ_TTL_HOURS=${RABBITMQ_DLQ_TTL_HOURS:-168}
         - RABBITMQ_DLQ_MAX_LENGTH=${RABBITMQ_DLQ_MAX_LENGTH:-10000}

         # --- Monitoramento de erros ---
         - SENTRY_DSN=${SENTRY_DSN:-}
       volumes:
         - fzap_app_dbdata:/app/dbdata
         - fzap_files:/app/files
         - fzap_logos:/app/data/public-folder-logos
       depends_on:
         postgres:
           condition: service_healthy
       restart: unless-stopped

     postgres:
       image: pgvector/pgvector:pg17
       environment:
         - POSTGRES_PASSWORD=${SERVICE_PASSWORD_POSTGRES}
         - POSTGRES_USER=${POSTGRES_USER:-postgres}
         - POSTGRES_DB=${POSTGRES_DB:-fzap}
         - TZ=${TZ:-America/Sao_Paulo}
       volumes:
         - fzap_dbdata:/var/lib/postgresql/data
       healthcheck:
         test:
           - CMD-SHELL
           - pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}
         interval: 10s
         timeout: 5s
         retries: 10
         start_period: 20s
       restart: unless-stopped

   volumes:
     fzap_dbdata:
     fzap_app_dbdata:
     fzap_files:
     fzap_logos:
   ```

   [Abrir Compose oficial no GitHub](https://github.com/flouds-dncarbonell/installer-flouds/blob/main/deploy/coolify/docker-compose.yml)

3. **Revise as variáveis**  
   Confira `FZAP_LANGUAGE`, `SESSION_DEVICE_NAME` (nome do aparelho que aparece no WhatsApp) e `FLOUDS_LICENCE_KEY`. A licença pode ficar vazia no Free.

4. **Configure o domínio**  
   No serviço `fzap`, configure o domínio usando a porta interna `8080`.

5. **Faça o deploy**  
   Salve, faça o deploy e copie o `ADMIN_TOKEN` gerado nas variáveis do recurso.

## Easypanel: Gere o template no site da Flouds

Preencha os dados essenciais e receba um JSON pronto para importar. Senha do banco e ADMIN_TOKEN são criados localmente no seu navegador.

**Antes de começar** (5–10 min)

- Easypanel funcionando
- Domínio apontado para o servidor
- Acesso à importação de templates

1. **Gere o template**  
   Preencha os campos abaixo e gere o JSON. A senha do banco e o `ADMIN_TOKEN` são criados no seu navegador.

   O template cria o FZAP, PostgreSQL 17 com pgvector, volumes persistentes e credenciais exclusivas. As credenciais são geradas neste navegador e não são enviadas à Flouds.

   https://flouds.com.br/produtos/fzap/instalacao?metodo=easypanel

   > **Observação:** O `ADMIN_TOKEN` fica dentro do JSON. Guarde o arquivo baixado: é a senha do seu dashboard.

2. **Abra a importação**  
   No Easypanel, abra **Templates** e escolha **Import JSON**, **Create from JSON** ou **Custom Template**, conforme a sua versão.

3. **Crie o projeto**  
   Cole o JSON, dê um nome ao projeto e clique em **Create**.

4. **Adicione o domínio**  
   Abra o serviço `fzap`, adicione o domínio principal e confirme a porta de proxy `8080`.

5. **Faça o deploy**  
   Depois do deploy, o `ADMIN_TOKEN` também fica em **Serviço fzap → Environment**.

## Confirme que tudo está funcionando

1. Os serviços `fzap` e `postgres` aparecem como ativos no seu painel.
2. Você entra no dashboard pelo domínio, com o `ADMIN_TOKEN`.
3. Crie uma instância, conecte o WhatsApp e envie uma mensagem de teste.

## Free e pago usam a mesma instalação

A chave apenas define quais módulos ficam disponíveis. Ela não muda a imagem Docker, o banco ou o processo de deploy.

### Plano Free: Nenhuma licença é necessária

Deixe `FLOUDS_LICENCE_KEY` vazia. O Free não limita instâncias nem mensagens.

**No Free**

- API Core e dashboard
- Instâncias ilimitadas e pastas
- Nodes n8n e servidor MCP

**Com licença**

- Chatwoot nativo e Typebot
- Botões, listas, carrossel e Pix
- Tráfego pago + CAPI, chamadas e marca própria

[Comparar os planos pagos](https://flouds.com.br/produtos/fzap#fzap-pricing)

### Com licença: Adicione a chave à instalação

Copie sua chave na área de membros e adicione esta variável ao serviço.

```env
FLOUDS_LICENCE_KEY=SUA_CHAVE_AQUI
```

**Depois de colar a chave**

1. Atualize o serviço `fzap`: a chave é lida quando ele sobe
2. Abra o dashboard pelo domínio da licença. O plano aparece no selo do cabeçalho

> **Observação:** O plano mensal valida o endereço exato, com subdomínio (`api.suaempresa.com.br`). O vitalício valida o domínio raiz (`suaempresa.com.br`). Cadastre na área de membros o mesmo endereço pelo qual você abre o dashboard.

## Precisa de ajuda?

Use o canal correspondente ao seu plano ou consulte a referência completa da API.

- [Grupo da comunidade Free](https://chat.whatsapp.com/LAzqWDfq0pg5u054TVVUq6?mode=hq2tcla)
- [Suporte para licenciados](https://chat.whatsapp.com/K8ecdnQwDhQ9drDs71V2hA)
- [Documentação da API](https://flouds.com.br/produtos/fzap/docs)