blog
Revenda

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.

JR · · 7 min de leitura · 2 tabelas · 3 blocos de código

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
  1. O que precisa estar pronto antes de abrir o instalador
  2. Por que a licença do WHMCS trava se domínio, IP ou pasta mudarem
  3. Conferindo PHP e ionCube pelo terminal
  4. Instalação passo a passo
  5. O que fazer quando o instalador para no meio
  6. Checklist reutilizável para cada cliente

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.

Ordem certa de instalação do WHMCSConta de cobrançaInstalação do WHMCSLigação com o WHM
Duas etapas separadas: primeiro o WHMCS funcionando, depois a integração com o servidor.

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:

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.

O que fazer quando a licença recusa o novo endereçoMudou domínio, IP ou pastaReemitir a licença na loja de quem vendeuDados continuam no banco
Fluxo a seguir quando a instalação muda de endereço.

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:

  1. 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.
  2. Restaure configuration.php a partir de uma cópia limpa de configuration.php.new.
  3. Confirme que a pasta install ainda está lá. Se você a apagou, extraia de novo só essa pasta do pacote.
  4. 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:

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

  1. Documentação oficial (cpanel) — How to Purchase and Install WHMCS. Consultado em 2026-11-10.
Leia também