Passo a passo: restaurar backup cPanel com Docker no AlmaLinux

15 min de leitura  ·  Guia técnico

Restaurar backup cPanel em container Docker no AlmaLinux é a forma mais segura de validar arquivos de backup antes de aplicá-los em produção. Para executar o processo completo, siga estes passos:

1. Instale o Docker no servidor AlmaLinux host
2. Suba um container AlmaLinux com systemd habilitado e modo privilegiado
3. Instale o cPanel/WHM dentro do container via script oficial
4. Transfira o arquivo de backup .tar.gz para dentro do container
5. Valide a integridade do backup com tar -tzf
6. Restaure via WHM e verifique banco de dados, arquivos e configurações

Pré-requisitos para restaurar backup cPanel com Docker

• Servidor host com AlmaLinux 10+ (bare metal ou VPS com virtualização KVM)
• Docker Engine instalado — versão 26+ recomendada
• Acesso root ao servidor host via SSH
• Arquivo de backup cPanel no formato backup-MM-DD-YYYY_HH-mm-ss_usuario.tar.gz
• Mínimo de 4 GB de RAM disponível e espaço em disco igual ao dobro do tamanho do backup
• Porta 2087 (WHM) liberada no firewall do host apenas para o IP de administração
• Conexão estável — a instalação do cPanel baixa pacotes da internet e leva entre 20 e 40 minutos

Preparando o ambiente Docker no AlmaLinux para homologação cPanel

Antes de subir o container, confirme que o Docker está instalado e o daemon está rodando no AlmaLinux host. O processo de instalação do cPanel dentro de containers exige que o kernel do host suporte namespaces e cgroups v1 — ambos presentes no kernel padrão do AlmaLinux 10.

dnf install -y docker-ce docker-ce-cli containerd.io
systemctl enable --now docker
docker --version

Docker version 26.1.4, build 5650f9b

Com o Docker ativo, crie um diretório dedicado ao ambiente de homologação e copie o arquivo de backup para ele:

mkdir -p /opt/cpanel-homolog/backups
cp /caminho/para/backup-*.tar.gz /opt/cpanel-homolog/backups/

Antes de restaurar qualquer backup, valide a integridade do arquivo. Backups corrompidos causam falhas silenciosas na restauração do cPanel:

tar -tzf /opt/cpanel-homolog/backups/backup-*.tar.gz | head -30

O output deve listar diretórios como homedir/, mysql/, ssl/ e o arquivo cp/. Se o comando retornar erro de gzip ou unexpected EOF, o backup está corrompido e não deve ser restaurado.

Criando e configurando o container Docker com systemd para o cPanel

O cPanel requer systemd para gerenciar seus serviços internos. Containers Docker padrão não iniciam systemd, então é necessário configurar o container com parâmetros específicos que permitem ao processo init funcionar corretamente dentro do namespace.

Atenção: o flag --privileged concede acesso amplo ao kernel do host. Use este container exclusivamente em ambiente isolado de homologação, nunca exponha as portas publicamente.

docker run -d \
  --name cpanel-homolog \
  --privileged \
  --tmpfs /run \
  --tmpfs /run/lock \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -v /opt/cpanel-homolog/backups:/backups \
  -p 2087:2087 \
  -p 2083:2083 \
  -p 2082:2082 \
  -p 8080:80 \
  --hostname homolog.seudominio.com.br \
  almalinux:10 \
  /sbin/init

a3f7c891d42b1e05f9e8c3d12b456789abc01234def56789

Verifique se o container está rodando e acesse seu shell interativo:

docker ps --filter name=cpanel-homolog
docker exec -it cpanel-homolog bash

Dentro do container, prepare o sistema antes de instalar o cPanel:

dnf update -y
dnf install -y perl curl wget tar
hostnamectl set-hostname homolog.seudominio.com.br

Instalando o cPanel dentro do container AlmaLinux

Com o ambiente base configurado, execute o script oficial de instalação do cPanel. Ainda dentro do shell do container, rode:

cd /home
curl -o latest -L https://securedownloads.cpanel.net/latest
sh latest

O instalador exibirá progresso em tempo real. Aguarde a conclusão — normalmente entre 25 e 45 minutos dependendo da conexão e dos recursos do host. Ao final, você verá uma mensagem semelhante a:

cPanel & WHM 120.x.x has been successfully installed.
WHM is available at: https://homolog.seudominio.com.br:2087/

Após a instalação, acesse o WHM pelo navegador apontando para o IP do servidor host na porta 2087:

https://IP_DO_HOST:2087

Faça login com o usuário root e a senha do root do container. Se precisar redefinir a senha do root dentro do container, consulte o artigo Como trocar a senha do usuário root do servidor VPS ou Dedicado.

Restaurando o backup cPanel via WHM no ambiente de homologação

Com o WHM acessível, a restauração do backup de homologação segue o fluxo nativo do cPanel, garantindo que todos os componentes — banco de dados MySQL, arquivos do diretório home, configurações de DNS e certificados SSL — sejam recriados exatamente como na origem.

