O gerenciamento de infraestrutura moderna exige agilidade sem abrir mão do controle. Para desenvolvedores e equipes de DevOps que buscam uma alternativa robusta ao Docker Compose manual, o Easypanel surge como uma solução PaaS (Platform as a Service) auto-hospedada extremamente eficiente. Ele automatiza o deploy de aplicações, gerencia variáveis de ambiente e, crucialmente, lida com certificados SSL e roteamento de tráfego.
Muitos administradores iniciam o uso do Easypanel expondo suas aplicações na porta padrão (geralmente 8080 ou 3000), mas a verdadeira maturidade de uma infraestrutura vem quando configuramos domínios personalizados. Isso permite que você utilize subdomínios profissionais, como app.seudominio.com, garantindo segurança via HTTPS e organização clara dos serviços.
Neste tutorial técnico, detalhamos o processo completo de instalação do Easypanel em um servidor Linux (Ubuntu/Debian) e a configuração definitiva de domínios personalizados para suas aplicações. O foco é garantir que o roteamento funcione corretamente desde o primeiro deploy.
Pré-requisitos e Preparação do Servidor
Antes de instalar qualquer software, é fundamental preparar o ambiente operacional. O Easypanel roda como um container Docker e requer acesso à raiz do sistema para gerenciar outros containers. Recomendamos o uso de um servidor Linux limpo, preferencialmente Ubuntu 20.04 ou 22.04 LTS.
O primeiro passo é garantir que o Docker esteja instalado e atualizado. Caso ainda não possua o Docker em seu ambiente, utilize os comandos abaixo para instalar a versão estável mais recente:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USERApós a instalação, verifique se o serviço está ativo:
systemctl status dockerAlém do Docker, certifique-se de que o firewall do servidor (UFW ou iptables) permita o tráfego nas portas 80 (HTTP) e 443 (HTTPS). O Easypanel utiliza o Nginx como proxy reverso para rotear as requisições. Se você estiver usando UFW, abra essas portas com:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcpInstalação do Easypanel
A instalação do Easypanel é feita via script oficial que baixa a imagem Docker e inicia o container principal. Execute o comando abaixo no terminal do seu servidor:
curl -sSL https://get.easypanel.io | shO script realizará o download da imagem easypanel/easypanel:latest e iniciará o container. Durante esse processo, você verá mensagens de log indicando que o serviço está sendo configurado. Aguarde até que a instalação seja concluída com sucesso.
Ao final da instalação, o script exibirá um link temporário e uma senha inicial para acesso ao painel administrativo. Copie essas credenciais, pois elas serão necessárias para o primeiro login. Acesse o link fornecido (geralmente http://IP_DO_SEU_SERVIDOR:8080) em seu navegador.
No primeiro acesso, você será solicitado a alterar a senha padrão e configurar o usuário administrador. Após definir suas credenciais de segurança, você terá acesso ao dashboard principal do Easypanel.
Configuração do Domínio no DNS
Antes de configurar o domínio dentro do Easypanel, é essencial resolver as questões de DNS. O Easypanel funciona como um proxy reverso; ele precisa saber para qual IP enviar o tráfego que chega em seu domínio.
Você deve criar um registro A no painel de controle do seu registrador de domínios (como Cloudflare, GoDaddy, Namecheap ou AWS Route53) apontando para o endereço IP público do seu servidor onde o Easypanel está instalado.
Por exemplo, se você deseja usar um subdomínio específico para sua aplicação, como app.meudominio.com, crie um registro A:
- Tipo: A
- Nome: app (ou o nome do subdomínio desejado)
- Valor/Target: IP_PUBLICO_DO_SEU_SERVIDOR
- TTL: Automático ou 3600
Se você deseja apontar o domínio principal (apex domain) como meudominio.com, verifique se seu provedor de DNS suporta registros A para o apex. Caso não suporte, utilize um serviço como Cloudflare que ofereça a função "Proxy" ou CNAME Flattening.
Para cenários de múltiplas aplicações, é altamente recomendável configurar um coringa (wildcard). Isso permite que qualquer subdomínio criado no futuro seja automaticamente roteado para o servidor do Easypanel. Para isso, crie um registro CNAME:
- Tipo: CNAME
- Nome: *
- Valor/Target: meudominio.com (ou o domínio principal)
Com as entradas de DNS propagadas, seu servidor estará pronto para receber requisições HTTP direcionadas aos seus domínios.
Adicionando um Domínio Personalizado no Easypanel
Agora que a infraestrutura de rede está pronta, vamos configurar o domínio dentro da interface do Easypanel. Esta etapa é crítica, pois instrui o proxy Nginx gerado pela plataforma como lidar com os headers Host.
- Faça login no dashboard do Easypanel.
- No menu lateral esquerdo, clique em Settings (Configurações).
- Na aba geral, localize a seção Domains ou Default Domain.
- Clique no botão Add Domain ou edite o domínio padrão.
Aqui, você deve inserir o nome do domínio que deseja utilizar. Por exemplo: app.meudominio.com. O Easypanel validará a entrada e perguntará se deseja habilitar automaticamente o SSL (HTTPS) para esse domínio.
Importante: Deixe a opção de SSL habilitada. O Easypanel utiliza o Let's Encrypt para emitir certificados gratuitos. No entanto, para que o desafio do Let's Encrypt seja aprovado, o DNS deve estar corretamente apontado e as portas 80/443 abertas no firewall, conforme descrito na seção de pré-requisitos.
Clique em Save. O sistema pode solicitar uma confirmação. Ao salvar, o Easypanel atualizará sua configuração interna de roteamento.
Vinculando Aplicações ao Domínio
Apenas adicionar o domínio nas configurações globais não significa que suas aplicações serão acessíveis por ele automaticamente. Você precisa vincular cada aplicação individualmente ao domínio configurado.
Criando uma Nova Aplicação com Domínio
Se você está criando uma aplicação do zero:
- No dashboard principal, clique em Create App.
- Preencha os detalhes básicos: nome da aplicação (ex:
meu-app-node). - Escolha o método de deploy. O Easypanel suporta Docker Images públicas, repositórios Git (GitHub/GitLab) ou uploads diretos.
No campo Domains ou Hostnames, insira o subdomínio específico que deseja usar para essa aplicação, como app.meudominio.com. Se você configurou um wildcard no DNS anterior, pode simplesmente digitar o nome do subdomínio.
Defina a porta interna da sua aplicação. Por exemplo, se seu app Node.js roda na porta 3000, defina 3000 como a porta de exposição. O Easypanel fará o mapeamento automático entre o domínio externo e essa porta interna.
Finalize a criação clicando em Create. Aguarde o processo de build e deploy. Ao concluir, acesse https://app.meudominio.com. Você deverá ver sua aplicação rodando com o cadeado de segurança ativo.
Configurando uma Aplicação Existente
Para alterar o domínio de uma aplicação que já está em produção:
- Navegue até a lista de aplicações e clique no nome da app desejada.
- Vá para a aba Settings (Configurações) daquela aplicação específica.
- Localize o campo Domains.
- Altere o domínio antigo pelo novo domínio personalizado ou adicione um novo subdomínio à lista.
- Clique em Save.
O Easypanel reiniciará os containers relacionados para aplicar as novas regras de roteamento. Isso geralmente leva alguns segundos. Verifique se o acesso via novo domínio está funcional.
Gerenciamento de SSL e Certificados
Uma das maiores dores de cabeça em auto-hospedagem é a renovação de certificados SSL. O Easypanel automatiza isso através do certbot integrado ao Nginx.
No entanto, problemas comuns podem impedir a emissão do certificado. Se você tentar acessar o domínio e receber um erro de conexão ou certificado inválido, verifique os seguintes pontos:
- Propagação DNS: Use ferramentas como
digounslookuppara garantir que o domínio resolve para o IP correto. Exemplo:dig app.meudominio.com +short. - Firewall: Certifique-se de que a porta 80 está aberta. O Let's Encrypt precisa acessar um endpoint específico (
/.well-known/acme-challenge/) no seu servidor para validar a posse do domínio. - Conflitos de Porta: Verifique se não há outro serviço (como um Apache ou Nginx nativo) rodando na porta 80 ou 443. O Easypanel precisa de acesso exclusivo a essas portas para gerenciar o proxy reverso.
Você pode verificar o status dos certificados na aba Certificates dentro das configurações do Easypanel, se disponível na sua versão, ou simplesmente observar os logs do container do Nginx se houver falhas recorrentes.
Boas Práticas e Dicas de Produção
Para garantir a estabilidade e segurança de suas aplicações com domínios personalizados no Easypanel, considere as seguintes práticas:
1. Use Variáveis de Ambiente para Diferentes Ambientes
Sempre que possível, defina variáveis de ambiente específicas para produção. No Easypanel, você pode configurar variáveis na aba Variables da aplicação. Isso evita a exposição de chaves de API ou senhas de banco de dados diretamente no código.
2. Limites de Recursos
Defina limites de CPU e memória para cada aplicação. Isso impede que uma única app consuma todos os recursos do servidor, derrubando outras aplicações críticas. Na aba Resources, defina valores como 0.5 CPUs e 512MB de RAM.
3. Backups do Banco de Dados
Se suas aplicações utilizam bancos de dados (PostgreSQL, MySQL, MongoDB), utilize os volumes persistentes oferecidos pelo Easypanel ou configure backups externos. O Easypanel gerencia a infraestrutura, mas a integridade dos dados é responsabilidade do administrador.
4. Monitoramento
Ative as opções de logging no Easypanel. Em caso de erro 502 ou 504, os logs da aplicação e do proxy serão essenciais para diagnóstico. Acesse a aba Logs diretamente no dashboard.
Troubleshooting Comum
Se ao acessar seu domínio personalizado você receber uma página de erro padrão do Nginx ou um "Connection Refused", verifique os seguintes cenários:
Cenário A: Erro 502 Bad Gateway
Isso geralmente indica que o Easypanel conseguiu conectar ao Nginx, mas não conseguiu conectar ao container da aplicação. Verifique se a porta interna configurada na aplicação corresponde à porta em que seu código está ouvindo. Se seu app espera conexões apenas no localhost (127.0.0.1), certifique-se de que o Docker está mapeando corretamente.
Cenário B: Erro 404 Not Found
O roteamento está funcionando, mas o caminho solicitado não existe na sua aplicação. Verifique se o Base Path ou Route está configurado corretamente nas configurações da aplicação, caso seu app utilize rotas específicas.
Cenário C: Certificado SSL Não Atualiza
Se o domínio muda de IP ou se há bloqueios no firewall, o agendador do Let's Encrypt falhará. Verifique os logs do sistema (journalctl -u easypanel) para mensagens de erro relacionadas ao certbot. Remover e re-adicionar o domínio às vezes força uma nova tentativa de emissão.
Conclusão
Configurar domínios personalizados no Easypanel transforma um servidor Docker básico em uma plataforma de desenvolvimento profissional e segura. Ao seguir os passos de preparação do DNS, instalação limpa e vinculação correta das aplicações, você elimina a complexidade manual de configurar Nginx e SSL.
O Easypanel oferece uma camada de abstração poderosa para sysadmins e devs, permitindo que o foco permaneça no código e não na infraestrutura subjacente. Com domínios personalizados corretamente configurados, suas aplicações estão prontas para receber tráfego real com a confiança que um HTTPS válido proporciona.
Agora que você domina a configuração básica, explore as funcionalidades avançadas do Easypanel, como deploy via Git push, variáveis de ambiente sensíveis e integração com bancos de dados gerenciados, para maximizar o potencial da sua infraestrutura em nuvem.