# Instalar Conversa 0.2.0 no cPanel

Destino: **https://app.leanmarket.com.br**. Este pacote prepara a aplicação; não altera o domínio, DNS ou servidor automaticamente.

## 1. Requisitos do servidor

- cPanel com **Setup Python App / Configurar aplicativo Python** (CloudLinux) ou Application Manager com Passenger configurado pela hospedagem.
- Python **3.12 ou superior**, pip, módulo sqlite3 e suporte a scrypt/hashlib (Python padrão).
- HTTPS válido no subdomínio app.leanmarket.com.br.
- Cron Jobs habilitado; saída HTTPS para Meta e integrações quando forem configuradas.
- Um único servidor e disco local para o SQLite. Não usar volume de rede nem vários hosts.

Se o painel não oferecer aplicativo Python, a hospedagem precisa habilitar esse recurso. Enviar o ZIP somente para public_html não executa uma aplicação Python.

## 2. Criar a aplicação Python

No cPanel → **Setup Python App** → **Create Application**:

| Campo | Valor |
|---|---|
| Python version | 3.12 ou superior |
| Application root | `conversa` |
| Application URL — domínio | `app.leanmarket.com.br` |
| Application URL — caminho | Vazio, para usar a raiz `/` |
| Application startup file | `passenger_wsgi.py` |
| Application Entry point | `application` |
| Modo | Production, se o painel oferecer a opção |

A raiz física deve ficar em **/home/SEU_USUARIO/conversa**, fora de public_html e fora da pasta pública do subdomínio. O cPanel/Passenger conecta o domínio a essa pasta privada. Não instale sobre o ERP Horizonte Cred.

O painel pode criar um arquivo de exemplo. No próximo passo, substitua apenas esse exemplo pelos arquivos do pacote.

## 3. Enviar o pacote e instalar dependências