No WHM, navegue até Backup > Restore a Full Backup/cpmove File. O arquivo de backup já está disponível em /backups/ dentro do container, pois mapeamos esse volume ao criar o container.

Como alternativa via linha de comando, restaure diretamente dentro do container usando o script /scripts/restorepkg:

docker exec -it cpanel-homolog bash
/scripts/restorepkg /backups/backup-*.tar.gz

Restoring account: usuario
  Extracting backup archive...done
  Restoring MySQL databases...done
  Restoring DNS zones...done
  Restoring SSL certificates...done
Restoration complete.

Após a restauração, verifique se a conta foi criada corretamente:

whmapi1 listaccts | grep -A5 "user: usuario"

Validando o site restaurado no ambiente Docker de homologação

Com o backup restaurado, acesse o cPanel da conta pelo porta 2083 e verifique arquivos, banco de dados e e-mails. Para visualizar o site no navegador sem alterar DNS real, edite o arquivo hosts na sua máquina local:

No Linux ou macOS (máquina local, não o servidor):

echo "IP_DO_HOST seudominio.com.br www.seudominio.com.br" | sudo tee -a /etc/hosts

No Windows, adicione a linha equivalente em C:\Windows\System32\drivers\etc\hosts usando um editor com permissão de administrador.

Acesse o banco de dados MySQL restaurado para confirmar que as tabelas estão íntegras. Para conexões remotas ao MySQL do cPanel, siga o procedimento descrito em Conectando remotamente ao MySQL - cPanel.

docker exec -it cpanel-homolog mysql -u root -p -e "SHOW DATABASES;"

Você deve ver os bancos de dados restaurados listados, com prefixo no formato usuario_nomebanco. Execute uma verificação rápida nas tabelas principais:

docker exec -it cpanel-homolog mysql -u root -p -e \
  "SELECT table_schema, COUNT(*) as tabelas FROM information_schema.tables \
   WHERE table_schema LIKE 'usuario_%' GROUP BY table_schema;"

Destruindo o container após validação e boas práticas de ciclo de vida

Uma das principais vantagens de usar Docker para homologação de backups cPanel é a descartabilidade do ambiente. Após confirmar que o backup está íntegro e funcional, destrua o container para liberar recursos:

docker stop cpanel-homolog
docker rm cpanel-homolog

Para criar um novo ciclo de teste com outro backup, apenas recrie o container seguindo o mesmo processo da seção anterior. Considere criar um script shell para automatizar a criação do ambiente:

#!/bin/bash
# Script de homologação de backup cPanel
BACKUP_FILE="$1"
CONTAINER_NAME="cpanel-homolog-$(date +%Y%m%d%H%M)"

if [ -z "$BACKUP_FILE" ]; then
  echo "Uso: $0 /caminho/para/backup.tar.gz"
  exit 1
fi

echo "Verificando integridade do backup..."
tar -tzf "$BACKUP_FILE" | grep -E "^(homedir|mysql|ssl)/" | head -5

echo "Criando container de homologação..."
docker run -d \
  --name "$CONTAINER_NAME" \
  --privileged \
  --tmpfs /run \
  --tmpfs /run/lock \
  -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
  -v "$(dirname $BACKUP_FILE)":/backups \
  -p 2087:2087 \
  -p 2083:2083 \
  --hostname homolog.local \
  almalinux:10 \
  /sbin/init

echo "Container criado: $CONTAINER_NAME"
echo "Acesse WHM em: https://$(hostname -I | awk '{print $1}'):2087"

Salve o script como /usr/local/bin/cpanel-homolog.sh, torne-o executável com chmod +x e use como cpanel-homolog.sh /backups/backup-usuario.tar.gz.

Problemas comuns e como resolver

Sintoma: container para imediatamente após iniciar com /sbin/init

Causa: o kernel do host não tem suporte a cgroups v1 ou a versão do AlmaLinux no container é incompatível com a imagem baixada.
Solução: confirme que o kernel do host é versão 4.15+ com uname -r. Adicione o parâmetro systemd.unified_cgroup_hierarchy=0 ao GRUB se o host usar cgroups v2 exclusivamente. Verifique os logs do container com docker logs cpanel-homolog para identificar o erro específico.

Sintoma: instalação do cPanel falha com erro "This system is not supported"

Causa: o cPanel verifica o hostname e a versão do sistema operacional. Se o hostname não resolv para um FQDN válido ou o container reportar uma versão incorreta do AlmaLinux, a instalação é abortada.
Solução: dentro do container, execute hostnamectl set-hostname homolog.seudominio.com.br antes de rodar o instalador. Confirme também com cat /etc/almalinux-release que a versão é reconhecida pelo cPanel. Versões do AlmaLinux 10+ são suportadas pelo cPanel a partir da versão 120.

Sintoma: /scripts/restorepkg falha com "Unable to extract archive"

