Blog do Fernando Jorge Mota

Como programador, uma coisa que eu aprecio demais na nossa profissão é a possibilidade de criar side projects. Claro, relaxar é super importante, eu não nego, ainda mais para nós que trabalhamos basicamente pensando muito o dia inteiro.

Mas poder criar projetos que resolvem AQUELE problema ou necessidade chato que você tem - e ainda de quebra poder ajudar outras pessoas (ou até faturar algum $$$ extra, em alguns casos) - também é algo muito bem vindo.

O problema, como sempre, é que isso é basicamente...trabalho, e por mais interessante que seja poder customizar cada parte do seu próprio projeto, o fato é que quanto mais você demora para lançá-lo - por qualquer motivo que seja - maiores são as chances de você acabar desistindo e/ou partindo para outro projeto.

E é nesse ponto que entra o Dokku: um projeto que, após ser instalado em um servidor (VPS ou dedicado, conforme o seu bolso deixar), lhe permite facilmente criar novas aplicações e fazer deploy delas, usando um workflow muito parecido com o do Heroku, mas sem os custos extras (além do custo do servidor e do seu tempo, é claro).

O que é

O Dokku é um projeto que implementa um PaaS - Platform as a Service, ou Plataforma como Serviço, em inglês - e usa o Docker - que já apresentamos em outro post - para fazer suas "magias". Sua administração decorre de um simples comando chamado "dokku", que permite a criação de novos aplicativos (que é como o projeto chama os seus projetos) e também configuração dos mesmos.

Além disso, possui um ecossistema muito rico, com plugins que facilitam, entre outras coisas, a instalação e configuração de projetos como MySQL, PostgreSQL e RabbitMQ, e até mesmo facilitam a configuração de certificados SSL usando Let's Encrypt.

Depois de configurar o Dokku completamente, se torna possível publicar seu projeto com apenas alguns poucos comandos (a depender do que você usa no seu projeto), portanto tornando possível publicar o seu projeto muito rapidamente. Para que isso seja possível, entretanto, é necessário seguir algumas regras durante o desenvolvimento do seu projeto, chamado Twelve-Factor App, em especial no que diz respeito à configuração do projeto, mas isso é algo que qualquer framework moderno já suporta facilmente, então não chega a ser um grande problema.

Como instalar

Para instalar o Dokku, você precisa primeiramente de um servidor VPS ou dedicado, ou seja, não dá para usar uma hospedagem compartilhada com ele. Também é necessário que você possua um domínio, e que o servidor em questão rode uma distribuição Linux. Para simplificar o processo de instalação, vou mostrar aqui apenas os comandos para quem usa Ubuntu ou Debian no servidor. É plenamente possível usar o Dokku também com outras distribuições, mas, o processo será potencialmente mais complicado.

Se você quiser apenas usar o Dokku em seu próprio computador, digamos, para ver como funciona, também é possível usar o Vagrant - que apresentei em outro post - para rodá-lo. Apenas esteja ciente de que dessa forma os seus projetos NÃO serão publicados na internet. Segue aqui as instruções.

Com tudo isso dito, segue os comandos para instalar a última versão do Dokku - 0.30.2 - conforme disponível no momento de escrita desse post. Eu sugiro fortemente para que você verifique a última versão disponível do Dokku e ajuste o comando de forma correspondente abaixo, portanto, os comandos abaixo são apenas uma referência:

wget https://dokku.com/bootstrap.sh
sudo DOKKU_TAG=v0.30.2 bash bootstrap.sh

ATENÇÃO: Antes de rodar esses comandos de forma imediata, eu sugiro para que os rode individualmente, e, se possível, analise o conteúdo do arquivo baixado após a execução do primeiro comando. O Dokku é um projeto bastante confiável, mas, sempre vale ter essa prática por segurança, com todo e qualquer comando do tipo que você vê por aí.

Depois de rodar esses comandos e de instalar o Dokku, chegou a hora de configurar o domínio global que o Dokku usará. Uma questão importante sobre esse domínio é que, em um cenário ideal, o domínio deve ser configurado de forma que todo sub-domínio ainda não definido aponte para o servidor no qual o Dokku está instalado. Em termos técnico, isso significa que o DNS precisa ter uma entrada "wildcard" apontando para o seeu servidor. Isso NÃO é um requisito para o uso do Dokku, mas, facilita e muito a configuração de novos aplicativos, visto que você acaba não precisando configurar o DNS manualmente a cada vez que você vai criar um novo aplicativo (bom, pelo menos não se você quiser que sua aplicação rode em um..sub-domínio). Para referência, nesse artigo é mostrado como configurar uma entrada wildcard no Cloudflare. Consulte a documentação do servidor DNS que você usa para mais informações.

Com isso dito, segue o comando para configurar o domínio global no Dokku, onde SEU_DOMINIO é o dominio que o Dokku deve usar como global:

