# Instalação do BullQ no cPanel

## 1. Recursos e domínios

Use Node.js 20.9 ou superior e MySQL 5.7.44 ou superior. MariaDB e o PostgreSQL 9.2 existente não são usados. O modo MySQL 5.7 serializa somente a reivindicação curta dos jobs; o processamento posterior continua concorrente.

- `bullq.propero.com.br`: frontend.
- `api-bullq.propero.com.br`: API, Socket.IO, Swagger, webhooks e uploads.
- MCP não faz parte desta instalação.

Crie os dois subdomínios e aguarde o AutoSSL antes de configurar os canais.

## 2. Banco MySQL

No **MySQL Databases**, crie um banco `bullq`, um usuário exclusivo e conceda `ALL PRIVILEGES`. Não reutilize credenciais de outro sistema. A senha precisa ser URL-encoded dentro de `DATABASE_URL` (`@` vira `%40`, por exemplo).

O primeiro início executa somente o baseline em um banco vazio. Depois disso, migrations são aplicadas em `https://api-bullq.propero.com.br/__bullq-deploy`, sempre precedidas por backup.

## 3. Arquivos

Extraia `bullq-cpanel-node20.zip` em `/home2/avida/public_html/hotsites/bullq`. A estrutura final deve conter:

```text
bullq/
  api/
  web/
  shared/
    backups/
    incoming/
    uploads/
```

Restrinja a leitura do arquivo `.env` e configure a futura conta FTP com raiz em `public_html/hotsites/bullq/shared/incoming`.

## 4. Aplicações Node.js

No **Setup Node.js App**, modo `Production` e Node 20:

1. API: root `public_html/hotsites/bullq/api`, URL `api-bullq.propero.com.br`, startup `app.js`.
2. Web: root `public_html/hotsites/bullq/web`, URL `bullq.propero.com.br`, startup `app.js`.

Na API, use **Run NPM Install** uma vez. O frontend standalone já contém suas dependências de runtime.

Cadastre na aplicação da API as variáveis de `.env.cpanel.example`, substituindo `CPANEL_USER` e todos os segredos. No build web, `NEXT_PUBLIC_API_URL` já é `https://api-bullq.propero.com.br/api/v1`.

## 5. Inicialização e migrations

Inicie primeiro a API. O launcher cria o baseline MySQL e grava `shared/.mysql-installed`. Abra o painel de implantação, informe `DEPLOY_ADMIN_TOKEN` e execute:

1. **Verificar ambiente**;
2. **Ver migrations**;
3. **Criar backup**;
4. **Backup e migrar**, digitando `MIGRAR`.

Nunca apague `.mysql-installed` em uma base com dados e nunca use `prisma db push` em produção.

## 6. Manter o Passenger ativo

No **Cron Jobs**, adicione a cada minuto:

```sh
curl -fsS https://api-bullq.propero.com.br/__bullq-deploy/health >/dev/null 2>&1
```

Isso impede a suspensão por inatividade e mantém filas, cron e jobs adiados processando.

## 7. Validação

Confirme, nesta ordem:

- `https://api-bullq.propero.com.br/docs` abre o Swagger;
- o health do painel retorna `database: mysql` e `redis: false`;
- login e refresh token;
- atualização em tempo real no inbox;
- upload persistente após reiniciar a aplicação;
- criação de um canal de teste e recepção de webhook;
- envio de mensagem e execução de uma automação simples.

Comece com `AUTOMATIONS_ENABLED=false`; habilite somente depois do teste dos canais. RAG permanece desativado com `RAG_ENABLED=false`.

## 8. Atualizações

Antes de atualizar, envie o novo pacote para `shared/incoming`, confira o checksum, extraia os componentes nas respectivas raízes e use o painel para backup/migration. Toque `api/tmp/restart.txt` e `web/tmp/restart.txt` pelo Gerenciador de Arquivos para o Passenger recarregar os processos. Preserve sempre `shared/`.