Causa: o arquivo de backup está corrompido, incompleto ou foi gerado com uma versão do cPanel muito antiga que usa formato de compressão diferente.
Solução: execute tar -tzf backup-*.tar.gz 2>&1 | tail -5 para identificar erros específicos. Se o arquivo estiver truncado, gere um novo backup a partir do cPanel de origem. Para backups antigos em formato .tar.bz2, use /scripts/restorepkg --allow-reseller backup.tar.bz2.

Sintoma: porta 2087 inacessível pelo navegador após subir o container

Causa: firewall do servidor host (firewalld ou iptables) está bloqueando a porta 2087, ou o cPanel ainda não terminou de iniciar todos os serviços após a instalação.
Solução: no host, execute firewall-cmd --add-port=2087/tcp --zone=public --permanent && firewall-cmd --reload para liberar a porta. Dentro do container, verifique se o serviço cpsrvd está ativo com systemctl status cpsrvd. Aguarde até 2 minutos após a instalação para todos os serviços iniciarem.

Sintoma: banco de dados MySQL não está presente após restauração

Causa: o processo de restauração encontrou uma incompatibilidade de versão do MySQL entre o backup de origem e o MySQL instalado no container, ou o diretório mysql/ estava ausente no backup.
Solução: confirme a presença do diretório mysql/ no backup com tar -tzf backup-*.tar.gz | grep "^mysql/". Se presente, execute a restauração manualmente com /scripts/mysqlrestore --all-databases dentro do container. Verifique também o log em /var/cpanel/logs/.

Perguntas frequentes sobre restaurar backup cPanel com Docker

É possível restaurar um backup cPanel dentro de um container Docker?

Sim. Você pode criar um container Docker com AlmaLinux e instalar o cPanel/WHM dentro dele para fins de teste. O processo envolve subir o container com systemd habilitado, instalar o cPanel via script oficial e então usar o WHM para restaurar o arquivo de backup .tar.gz gerado pelo cPanel de produção. O resultado é um ambiente funcional e completamente isolado do servidor real.

Qual a diferença entre restaurar backup cPanel em produção e em ambiente de homologação Docker?

Em produção, a restauração sobrescreve dados reais e pode causar downtime ou perda de configurações. Em um container Docker de homologação, o ambiente é isolado e descartável — qualquer erro pode ser revertido simplesmente destruindo e recriando o container, sem impacto algum no servidor de produção. Essa abordagem é ideal para validar backups antes de executar migrações ou atualizações críticas.

O cPanel funciona corretamente dentro de um container Docker no AlmaLinux?

O cPanel foi projetado para servidores bare metal ou VPS, mas funciona em containers Docker quando o container é configurado com systemd e privilégios adequados (--privileged ou capabilities específicas). Para testes de homologação e validação de backups, essa abordagem é suficiente e amplamente utilizada por administradores de sistemas. Não é recomendado para ambientes de produção, apenas para testes.

Como verificar se um backup cPanel está íntegro antes de restaurar em produção?

Execute o comando tar -tzf backup-*.tar.gz para listar o conteúdo do arquivo sem extrair. Verifique se os diretórios homedir, mysql e ssl estão presentes. Em seguida, restaure em um ambiente Docker de homologação e acesse o site via /etc/hosts para confirmar que banco de dados, arquivos e configurações estão funcionando corretamente antes de tocar no servidor de produção.

Quanto tempo leva para restaurar um backup cPanel em Docker para homologação?

O tempo varia conforme o tamanho do backup e os recursos do servidor host. A instalação do cPanel no container leva entre 20 e 40 minutos. A restauração do backup em si pode levar de 5 minutos (backups pequenos) a mais de 1 hora para backups acima de 10 GB. Recomenda-se usar um servidor com SSD e pelo menos 4 GB de RAM disponível para o processo completo de homologação.

Conclusão

• Valide sempre antes de produção: use tar -tzf para checar integridade e o ambiente Docker para testar a restauração completa — banco de dados, arquivos e DNS — sem risco ao servidor real.
• Automatize com script: o script de homologação apresentado neste artigo pode ser adaptado para rodar em um pipeline de CI/CD ou como verificação periódica agendada via cron, garantindo que backups recentes são sempre válidos.
• Destrua o container após o teste: containers de homologação com cPanel devem ser efêmeros. Após validar, execute docker stop e docker rm para liberar recursos; nunca mantenha um cPanel de homologação exposto permanentemente.

Precisa de um VPS para rodar Docker e homologar seus backups cPanel?

Um VPS com KVM, SSD NVMe e AlmaLinux pré-instalado é o ambiente ideal para executar este fluxo de homologação com estabilidade e performance. A AviraHost oferece planos de VPS Linux com recursos dedicados e suporte técnico especializado para quem gerencia ambientes cPanel.

Ver planos de VPS Linux na AviraHost

Leia também

• Guia: backup do WhatsApp Business no PC com Docker
• Comparativo: Gerenciadores de Pacotes no cPanel — onde fica, como funciona e como usar
• Como fazer backup do WhatsApp no PC para Linux sem cPanel