dokku domains:set-global SEU_DOMINIO

Depois de configurar o Dokku no seu servidor, uma última etapa que eu considero bastante importante é configurar um cliente do Dokku no seu próprio computador. Naturalmente, o processo varia bastante de acordo com a sua preferência, mas aqui está a lista de clientes que podem ser usados para se comunicar com o Dokku. Pessoalmente, eu gosto bastante do cliente oficial do Dokku, que é bastante simples e funciona por SSH, tornando toda a comunicação bastante segura e simples.

Como publicar sua primeira aplicação

Depois de configurado, publicar sua primeira aplicação é bem simples. Digamos que você tenha um simples repositório Git - que você pode ler mais sobre nesse post - com o seguinte arquivo - chamado index.php - comittado:

<?php
// Pega o nome da URL, ou assume o padrão "Mundo", e converte caracteres HTML de forma que não seja possível injetar JS/CSS na página:
$nome = htmlspecialchars( $_GET["name"] ?? "Mundo" );
// Imprime "Olá, " seguido do valor da variável acima
echo "Olá, {$nome}";

E também tenha no repositório os arquivos "composer.json" e "composer.lock" criados pelo Composer, sobre o qual já falei aqui (você pode rodar composer init e responder todas as perguntas para configurar o Composer corretamente).

Apesar da criação dos arquivos composer.json e composer.lock não ser SUPER necessária - visto que o Dokku consegue detectar que se trata de um projeto que usa PHP à partir da existência do arquivo index.php - é algo que é recomendado, visto que o modo de detecção a partir da existência de arquivos PHP é considerado depreciado.

Antes de fazer o deploy dessa aplicação, que vamos chamar aqui de hello, você primeiramente precisa criar a aplicação no Dokku. Para isso, você pode usar o seguinte comando, que usa o cliente oficial do Dokku mencionado anteriormente:

dokku apps:create hello

Depois de criado, você pode simplesmente rodar o seguinte comando para fazer o deploy do projeto, assumindo que a branch principal do repositório em questão é a branch main, e que você fez o commit nessa branch:

git push dokku main

Depois de rodar o comando, o Dokku analisará o conteúdo do repositório e rapidamente constatará que se trata de uma aplicação em PHP, usando um projeto chamado Herokuish. A partir daí, será usado o buildpack do Heroku para PHP para fazer o deploy da sua aplicação, que deverá estar disponível em hello.SEU_DOMINIO.

Como eu possuo Dokku instalado nesse mesmo servidor, você pode ver a aplicação rodando aqui: http://hello.fjorgemota.com/?nome=Teste - sinta-se a vontade para mudar o parâmetro nome para qualquer outra coisa apenas para experimento. 🙂

Conectando um banco de dados

Naturalmente, fazer uma simples aplicação assim não mostra o potencial completo da ferramenta. Em virtude disso, vamos complicar um pouquinho o exemplo: Em vez de um simples código PHP que printa um parâmetro recebido na URL, vamos fazer um contador de visitas...bem simples, mas enfim.

Para isso, no repositório Git criado anteriormente, adicione o seguinte código no final do arquivo index.php:

// Captura a URL da variável de ambiente e divide em partes
$parametros = parse_url( getenv( "DATABASE_URL" ) );
// Gera a URL para passar para o PDO, contendo os dados de configuração do banco de dados
$url = sprintf( "pgsql:host=%s;port=%d;dbname=%s;user=%s;password=%s", $parametros['host'], $parametros['port'],  substr( $parametros['path'], 1 ), $parametros['user'], $parametros['pass'] );
// Conecta oa banco de dados
$conexao = new PDO( $url );
// Faz a consulta para contar o número de visitas e retornar o número atualizado
$consulta = $conexao->query( "INSERT INTO visits ( id, num_visits ) VALUES( 1, 1 ) ON CONFLICT (id) DO UPDATE SET num_visits = visits.num_visits + EXCLUDED.num_visits RETURNING num_visits");
// Captura o número de visitas retornado pelo banco de dados
$visitas = $consulta->fetchColumn( 0 );
// Imprime o resultado na página
echo "<br /> Número de visitas: {$visits}";

Depois de adicionar esse script ao arquivo, lembre-se de comittar e enviar o resultado para o Dokku, usando git push dokku main como definido acima.

Como você pode imaginar, isso não vai ser suficiente: Estamos aqui usando o PDO com o PDO_PGSQL para conectar a um banco de dados PostgreSQL, que é um SGBD bastante completo. Só que, no momento, o Dokku não faz a mínima ideia dessa dependência do PostgreSQL pra começo de conversa. Portanto, vamos por partes: Vamos configurar o PostgreSQL no Dokku. Felizmente, graças ao fato de que o PHP que o Dokku usa vem com o PDO e o PDO_PGSQL (conforme listado aqui) ativado por padrão, não vamos precisar nos preocupar com a configuração do mesmo.

