FAQ

Perguntas frequentes

O que costuma ser perguntado antes e depois de instalar.

Geral

Meus clientes vão ter acesso ao Docker?

Não. O cliente só escreve um arquivo na pasta dele. Ele não tem o comando docker, não entra em grupo nenhum e não roda nada por conta própria: quem publica e sobe é você, pelo WHM. Dar acesso ao Docker a um usuário equivale a dar root, e o dPanel existe justamente para evitar isso.

Funciona em qualquer servidor cPanel?

Nos da família RHEL 8 e 9: CloudLinux, AlmaLinux, Rocky, CentOS e RHEL. Foi desenvolvido e validado em CloudLinux 9 com cPanel 11.134. O instalador confere o sistema e recusa o que não reconhece, em vez de tentar e quebrar.

Preciso instalar o Docker antes?

Não. O instalador adiciona o repositório oficial, instala o Docker CE com o Compose v2 e configura o daemon. Se você já tiver Docker e preferir gerenciar por conta própria, use bash install.sh --no-docker.

O plugin interfere nos sites que já estão no servidor?

Não. As regras do nginx são criadas só para os domínios que você configurar, e cada regra casa pelo host exato; o resto do site e os outros domínios seguem intocados. Antes de recarregar, a configuração passa por nginx -t, e se algo ficar inválido o estado anterior é restaurado automaticamente. O arquivo que o cPanel gera para a conta nunca é editado: o dPanel escreve no diretório de customização do próprio ea-nginx, que sobrevive a qualquer regeneração.

Posso desinstalar sem perder o que está no ar?

Pode. O uninstall.sh remove o plugin mas preserva containers, stacks, regras do nginx e a configuração do Docker: os sites publicados continuam no ar. Só o --purge apaga de verdade, e nesse caso ele derruba os stacks e remove as regras juntas, na ordem certa, para nenhum domínio ficar devolvendo 502.

Segurança

Como sei que o compose do cliente não vai comprometer o servidor?

Três camadas. Primeiro, o arquivo é interpretado por um processo sem privilégio e com teto de recursos: YAML hostil não é processado como root. Segundo, a validação usa lista de permissões: o que não está previsto é recusado, então uma chave nova do Docker nunca passa por engano. Terceiro, o que roda é a cópia normalizada pelo dPanel, nunca o arquivo do cliente.

E antes de publicar, você vê o arquivo dele lado a lado com o que o root vai executar.

Um container consegue chegar no WHM ou no SSH?

Não. Só a porta 3306 do host fica acessível. SSH, WHM, cPanel, Exim, o Apache do servidor, as redes privadas e o metadata da instância são recusados. Foi testado em produção e revalidado depois de um csf -r, que apaga todas as regras do iptables.

Detalhe importante: o tráfego de container para o próprio host passa por INPUT, não por FORWARD. Receitas que só mexem em DOCKER-USER não bloqueiam nada disso.

E se alguém reiniciar o CSF?

O CSF reconstrói o iptables e apaga as cadeias do Docker junto. O dPanel instala um hook que roda logo depois: reinicia o Docker (com live-restore, os containers não caem) e repõe as regras. Um timer confere a cada 60 segundos, cobrindo casos que o hook não pega. E o painel se recusa a subir um stack se o isolamento não estiver ativo.

Um cliente consegue ver ou atacar o container de outro?

Cada conta tem sua própria rede Docker, e o dPanel substitui as redes declaradas no arquivo por ela. Redes externas são recusadas. As portas publicadas ficam em 127.0.0.1 e são inalcançáveis a partir de containers.

A exceção assumida é o MySQL: como 3306 é alcançável, um container pode tentar autenticar contra o banco de outra conta. A barreira aí são as permissões e as senhas.

Posso permitir privileged para um cliente específico?

Pelo painel, não, e isso é proposital. privileged, cap_add e namespaces do host equivalem a root no servidor; liberar para um cliente compromete todos os outros. Se um caso realmente exigir, o certo é uma máquina separada.

Uso no dia a dia

Por que não posso escolher a porta do host?

Porque a porta é detalhe interno: quem expõe para a internet é o nginx, pelo redirecionamento. Deixar o dPanel escolher evita conflito entre contas, garante que a publicação seja só em 127.0.0.1 e mantém a faixa organizada. Escreva apenas a porta interna do container.

Se eu republicar o stack, a porta muda e quebra o redirecionamento?

Não. As portas são estáveis: cada serviço reivindica a porta que já usava. Isso foi um bug real durante o desenvolvimento e está corrigido. Se ainda assim uma porta deixar de existir (por exemplo, se o serviço for removido do arquivo), o painel avisa qual regra ficou órfã.

WebSocket funciona?