1. No Gerenciador de Arquivos, envie `Conversa-0.2.0-cPanel.zip` para a pasta **home** da conta (um nível acima de public_html).
2. Extraia o ZIP. Ele já contém a pasta **conversa/**.
3. Confira que `/home/SEU_USUARIO/conversa/passenger_wsgi.py` existe. Evite a estrutura duplicada `conversa/conversa/`.
4. Retorne ao aplicativo Python. Em **Configuration files**, adicione `requirements.txt`, se necessário.
5. Clique em **Run pip install**. Aguarde o término sem erros.

Alternativa se sua interface não tiver esse botão: use o Terminal do cPanel com o comando de ativação do ambiente que o próprio painel exibe e execute `python -m pip install -r /home/SEU_USUARIO/conversa/requirements.txt`. Isso é só a instalação; depois o aplicativo não depende de manter o Terminal aberto.

## 4. Definir a chave de instalação

No Gerenciador de Arquivos, dentro de **conversa/**:

1. Copie **server_config.example.json** para **server_config.json**.
2. Edite a cópia. No campo `install_token`, coloque uma chave privada criada por você, com **24 a 256 caracteres**. Evite aspas ou barras invertidas para facilitar o preenchimento JSON.
3. Mantenha `site_url` como `https://app.leanmarket.com.br` e `data_dir` como `instance`.
4. Salve. O aplicativo restringe esse arquivo e os dados privados às permissões do proprietário.
5. Clique em **Restart** no aplicativo Python.

Também é possível definir INSTALL_TOKEN nas variáveis do aplicativo, em vez de colocá-la no JSON. Para segredos Meta/webhooks que também serão usados pelo cron, prefira o objeto `environment` do JSON privado, pois variáveis criadas apenas no aplicativo web podem não existir nas tarefas agendadas.

Não há senha padrão no ZIP. A chave de instalação é diferente da senha do administrador e não deve ser enviada na URL.

## 5. Concluir no navegador

Abra **https://app.leanmarket.com.br/install**.

Preencha:

- Chave privada de instalação, igual à definida no passo anterior.
- Seu e-mail de administrador da plataforma.
- Senha de acesso com pelo menos 12 caracteres e confirmação.

Ao concluir, o sistema vai para o login e bloqueia o instalador. Entre com o acesso criado. Não são geradas empresas, clientes ou conversas fictícias.

No perfil da plataforma:

1. Clique em **Nova empresa**.
2. Cadastre a empresa, um identificador simples (ex.: `leanmarket`) e **outro e-mail** para o administrador dessa empresa. Os logins são individuais e o e-mail deve ser único.
3. Defina a senha inicial dessa conta.
4. Saia do perfil da plataforma e entre como administrador da empresa para cadastrar atendentes, departamentos e canais.

O administrador da plataforma gerencia empresas; o administrador da empresa gerencia sua operação. Isso preserva a separação entre clientes do produto.

## 6. Configurar o cron sem deixar terminal aberto

A tela **Empresas** do administrador da plataforma e a tela **Conexões** do administrador da empresa mostram **Processador de mensagens** e o comando completo de cron, com os caminhos calculados pelo servidor.

1. Copie o comando exibido na tela.
2. Abra cPanel → **Cron Jobs**.
3. Configure **uma vez por minuto**: minuto `*`, hora `*`, dia `*`, mês `*`, dia da semana `*`.
4. Cole o comando e salve.
5. Aguarde até dois minutos, atualize a tela do sistema e confira que o processador aparece **ativo**.

O comando usa o Python do aplicativo, processa a fila por cerca de 45 segundos e encerra. Um lock impede execuções simultâneas. O orçamento é flexível: uma requisição externa já iniciada pode terminar depois desse prazo. O log fica em `instance/worker.log`.

Esse modo de hospedagem pode introduzir espera entre execuções e está sujeito aos limites de processos do provedor. Para operação de atendimento com menor latência e maior volume, prefira worker contínuo supervisionado em VPS/servidor. Não execute `run_demo.py`, `manage.py serve` ou um servidor Flask de desenvolvimento no site público.

## 7. Verificar a instalação

- https://app.leanmarket.com.br/health deve retornar versão **0.2.0**.
- A tela de login deve abrir em HTTPS.
- O instalador deve responder como indisponível/404 após a criação do administrador.
- O processador deve aparecer ativo na interface.
- Empresas e usuários cadastrados devem continuar presentes após **Restart** no cPanel.

`/health` é uma verificação de processo, não prova de WhatsApp conectado. Não há domínio publicado ou instalação remota comprovada por este pacote.

## WhatsApp e IA

O adaptador Meta continua aguardando credenciais e homologação externa. O campo `environment` no JSON aceita somente variáveis META_, WA_TOKEN_COMPANY_ e WEBHOOK_, com os mesmos nomes documentados em `docs/API.md`. Não exponha esse arquivo. O instalador não ativa WhatsApp ou IA automaticamente.

O modo servidor desativa o simulador e não cria dados de demonstração. A IA ainda não está ativa. Mídias WhatsApp, templates e demais pendências estão em `docs/ESTADO.md`.

## Atualizar sem apagar os dados

Faça backup da conta/pasta privada e do banco antes de atualizar, pausando o aplicativo e o cron durante uma cópia simples. Preserve **instance/** e **server_config.json**. Extraia somente o código novo e reinicie. Não delete `session-secret`: essa chave mantém a validade das sessões. Migrações são aplicadas automaticamente e não recriam usuários ou apagam chamados.

## Se ocorrer erro

| Sintoma | Verificação |
|---|---|
| Python App não aparece no painel | Solicitar à hospedagem Python/Passenger; pacote não funciona como arquivo PHP |
| ModuleNotFoundError: flask | Run pip install no ambiente do aplicativo, não no Python global |
| Página padrão “It works” | Confirmar raiz e substituir arquivo de exemplo por passenger_wsgi.py do pacote; Restart |
| 500 antes de abrir instalador | Verificar log Passenger; JSON válido, Python 3.12+, permissões e dependências |
| “Prepare sua instalação” | Chave INSTALL_TOKEN não definida; configurar e reiniciar |
| Host não autorizado | Conferir site_url e domínio/caminho da aplicação |
| Redirecionamento HTTPS repetido | Hospedagem/proxy não informa HTTPS no WSGI; não desligar cookies seguros, ajustar proxy com o provedor |
| Processador não fica ativo | Confirmar cron, Python do ambiente e log privado instance/worker.log |
| Mensagem fica pendente | Conferir processador; mensagem incerta não deve ser reenviada sem conciliação |

Não envie server_config.json, tokens, session-secret, banco ou senhas em prints públicos. Para diagnóstico basta a mensagem de erro e a tela de configuração sem segredos.

## Referências oficiais consultadas

- [cPanel — aplicação Python WSGI](https://docs.cpanel.net/knowledge-base/web-services/how-to-install-a-python-wsgi-application/)
- [CloudLinux — componentes e Python Selector](https://docs.cloudlinux.com/cloudlinuxos/cloudlinux_os_components/)
- [cPanel — Cron Jobs](https://docs.cpanel.net/cpanel/advanced/cron-jobs/)