Como instalar o Dokku em um VPS

Pré-requisitos

• VPS com Ubuntu 22.04 ou 24.04 e endereço IP público
• Pelo menos 1 GB de RAM (adicione 1 GB de swap para VMs menores)
• Acesso SSH como root ao VPS
• Um domínio com registro A curinga apontando para o IP do VPS (por exemplo, *.apps.example.com)
• Git e um par de chaves SSH na máquina local

O Dokku não é um contêiner Docker. É uma PaaS gerenciada pelo apt que instala o Docker Engine como dependência. Comece com um servidor limpo: não instale previamente o Docker, nginx ou ferramentas de contêiner. O próprio Dokku gerencia todos eles.

Etapa 1: Conectar ao servidor

Faça login e atualize os pacotes do sistema:

ssh root@SERVER_IP
apt update && apt upgrade -y
hostnamectl set-hostname dokku.example.com

Verifique se o nome de host resolve corretamente e se as portas 80 e 443 estão livres:

ss -ltnp

Reinicie o servidor se o kernel tiver sido atualizado. Depois da reinicialização, conecte-se novamente e continue.

Etapa 2: Instalar o Dokku pelo script de inicialização

Baixe o script oficial de inicialização para uma versão específica e execute-o. Não instale o Docker manualmente, o script cuida disso.

wget -NP . https://dokku.com/install/v0.38.25/bootstrap.sh
sudo DOKKU_TAG=v0.38.25 bash bootstrap.sh

Durante a instalação, o script exibe uma tela azul de configuração debconf. Ela solicita:

1. Domínio global: informe apps.example.com (ou o domínio que você configurou)
2. Chave SSH: deixe em branco. Você cadastrará sua chave na próxima etapa.

Use a tecla Tab para alternar entre os campos e Enter para confirmar. Se a solicitação não aparecer, execute sudo dpkg-reconfigure dokku depois.

Quando o script terminar, verifique se tudo está funcionando:

dokku version
docker version
sudo systemctl status dokku

O Dokku inclui sua própria instância do nginx. A partir de agora, o Dokku gerencia as portas 80 e 443.

Etapa 3: Cadastrar a chave SSH e definir o domínio

Esta é a etapa mais importante. Sem uma chave SSH cadastrada, o Dokku rejeita todas as tentativas de git push.

cat ~/.ssh/authorized_keys | sudo dokku ssh-keys:add admin

Isso cadastra a chave pública das chaves autorizadas do usuário root (que contém a chave usada para conectar por SSH). Substitua admin pelo rótulo que preferir.

Defina o domínio global para que cada aplicação receba um nome de host automaticamente:

sudo dokku domains:set-global apps.example.com

Confirme que a chave e o domínio foram cadastrados:

dokku ssh-keys:list
dokku domains:report --global

Etapa 4: Implantar sua primeira aplicação

Crie uma aplicação no servidor:

dokku apps:create hello

Na sua máquina local, adicione o remoto do Dokku e envie o código:

git remote add dokku [email protected]:hello
git push dokku main

O Dokku detecta o tipo de projeto (Dockerfile ou buildpack), compila, executa o contêiner e configura o roteamento do nginx automaticamente. A aplicação já pode ser acessada em http://hello.apps.example.com.

Confira o status da aplicação:

dokku ps:report hello
dokku logs hello -t

Etapa 5: SSL com Let's Encrypt

O Dokku não inclui HTTPS por padrão. Instale o plugin oficial do Let's Encrypt:

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Configure o plugin com seu e-mail (para receber avisos de renovação):

dokku config:set --global [email protected]

Ative o certificado para sua aplicação:

dokku letsencrypt:enable hello

Depois disso, https://hello.apps.example.com servirá por HTTPS. O Dokku cuida da renovação automática por meio de uma tarefa cron instalada pelo plugin.

Verifique se a renovação está agendada:

dokku letsencrypt:cron-job --add

Manutenção

Atualize o Dokku e todos os plugins pelo apt. Não atualize apenas o dokku sem também atualizar o Docker do sistema, gerenciado pela mesma fonte apt:

sudo apt update && sudo apt upgrade -y

Antes de qualquer atualização importante, faça backup dos dados persistentes dos plugins (por exemplo, bancos de dados) em outro local. Monitore o uso do disco: imagens antigas de compilação e camadas Docker se acumulam com o tempo. Limpe periodicamente os recursos Docker não utilizados:

docker system prune -af

Reinicie o servidor após uma atualização do kernel e confirme que o Dokku inicia o proxy e todas as aplicações:

dokku proxy:report
dokku ps:rebuildall

Quando uma implantação falhar, inspecione os logs e o relatório dos processos em vez de remover volumes. Reverta para uma versão anterior com dokku ps:rebuild.