Para configurar o PostgreSQL no Dokku, primeiramente você precisa instalar o plugin dokku-postgres, que permite criar e gerenciar "serviços" PostgreSQL, e também integrá-los com sua aplicação. Para fazer isso, basta rodar o comando abaixo:

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

Agora, vamos criar o "serviço", que nada mais é do que o container Docker rodando o PostgreSQL. Esse serviço se chamará pgdb:

dokku postgres:create pgdb

Finalmente, vamos conectar o serviço criado com a nossa aplicação hello:

dokku postgres:link pgdb hello

Com isso feito, deveremos ter uma variável de ambiente (ou environment variable, em inglês) chamada DATABASE_URL com as informações necessárias para se conectar ao serviço pgdb, que é basicamente o nosso servidor PostgreSQL. Entretanto, falta uma coisa importante: criar a tabela visits, que o nosso script em PHP usa para contar as visitas. Para fazer isso, primeiro, conecte ao PostgreSQL usando o comando abaixo:

dokku postgres:connect pgdb

E então execute o seguinte SQL para criar a tabela visits:

CREATE TABLE visits(id INT PRIMARY KEY NOT NULL, num_visits INT NOT NULL);

Agora, acesse sua aplicação e verifique que, a cada vez que você atualiza a página, o contador é devidamente incrementado, como se espera de um contador de visitas.

Configurando sua aplicação

O Dokku fornece uma forma fácil de configurar sua aplicação através do uso de variáveis de ambiente, que são úteis para definir parâmetros diversos da sua aplicação. Alguns exemplos que me vem à mente são configurações do servidor de e-mail, configurações de log (para usos mais robustos além do tradicional dokku logs) e outras configurações mais específicas da sua aplicação, como...fuso horário padrão.

Para configurar uma variável de ambiente, você pode usar o comando dokku config. No script acima, se você mudar a linha:

$nome = htmlspecialchars( $_GET["nome"] ?? "Mundo" );

Por:

$nome = htmlspecialchars( $_GET["nome"] ?? getenv("DEFAULT_NAME") ?? "Mundo" );

Você se torna apto a usar a variável de ambiente DEFAULT_NAME para mudar o nome que deve aparecer por padrão caso o parâmetro não seja definido na URL. Com o Dokku, você pode configurar tal variável de ambiente usando o seguinte comando, que configurará o valor para "User":

dokku config:set DEFAULT_NAME=Usuário

Escalonando a aplicação

Vamos dizer que sua aplicação é um sucesso absoluto! E que, graças a isso, não é mais suficiente rodar sua aplicação com apenas um processo. O Dokku fornece um comando simples para ajudar nisso, inclusive configurando balanceamento de carga para você. Por exemplo, para ter 4 instâncias da sua aplicação rodando, você pode rodar o seguinte comando:

dokku ps:scale hello web=4

Note, entretanto, que as 4 instâncias da aplicação ainda estarão rodando dentro do mesmo servidor. Na maior parte dos casos, isso pode ser suficiente, em especial se o seu servidor possuir vários núcleos.

Entretanto, em um dado momento, se torna interessante ter vários servidores operando. Para fazer isso, o processo é BEM mais complicado, e envolve o uso de sistemas como o Kubernetes, com o qual é possível integrar usando um plugin do Dokku. Em virtude disso, eu não vou cobrir esse assunto aqui, mas, é algo que é interesante saber de qualquer forma. 🙂

Conclusão

Como é possível ver, o Dokku facilita e muito todo o processo de deploy e configuração da sua aplicação. No geral, todo o uso da ferramenta é muito inspirado pelo Heroku, que foi pioneiro nessa abordagem de deploy e configuração.

Apesar disso, o fato é que, honestamente, a grande maior parte dos projetos NÃO precisam de algo tão robusto e nem tão caro quanto o Heroku, e aí o Dokku começa a se tornar muito mais interessante, visto que com um simples VPS (que hoje você consegue contratar por menos de 5 dólares ao mês), você consegue hospedar diversas aplicações E ainda ter todas essas facilidades de forma bem tranquila, o que é útil em especial se as suas aplicações não tem como meta retorno financeiro (que é o meu caso).

"Mas, Fernando, eu trabalho para uma empresa pequena, vale a pena usar Dokku?" - Bom, eu diria que depende muito. Se vocês tem condições de ter um VPS (e há, por exemplo, há uma pessoa trabalhando com a infraestrutura da empresa), a resposta é... Talvez.

Na prática, entretanto, se você tem um projeto que possui retorno financeiro, quase sempre vale considerar fortemente o uso de um serviço como o Heroku (ou um de seus concorrentes), simplesmente pela paz de espírito que se tem ao poder dormir à noite ou passar o tempo livre, e também por todo o suporte que você tem ao usar algo especializado do tipo.

Bom, espero que tenham gostado da leitura, e deixem nos comentários: como é o processo de deploy do seu último projeto?