# Instala FZAP en tu servidor

> Elige el método que encaja con tu infraestructura. La misma imagen Docker sirve para el plan Free y todas las licencias de pago.

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

## Manual: Instalación manual con Portainer

Usa este camino si Docker Swarm, Portainer, PostgreSQL, red y proxy ya están preparados. Podrás revisar el stack y cada variable antes del deploy.

**Antes de empezar** (15–25 min)

- Docker Swarm activo
- Portainer accesible
- PostgreSQL disponible
- Traefik y dominio configurados

1. **Crea los volúmenes**  
   Crea los volúmenes externos usados por los datos locales y los archivos de FZAP.

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

2. **Pega el stack en Portainer**  
   En Portainer, abre **Stacks → Add stack**, usa el nombre `fzap` y pega el stack oficial de abajo.

   ```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 en GitHub](https://github.com/flouds-dncarbonell/projeto-fzap/blob/main/stack.yml)

3. **Define el token y revisa las variables**  
   Cambia `ADMIN_TOKEN` por un valor tuyo y revisa la base de datos, el dominio, `FZAP_LANGUAGE` y la zona horaria. Si tienes licencia, completa `FLOUDS_LICENCE_KEY`.

   > **Atención:** No dejes `ADMIN_TOKEN` vacío: sin él, FZAP genera un token nuevo en cada reinicio y el acceso al dashboard cambia con él.

4. **Haz el deploy**  
   Haz clic en **Deploy the stack** y espera hasta que el servicio `fzap` esté activo.

5. **Entra al dashboard**  
   Abre el dominio configurado, entra con el `ADMIN_TOKEN` y prueba la API.

   > **Nota:** Abre siempre por el dominio, no por la IP. Esa es la dirección que valida la licencia.

## Instalador: Prepara e instala con un comando

Ideal para una VPS nueva. El instalador detecta el sistema, prepara la infraestructura y guía la instalación de FZAP desde el terminal.

**Antes de empezar** (10–20 min)

- Acceso root a la VPS
- 2 vCPU y 2 GB de RAM
- Puertos 80 y 443 abiertos
- Dos dominios apuntados a la VPS

**El instalador prepara la infraestructura**. No necesitas instalar ni configurar estos componentes manualmente.

- Docker y Docker Swarm
- Traefik con HTTPS
- Portainer
- PostgreSQL 17 con pgvector
- Red Docker compartida
- Volúmenes y servicio FZAP

[La instalación por terminal en vídeo](https://www.youtube.com/watch?v=ANKm_9I-Rno)

1. **Conéctate a la VPS**  
   Entra por SSH con un usuario que pueda ejecutar `sudo`.

2. **Ejecuta el instalador**  
   Ejecuta el comando de abajo y espera mientras se prepara el entorno.

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

3. **Elige instalar FZAP**  
   En el menú, elige **Instalar FZAP en este servidor**.

4. **Indica dominios y licencia**  
   Indica los dominios que se piden y, si la tienes, la clave de licencia. Déjala vacía para usar Free.

5. **Confirma y espera**  
   Confirma los datos y espera a que el instalador verifique que todos los servicios están en línea.

## Coolify: Instala como recurso de Coolify

Coolify administra proxy, HTTPS, red, volúmenes y credenciales. Solo necesitas crear el recurso, pegar el Compose oficial y configurar el dominio.

**Antes de empezar** (8–15 min)

- Coolify funcionando
- Dominio apuntado al servidor
- Proyecto creado en Coolify

1. **Crea el recurso**  
   En el proyecto deseado, haz clic en **New Resource** y elige **Docker Compose Empty**.

2. **Pega el Compose oficial**  
   Copia todo el `docker-compose.yml` de abajo y pégalo en el editor del 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 en GitHub](https://github.com/flouds-dncarbonell/installer-flouds/blob/main/deploy/coolify/docker-compose.yml)

3. **Revisa las variables**  
   Revisa `FZAP_LANGUAGE`, `SESSION_DEVICE_NAME` (nombre del dispositivo que aparece en WhatsApp) y `FLOUDS_LICENCE_KEY`. La licencia puede quedar vacía en Free.

4. **Configura el dominio**  
   En el servicio `fzap`, configura el dominio con el puerto interno `8080`.

5. **Haz el deploy**  
   Guarda, haz el deploy y copia el `ADMIN_TOKEN` generado en las variables del recurso.

## Easypanel: Genera el template en el sitio de Flouds

Completa los datos esenciales y recibe un JSON listo para importar. La contraseña de la base y ADMIN_TOKEN se crean localmente en tu navegador.

**Antes de empezar** (5–10 min)

- Easypanel funcionando
- Dominio apuntado al servidor
- Acceso a importar templates

1. **Genera el template**  
   Completa los campos de abajo y genera el JSON. La contraseña de la base y el `ADMIN_TOKEN` se crean en tu navegador.

   El template crea FZAP, PostgreSQL 17 con pgvector, volúmenes persistentes y credenciales exclusivas. Las credenciales se generan en este navegador y no se envían a Flouds.

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

   > **Nota:** El `ADMIN_TOKEN` queda dentro del JSON. Guarda el archivo descargado: es la contraseña de tu dashboard.

2. **Abre la importación**  
   En Easypanel, abre **Templates** y elige **Import JSON**, **Create from JSON** o **Custom Template**, según tu versión.

3. **Crea el proyecto**  
   Pega el JSON, ponle un nombre al proyecto y haz clic en **Create**.

4. **Agrega el dominio**  
   Abre el servicio `fzap`, agrega el dominio principal y confirma el puerto de proxy `8080`.

5. **Haz el deploy**  
   Después del deploy, el `ADMIN_TOKEN` también queda en **Servicio fzap → Environment**.

## Confirma que todo funciona

1. Los servicios `fzap` y `postgres` aparecen activos en tu panel.
2. Entras al dashboard por el dominio, con el `ADMIN_TOKEN`.
3. Crea una instancia, conecta WhatsApp y envía un mensaje de prueba.

## Free y pago usan la misma instalación

La clave solo define qué módulos quedan disponibles. No cambia la imagen Docker, la base de datos ni el deploy.

### Plan Free: No necesitas una licencia

Deja `FLOUDS_LICENCE_KEY` vacía. Free no limita instancias ni mensajes.

**En Free**

- API Core y dashboard
- Instancias ilimitadas y carpetas
- Nodes n8n y servidor MCP

**Con licencia**

- Chatwoot nativo y Typebot
- Botones, listas, carrusel y Pix
- Tráfico pago + CAPI, llamadas y marca propia

[Comparar los planes de pago](https://flouds.com.br/es/produtos/fzap#fzap-pricing)

### Con licencia: Agrega la clave a la instalación

Copia tu clave en el área de miembros y agrega esta variable al servicio.

```env
FLOUDS_LICENCE_KEY=SUA_CHAVE_AQUI
```

**Después de pegar la clave**

1. Actualiza el servicio `fzap`: la clave se lee al arrancar
2. Abre el dashboard por el dominio de la licencia. El plan aparece en el sello del encabezado

> **Nota:** El plan mensual valida la dirección exacta, con subdominio (`api.tuempresa.com`). El vitalicio valida el dominio raíz (`tuempresa.com`). Registra en el área de miembros la misma dirección por la que abres el dashboard.

## ¿Necesitas ayuda?

Usa el canal correspondiente a tu plan o consulta la referencia completa de la API.

- [Grupo de la comunidad Free](https://chat.whatsapp.com/LAzqWDfq0pg5u054TVVUq6?mode=hq2tcla)
- [Soporte para licenciados](https://chat.whatsapp.com/K8ecdnQwDhQ9drDs71V2hA)
- [Documentación de la API](https://flouds.com.br/es/produtos/fzap/docs)