Como instalar o WHMCS no servidor da revenda
Pré-requisitos, licença amarrada a domínio e IP, fechamento seguro da instalação e o que fazer quando o instalador trava, antes de ligar o provisionamento ao WHM.

Resposta curta: instale o WHMCS no endereço final, com PHP suportado e ionCube ativo, crie banco com todos os privilégios, rode /install/, apague a pasta install e configure o cron. A licença fica presa a domínio, IP e pasta; mudou, reemita.
Neste artigo
O que precisa estar pronto antes de abrir o instalador
O WHMCS é a camada de cobrança. Ele só cria contas no WHM depois de instalado, licenciado e ligado ao servidor. A criação da conta após o pagamento é disparada pela confirmação do pagamento, não pelo cron. O cron cuida das rotinas agendadas: faturas recorrentes, suspensões e lembretes. Quem pula essa ordem acaba depurando o módulo de provisionamento quando o problema está na instalação. Por isso vale separar a tarefa em duas: primeiro o WHMCS de pé e acessível pelo painel administrativo, depois a ligação com o WHM.
A documentação oficial da cPanel trata justamente dessas duas etapas iniciais, compra da licença e instalação, no guia How to Purchase and Install WHMCS. Use esse guia como referência para os passos da cPanel. O que segue organiza o processo para quem vai repetir isso em mais de um cliente e acrescenta o tratamento dos erros mais comuns.
Antes de baixar qualquer arquivo, confirme estes pontos na conta onde o WHMCS vai morar:
| Item | Como conferir | Por que trava a instalação |
|---|---|---|
| Domínio ou subdomínio definitivo | DNS já apontado e SSL emitido | A licença fica associada ao domínio usado no primeiro acesso |
| IP do servidor | IP que aparece no cPanel da conta | A licença também valida o IP de onde o WHMCS responde |
| Versão de PHP suportada | MultiPHP Manager no cPanel | Versão fora da faixa suportada faz o verificador de requisitos recusar |
| ionCube Loader ativo | php -m ou phpinfo |
Os arquivos do WHMCS são codificados e não executam sem ele |
| Banco MySQL e usuário | MySQL Databases no cPanel | O instalador cria as tabelas e precisa de todas as permissões |
| Acesso ao cron | Cron Jobs no cPanel | Sem cron, faturas recorrentes, suspensões e lembretes não rodam (a criação da conta após o pagamento depende da confirmação do pagamento, não do cron) |
A faixa exata de versões de PHP suportadas muda a cada versão do WHMCS. Consulte os requisitos da versão que você vai baixar, não um tutorial antigo.
Por que a licença do WHMCS trava se domínio, IP ou pasta mudarem
A licença do WHMCS é validada contra o domínio, o IP e o diretório da instalação. Na prática, o primeiro acesso define esses valores. Se você instala em teste.cliente.com.br para depois mover para financeiro.cliente.com.br, a licença passa a acusar inválida no novo endereço.
Isso tem duas consequências para quem trabalha com vários clientes:
- Instale direto no endereço final. Subdomínio dedicado (por exemplo,
financeiro.ouarea.) costuma ser mais limpo que uma subpasta do site institucional, porque a migração do site não arrasta o WHMCS junto. - Mudou domínio, IP ou pasta, reemita a licença. A reemissão (reissue) é feita na área de cliente de quem vendeu a licença. Se a compra foi pela loja da cPanel, procure a reemissão na área de cliente dessa loja, não no suporte da WHMCS. Em caso de dúvida, confirme com quem vendeu a licença.
Troca de servidor é o caso que mais pega agência de surpresa: o IP muda, o WHMCS para de abrir o painel e o cliente acha que perdeu os dados. Os dados estão no banco. Só a validação falhou.
Frase pronta para o cliente: "A licença do sistema de cobrança é registrada no endereço e no servidor onde ele roda. Como mudamos de servidor, preciso reemitir a licença. Os dados continuam intactos."
Conferindo PHP e ionCube pelo terminal
Se a conta tem acesso SSH, dois comandos resolvem a maior parte das dúvidas antes de começar:
php -v
php -m | grep -i ioncube
O primeiro mostra a versão do PHP de linha de comando. O segundo deve devolver uma linha com ionCube Loader. Se não devolver nada, o loader não está carregado.
Atenção a um detalhe que gera horas de confusão: em servidores cPanel, o PHP do terminal pode ser diferente do PHP que atende o site. O que vale para o instalador web é o PHP configurado para o domínio no MultiPHP Manager. Para conferir o PHP web, crie temporariamente um arquivo com phpinfo() na pasta da instalação, abra no navegador, procure por ionCube e apague o arquivo em seguida.
Em conta de revenda você não controla os módulos do servidor. Se o ionCube não estiver disponível, peça ao provedor para habilitá-lo. Não tente contornar.
Instalação passo a passo
O guia da cPanel cobre a compra da licença e a instalação. Detalhes como renomear configuration.php.new, a permissão 400 e o intervalo do cron são prática comum, não parte desse guia: confira na documentação da versão que você baixou. Os nomes de pasta e domínio são exemplos fictícios.
Obter a licença e baixar o pacote
Compre a licença (pela loja da cPanel ou diretamente na WHMCS) e baixe o pacote da versão atual. Guarde a chave de licença: o instalador vai pedi-la.
Criar banco e usuário no MySQL do cPanel
No cPanel, em MySQL Databases, crie um banco (exemplo: cliente_whmcs), um usuário com senha forte e associe os dois com todos os privilégios. Anote nome do banco, usuário e senha exatamente como o cPanel mostra, com o prefixo da conta.
Enviar e extrair os arquivos na raiz do subdomínio
Envie o pacote para a raiz do subdomínio (exemplo: /home/cliente/financeiro.cliente.com.br/) e extraia pelo Gerenciador de Arquivos. Se o pacote trouxer configuration.php.new, renomeie para configuration.php (confira na documentação da versão se o passo se aplica). O instalador grava os dados de conexão nesse arquivo, então ele precisa existir e estar gravável.
Rodar o instalador em /install/
Acesse https://financeiro.cliente.com.br/install/ no navegador. O fluxo aceita os termos, verifica requisitos, pede a chave de licença, os dados do banco e cria o primeiro administrador. Use um usuário administrador que não seja admin.
Apagar a pasta install e fechar a permissão do configuration.php
Ao final, apague a pasta install e proteja o arquivo de configuração. A permissão 400 abaixo é prática recomendada. Confira o que a documentação da sua versão indica:
cd /home/cliente/financeiro.cliente.com.br
rm -rf install
chmod 400 configuration.php
ls -l configuration.php
O ls -l deve mostrar -r--------. Enquanto a pasta install existir, o painel administrativo exibe aviso e a instalação fica exposta.
Configurar o cron com o comando copiado do painel
No cPanel, em Cron Jobs, adicione a tarefa de automação. Exemplo ilustrativo, com intervalo de 5 minutos e caminho a ajustar (a frequência recomendada está na documentação da versão):
*/5 * * * * php -q /home/cliente/financeiro.cliente.com.br/crons/cron.php
O WHMCS mostra o comando exato, com o caminho correto, em Configurações do sistema, na seção de automação. Copie de lá em vez de digitar. Depois de algumas execuções, o painel deixa de avisar que o cron não está rodando.
O que fazer quando o instalador para no meio
Instalação interrompida deixa um estado misto: parte das tabelas criadas, configuration.php às vezes preenchido, às vezes não. Rodar de novo por cima costuma falhar com erro de tabela já existente. O caminho limpo:
| Sintoma | Causa provável | O que fazer |
|---|---|---|
Tela branca ou erro 500 ao abrir /install/ |
ionCube ausente ou PHP incompatível | Conferir MultiPHP e phpinfo, ajustar e recarregar |
| Verificador de requisitos aponta item em vermelho | Extensão PHP faltando | Ativar a extensão no seletor de PHP ou pedir ao provedor |
| Erro de conexão com o banco | Nome sem prefixo, senha errada ou usuário sem privilégio | Copiar os nomes exatos do cPanel e reassociar com todos os privilégios |
| Mensagem de licença inválida | Chave errada, ou domínio, IP ou pasta diferente do registrado | Conferir a chave e reemitir a licença |
| Para na criação das tabelas | Tempo limite do PHP ou conexão caiu | Limpar o banco e reiniciar a instalação |
| Instalação conclui mas não grava nada | configuration.php inexistente ou sem permissão de escrita |
Renomear o .new e liberar escrita só durante a instalação |
Para reiniciar do zero sem deixar lixo:
- No phpMyAdmin, apague todas as tabelas do banco do WHMCS (ou exclua e recrie o banco com o mesmo usuário). Só faça isso em instalação nova, nunca em WHMCS com clientes cadastrados.
- Restaure
configuration.phpa partir de uma cópia limpa deconfiguration.php.new. - Confirme que a pasta
installainda está lá. Se você a apagou, extraia de novo só essa pasta do pacote. - Corrija a causa pela tabela acima e rode o instalador.
Se o erro persistir, ative a exibição de erros temporariamente ou leia o error_log da pasta. A mensagem real quase sempre aparece ali, e é ela que o suporte vai pedir.
Checklist reutilizável para cada cliente
Para padronizar entre vários projetos, transforme o processo em lista e marque item a item:
- Endereço final definido, DNS apontado e SSL ativo
- IP do servidor anotado junto com a chave de licença
- PHP do domínio na faixa suportada e ionCube confirmado via phpinfo
- Banco e usuário criados, privilégios completos, credenciais salvas no cofre de senhas
configuration.phprenomeado antes do instalador- Administrador criado com usuário próprio e autenticação em dois fatores
- Pasta
installapagada econfiguration.phpcom permissão 400 - Cron configurado com o comando copiado do painel
- Aviso de cron sumiu do painel após algumas execuções
- Backup do banco agendado antes de cadastrar o primeiro cliente
Só depois dessa lista fechada faz sentido cadastrar o servidor WHM e o módulo cPanel no WHMCS. Se o provisionamento falhar nesse ponto, você já sabe que a instalação está sã e pode olhar direto para a integração.
Frase pronta para o cliente: "O sistema de cobrança já está instalado e licenciado. A próxima etapa é ligá-lo ao servidor para que as hospedagens sejam criadas automaticamente quando a fatura for paga."
Referências
- Documentação oficial (cpanel) — How to Purchase and Install WHMCS. Consultado em 2026-11-10.