Antes de começar

• O dPanel instalado - guia de instalação.
• Uma conta cPanel de teste. Neste exemplo ela se chama minhaconta.
• Um domínio dessa conta para publicar depois.

1. Criar o compose na pasta da conta

O dPanel procura o arquivo em /home/{conta}/docker/. Aceita compose.yaml, compose.yml, docker-compose.yaml ou docker-compose.yml, nessa ordem de preferência.

O cliente pode criar pelo Gerenciador de Arquivos do cPanel. Pelo terminal:

mkdir -p /home/minhaconta/docker/site
cat > /home/minhaconta/docker/docker-compose.yaml <<'YAML'
services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    restart: unless-stopped
YAML

echo '<h1>Funcionou</h1>' > /home/minhaconta/docker/site/index.html
chown -R minhaconta:minhaconta /home/minhaconta/docker

2. Publicar no painel

Abra WHM → Plugins → dPanel Docker e clique em Adicionar stack. Escolha a conta na lista: o painel já indica quais têm um compose esperando.

A tela de análise mostra duas abas:

• Arquivo do cliente: o conteúdo original, como ele escreveu.
• O que o root vai executar: a versão normalizada, com caminhos resolvidos, portas atribuídas, limites e proteções injetados.

Compare as duas antes de publicar. É aí que você vê exatamente o que vai rodar como root. Erros aparecem em vermelho e impedem a publicação; avisos em amarelo são recomendações.

Clique em Publicar. O dPanel grava a cópia normalizada em /var/cpanel/dpanel/stacks/minhaconta/, pertencente ao root. A partir daí, o arquivo do cliente não é mais usado.

3. Subir os containers

Clique em Subir containers. O download da imagem acontece em segundo plano e o log aparece ao vivo na tela; a página não trava esperando.

Antes de subir, o dPanel confere três coisas: se os caminhos montados continuam apontando para o mesmo lugar de quando foram validados, se as regras de isolamento estão ativas, e se há disco livre. Qualquer uma falhando, o deploy não acontece.

Terminado, o container aparece no Painel com consumo de CPU e memória ao vivo.

4. Apontar o domínio

Na linha do stack, clique em Redirects. Cada regra tem três campos:

Clique em Aplicar no nginx. O dPanel gera os arquivos, roda nginx -t e recarrega. Se a configuração ficar inválida por qualquer motivo, ele restaura o estado anterior automaticamente e avisa. Nada entra em vigor quebrado, e o reload do nginx é gracioso: nenhuma conexão em andamento cai.

Conferir

Abra o domínio no navegador, e abra de verdade, porque curl não valida o handshake de WebSocket nem reproduz URL relativa sob subcaminho. Pelo terminal, lembrando que o nginx escolhe o site pelo cabeçalho Host, então apontar para 127.0.0.1 sem --resolve cai no site padrão e engana:

curl -sk --resolve loja.com.br:443:SEU_IP https://loja.com.br/

Para ver o que o container está registrando:

No painel, botão Log na linha do container. Há seletor de quantidade de linhas e atualização automática a cada 3 segundos.

Usar o banco de dados

Dentro do container, o MySQL do servidor responde em host.docker.internal:3306. O dPanel injeta esse host automaticamente e, no primeiro deploy, libera o acesso remoto da conta para as faixas de rede do Docker.

Usuário, senha e nome do banco são os mesmos que aparecem no cPanel da conta. No compose:

services:
  app:
    image: node:22-alpine
    environment:
      DB_HOST: host.docker.internal
      DB_PORT: "3306"
      DB_NAME: minhaconta_loja
      DB_USER: minhaconta_app

Instalar a demo

Se quiser ver tudo funcionando antes de montar sua própria aplicação, o dPanel acompanha uma demo que também serve de autoteste da instalação:

bash demo/install-demo.sh minhaconta

Ela sobe um container que mede, de dentro dele mesmo: os limites que o kernel aplicou, os cabeçalhos que chegaram do visitante, o MySQL respondendo, as portas do servidor sendo recusadas, e um WebSocket ao vivo. Depois é só criar o redirecionamento apontando para demo:8080.

Ver a demo ao vivo →

Quando algo dá errado