Funciona, sem configuração extra. O upgrade é tratado antes do tráfego HTTP comum, tanto na raiz do domínio quanto em subcaminho. A demo mantém uma conexão aberta recebendo mensagens do container em tempo real.

A aplicação recebe o IP real do visitante?

Sim, em X-Forwarded-For e X-Real-IP, junto com X-Forwarded-Proto e X-Forwarded-Port. O cabeçalho Host chega com o domínio real. Configure seu framework para confiar nesses cabeçalhos vindos do proxy local.

O AutoSSL continua emitindo certificado?

Continua. O caminho /.well-known nunca é encaminhado ao container: volta sempre para o site do cliente. Foi o primeiro cuidado tomado no gerador de regras, porque a quebra só apareceria meses depois, na hora da renovação. No nginx isso exige atenção extra: como location por regex vence prefixo simples, apontar o domínio inteiro sem uma lista de exclusão sequestraria o /.well-known sem avisar.

Posso publicar em dominio.com/app em vez da raiz?

Pode, é o campo Caminho da regra. O prefixo é removido antes de chegar no container: um pedido a /app/status chega como /status. Se a aplicação gerar URLs absolutas, configure nela o prefixo público.

Quantos containers cabem no meu servidor?

Depende da memória. O padrão é 512 MB por serviço, com teto global de 2,2 GB para todos os containers juntos: num servidor de 4 GB, algo como quatro serviços confortáveis. Ajuste os tetos na configuração e no dpanel.slice conforme a máquina.

Como fica o backup?

O backup do cPanel já leva o /home da conta, e é ali que fica tudo que importa: o docker-compose.yaml, os arquivos da aplicação, os bind mounts e também os volumes nomeados — o dPanel materializa cada um como pasta em /home/{conta}/docker/volumes/{nome} justamente para não deixar dado de cliente fora do backup. Só as imagens ficam de fora, e essas são baixadas de novo.

Uma ressalva: a quota do cPanel é contada por dono do arquivo. Se o serviço não define user:, o container grava como root; o backup leva os arquivos do mesmo jeito, mas eles não aparecem no consumo da conta. O painel avisa quando é o caso.

O cliente consegue ver os logs do container dele?

Nesta versão, não: o painel é só para root. O cliente vê o que a aplicação dele gravar dentro do home. Uma área para o usuário no cPanel é um passo natural, mas exigiria repensar cada permissão: o modelo atual assume um único operador confiável.

Problemas

O plugin não abre e o WHM fala em "unregistered applications"

O registro no WHM não foi concluído. Rode bash install.sh --verify: ele diz se o AppConfig está registrado. Se não estiver, rode o instalador de novo.

Não ative permit_unregistered_apps_as_root: isso libera qualquer CGI não registrado no servidor inteiro, o que é bem pior do que o problema.

O domínio devolve 502

O nginx está encaminhando para uma porta que não responde. Veja no painel se o container está de pé; se estiver, confira se a regra aponta para o serviço certo. Para testar direto, sem passar pelo nginx: curl -s http://127.0.0.1:PORTA/ no servidor. O motivo exato fica em /var/log/nginx/error.log. Um 502 momentâneo logo após reiniciar o container é esperado.

"o caminho mudou desde a validação"

É a proteção contra troca de diretório por link simbólico. O dPanel guarda a identidade do arquivo montado e reconfere antes de cada subida; se não bater, recusa e registra um alerta.

Normalmente é inocente: a pasta foi apagada e recriada, ou restaurada de um backup. Basta republicar o stack. Se você não fez nada disso, olhe a aba Auditoria antes de republicar.

Meu compose é recusado e eu não concordo com o motivo

A mensagem diz a chave e a razão. A maioria dos casos tem alternativa: em vez de network_mode: host, publique a porta normalmente; em vez de montar um caminho de fora do home, copie o arquivo para dentro da conta; em vez de cap_add, verifique se a aplicação realmente precisa daquilo.

O que é ajustável por servidor (registries permitidos, tetos de recurso, permitir ou não build) está na configuração. O que envolve privileged e namespaces do host não é ajustável de propósito.

O disco está enchendo

Imagens Docker ocupam bastante. A aba Saúde mostra o consumo e traz botões para limpar imagens antigas e o cache de build — nenhum dos dois toca em dado de cliente, porque dado de cliente não fica em /var/lib/docker: volume nomeado é materializado como pasta em /home/{conta}/docker/volumes/. O deploy também é bloqueado quando o disco fica abaixo do mínimo configurado.

Não achou sua dúvida? A documentação cobre as regras em detalhe, e o log em /var/cpanel/dpanel/logs/actions.log registra cada ação com o motivo de cada recusa.