Instalar cPanel no VPS: 5 decisões antes do instalador
A folha de decisões que você preenche antes de abrir o terminal, o que esperar na tela durante a execução e qual log ler quando o instalador para.

Resposta curta: são cinco decisões que precisam estar fechadas antes de rodar o instalador do cPanel num VPS limpo: hostname totalmente qualificado, versão de MySQL/MariaDB, perfil de pacotes, nameservers e servidor de e-mail. Errar parte delas custa reinstalar o sistema operacional inteiro.
Neste artigo
- O que custa caro é refazer, não instalar
- As cinco decisões, em uma folha
- Hostname totalmente qualificado, e por que não pode ser o domínio do cliente
- Versão de MySQL/MariaDB fixada por arquivo, antes de instalar
- Perfil de pacotes, nameservers e servidor de e-mail no arquivo de configuração
- Rodando o instalador e o que esperar na tela
- Quando o instalador para com erro
- Padronizando a folha de decisões em agência
O que custa caro é refazer, não instalar
Instalar o cPanel num VPS limpo é um comando. O que machuca é descobrir, três dias depois de migrar os sites do cliente, que o hostname ficou errado, que o MariaDB subiu numa versão que o plugin do cliente não suporta, ou que o servidor levantou um BIND que você não queria.
A documentação oficial da cPanel é explícita sobre o ponto central: a personalização da instalação acontece antes de executar o instalador, por arquivos de configuração que o instalador lê uma única vez (Customize Your Installation). Depois que a instalação termina, parte dessas escolhas deixa de ser um campo no WHM e passa a ser um procedimento de reinstalação do sistema operacional.
Para quem entrega VPS de cliente, isso vira uma folha de decisões. Cinco linhas preenchidas antes de abrir o terminal, arquivadas junto do projeto, iguais em todo servidor novo.
As cinco decisões, em uma folha
| Decisão | Onde se define antes | Custo de mudar depois |
|---|---|---|
| Hostname FQDN | hostname do sistema, antes do instalador |
Mudança é possível, mas afeta certificados de serviço, PTR e os registros DNS do próprio hostname; evite fazer com sites em produção |
| Versão de MySQL/MariaDB | arquivo de configuração de instalação lido pelo instalador | Downgrade de versão de banco não é suportado; voltar significa reinstalar |
| Perfil de pacotes | opção de perfil na chamada do instalador | Trocar o conjunto base depois é remendo, não configuração |
| Nameservers (tipo de DNS) | arquivo de configuração de instalação | Reversível no WHM, mas obriga a refazer zonas e delegação |
| Servidor de e-mail | arquivo de configuração de instalação | Reversível, com risco de deixar contas e caixas em estado inconsistente |
Preencha a folha com o cliente ao lado, não no meio da instalação.
Hostname totalmente qualificado, e por que não pode ser o domínio do cliente
O cPanel exige um hostname totalmente qualificado, e não um nome curto. A regra prática que resolve a maioria das entregas: subdomínio dedicado + domínio que você controla, e esse subdomínio não pode ser um domínio que vá hospedar sites no próprio servidor.
Bom: srv01.suaagencia.com.br, node3.infra-cliente.com.
Ruim: servidor, localhost.localdomain, clientefinal.com.br (o próprio domínio do site).
O motivo do "ruim" do final é chato de descobrir tarde: se o hostname é o mesmo domínio que você vai criar como conta no WHM, você entra em conflito de zona DNS e de vhost. Prefira sempre um domínio de infraestrutura da agência, com um subdomínio por servidor. Isso também padroniza o inventário: srv01, srv02, srv03.
Antes de rodar o instalador, confira o que o sistema responde:
hostname -f
# deve devolver algo como srv01.suaagencia.com.br
E deixe o registro A desse subdomínio apontando para o IP do VPS, com o PTR (DNS reverso) pedido ao provedor do IP. PTR não é requisito do instalador, mas é requisito de entregabilidade de e-mail, e é muito mais barato pedir agora do que depois que o cliente reclamar que a Microsoft rejeita as mensagens.
Versão de MySQL/MariaDB fixada por arquivo, antes de instalar
Esta é a decisão que mais gera reinstalação. A documentação de personalização da instalação descreve que a versão de banco de dados é uma das opções que o instalador lê de um arquivo de configuração colocado no servidor antes da execução. Se você não fixa nada, o instalador aplica o padrão da versão corrente do cPanel, que muda ao longo do tempo.
Por que isso importa na prática de agência: upgrade de MySQL/MariaDB é caminho de mão única. Downgrade não é suportado. Se o sistema legado do cliente só foi homologado numa versão anterior, e o servidor subiu com uma superior, a saída realista é reinstalar o sistema operacional e começar de novo.
O procedimento documental é: criar /root/cpanel_profile/cpanel.config antes de baixar o instalador e declarar a versão de banco na chave mysql-version, uma linha por chave, no formato chave=valor. Para fixar MariaDB 10.6, por exemplo:
mysql-version=10.6
Na mesma página estão as chaves das outras duas decisões de infraestrutura: local_nameserver_type, que define o tipo de servidor de nomes (incluindo disabled), e mailserver, que define o servidor de e-mail (também com disabled entre os valores). Monte o arquivo e só então baixe e execute o instalador. Como os nomes de chave e o caminho variam entre versões do cPanel, confira o valor exato na página Customize Your Installation na data da instalação, em vez de copiar um arquivo antigo do repositório da agência sem revisar.
Antes de preencher essa linha da folha, levante com o cliente:
- versão mínima e máxima suportada pelo ERP, CRM ou plugin crítico;
- versão do servidor de origem, se for migração (migrar para versão igual ou superior, nunca inferior);
- se há dependência de
utf8mb4ou de modos SQL estritos.
Perfil de pacotes, nameservers e servidor de e-mail no arquivo de configuração
Perfil de pacotes
O instalador aceita um perfil que define o conjunto de componentes instalados. Um servidor que só vai rodar WordPress de clientes não precisa do mesmo conjunto de um servidor de revenda completo. A escolha afeta consumo de memória e superfície de ataque, e é decisão de arquitetura, não de ajuste fino. Decida antes.
Nameservers
Aqui a pergunta real é: o DNS dos clientes vai morar neste servidor ou num DNS externo (registrador, Cloudflare, DNS gerenciado)? Se for externo, instalar um servidor de nomes completo só adiciona um daemon que você vai ter que atualizar para sempre. A configuração de instalação permite definir o tipo de servidor de nomes, incluindo não instalar nenhum.
Para agência, o padrão que economiza manutenção costuma ser: DNS fora do servidor web, servidor web sem authoritative DNS. Documente a escolha na folha, porque o próximo profissional que abrir o WHM vai procurar a zona onde ela não está.
Servidor de e-mail
Mesma lógica. Se o cliente usa Google Workspace ou Microsoft 365, você não quer um servidor de e-mail ativo competindo com o MX externo e recebendo entrega local por engano. A configuração de instalação permite definir o servidor de e-mail, incluindo desabilitado. Se tiver qualquer dúvida sobre o futuro, instale habilitado: é mais fácil deixar parado do que reconstituir depois com contas já criadas.
Rodando o instalador e o que esperar na tela
Com sistema operacional suportado, atualizado, sem painel concorrente instalado e com as cinco linhas da folha preenchidas, a execução é direta.
O bloco abaixo é a forma como fazemos aqui, não está na página de personalização citada neste artigo. Confirme a URL de download vigente na documentação de instalação da cPanel antes de rodar em servidor de cliente:
# como root, num sistema limpo
cd /home
curl -o latest -L https://securedownloads.cpanel.net/latest
sh latest
Rode dentro de screen ou tmux. A instalação é longa e uma queda de SSH no meio não é algo que você queira descobrir sem sessão persistente.
O que aparece na tela é uma sequência de etapas com muita saída de gerenciador de pacotes: checagens de pré-requisito, download de componentes, compilação e configuração dos serviços, e por fim a mensagem de conclusão com a URL do WHM na porta de administração, onde você aplica a licença e roda o assistente inicial.
Sobre tempo: a documentação não publica um número fixo, e não existe um. Depende de CPU, disco, banda do datacenter e do perfil escolhido. O enquadramento honesto para o cliente é janela de horas, não de minutos, e a instalação em si é só o primeiro bloco dessa janela: depois vêm licença, hostname validado, firewall, certificados e as contas.
Quando o instalador para com erro
O instalador pode parar. Não trate isso como catástrofe nem conte com retomada mágica: o caminho é ler o log, tratar a causa e, se necessário, voltar a um sistema limpo antes de tentar de novo.
Qual log ler primeiro quando a instalação falha
# log principal da instalação
tail -n 100 /var/log/cpanel-install.log
# procurar a primeira ocorrência de erro, não a última
grep -n -i -m 5 -E "error|fatal|failed" /var/log/cpanel-install.log
A primeira ocorrência quase sempre explica as cinquenta seguintes. Ler o fim do log costuma mostrar só o efeito.
O caminho /var/log/cpanel-install.log também vem da nossa prática de operação, não da página citada neste artigo. Se ele não existir na sua release, liste ls -la /var/log/cpanel-install* e use o arquivo mais recente.
Causas que aparecem antes de qualquer coisa exótica
- hostname não qualificado ou não resolvendo;
- sistema operacional em versão não suportada pela release do cPanel;
- resquício de outro painel ou de um Apache/MySQL instalado pelo template do provedor;
- firewall do provedor bloqueando saída nas portas usadas pelo download;
- disco ou memória abaixo do mínimo exigido, especialmente em
/usr/local.
Se a causa for de ambiente, e o instalador já tiver alterado pacotes do sistema, a opção mais rápida e mais segura em VPS de cliente é reinstalar o sistema operacional pelo painel do provedor e recomeçar com a folha corrigida. Reinstalar pelo painel do provedor costuma ser bem mais rápido que tentar resgatar um sistema meio configurado, e deixa um ponto de partida que você conhece.
Padronizando a folha de decisões em agência
Transforme a folha num arquivo por cliente no repositório da agência, versionado junto do projeto:
cliente: exemplo (fictício)
hostname: srv04.suaagencia.com.br
PTR solicitado: sim (ticket do provedor #000)
banco: versao fixada no arquivo de instalacao
perfil de pacotes: definido antes da execucao
nameservers: externos (DNS no registrador) -> sem DNS autoritativo local
servidor de e-mail: habilitado (cliente usa caixas locais)
data da instalacao:
responsavel:
Três hábitos que economizam retrabalho:
- Revalide o arquivo de configuração de instalação a cada novo servidor contra a documentação oficial vigente. Chave copiada de um servidor de dois anos atrás pode ter mudado de nome ou de valor padrão.
- Nunca instale sobre template de provedor que já traz stack LAMP. Peça imagem mínima do sistema operacional.
- Registre o resultado de
hostname -fe da leitura do log no mesmo arquivo. Vira histórico quando o servidor der problema seis meses depois.
Como explicar ao cliente a janela de horas
Quando perguntarem por que a entrega leva horas:
"A instalação do painel compila e configura os serviços do servidor do zero, e cinco escolhas (nome do servidor, versão do banco de dados, conjunto de pacotes, DNS e e-mail) precisam estar certas antes de começar. Mudar a versão do banco depois significa reinstalar o servidor inteiro, e as outras custam refazer configuração com os sites já no ar. Por isso trabalhamos com janela de algumas horas e não de minutos: é o que evita uma segunda parada mais cara lá na frente."
Fonte consultada para os pontos de personalização descritos: documentação oficial da cPanel, Customize Your Installation (consultada em 7 de outubro de 2026). Este artigo é documental: não houve medição própria de tempo de instalação.
Referências
- Documentação oficial (cpanel) — Customize Your Installation. Consultado em 2026-10-07.