Dokku: minha plataforma serverless pessoal favorita

• Dokku é uma PaaS open source que permite usar um único VPS como se fosse o Heroku, sendo ideal para uso pessoal e equipes pequenas que querem implantar vários apps de forma barata em infraestrutura própria
• Workloads sem GPU estão rodando em um VPS da OVHcloud de US$ 7/mês, o que reduz custo e complexidade de deploy em ambientes como consultoria de LLM, onde é comum publicar apps com frequência
• Apps baseados em Dockerfile podem ser implantados apenas criando o app no Dokku, adicionando um Git remote e executando git push dokku main; a quantidade de processos pode ser ajustada com dokku ps:scale
• Até sites estáticos podem combinar _site, .static, o buildpack do nginx e dokku-http-auth para permitir deploy a partir de repositórios privados no GitHub com proteção por senha
• Conectando GitHub Actions, comandos remotos via SSH, invalidação do cache do Docker e rebuild sem push, é possível transformar uma PaaS pessoal em um ambiente operacional reproduzível

---

Dokku: usando um único VPS como se fosse o Heroku

• Dokku é uma PaaS open source que roda em um único servidor escolhido pelo usuário
• Ela oferece uma experiência de deploy parecida com a do Heroku, mas com a infraestrutura pertencendo ao próprio usuário
• Como o custo do Heroku pode ficar alto, uma plataforma de deploy com boa relação custo-benefício é importante em trabalhos de consultoria com LLM que exigem publicar vários aplicativos
• O servidor Dokku está rodando em um VPS da OVHcloud de US$ 7/mês para workloads sem GPU
  • Exemplos de aplicações incluem nbsanity e uma ferramenta de organização de dados para LLM

Experiência de deploy no estilo Heroku e recursos operacionais

• O Dokku oferece um fluxo de deploy fácil de usar, no estilo Heroku
• Suporta gerenciamento automático de certificados SSL com Let’s Encrypt
• É possível proteger sites com senha usando Basic Auth
• Dá para fazer scale up/down com um único comando
• Lida com vários tipos de app, como Node e Python, e também permite definir containers Docker manualmente quando necessário
• Há muitos plugins oficiais, o que permite estender praticamente qualquer funcionalidade necessária
• O deploy pode ser feito apenas com comandos Git

Implantando apps com containers Docker

• Depois de instalar o Dokku no VPS, basta colocar um Dockerfile na raiz do repositório do app para fazer o deploy com um container Docker
• O Dockerfile de exemplo usa a imagem python:3.10, copia o código para /app e depois executa pip install .
• O entrypoint.sh é usado para facilitar a execução do app localmente ou dentro do container Docker
  • No exemplo, ele executa um app FastAPI com uvicorn main:app --port "$PORT" --host 0.0.0.0
• Primeiro, o app é criado no host Dokku

dokku apps:create myapp

• No ambiente local, as informações de acesso ao host Dokku são configuradas em ~/.ssh/config, definindo o nome desse host como dokku
• Depois, basta adicionar o Dokku como remote no repositório Git local e fazer push para implantar

git remote add dokku dokku@dokku:myapp
git push dokku main

• Após o deploy, a URL do app é exibida nos logs locais, e o padrão é algo como myapp.yourdomain.com
• A quantidade de workers pode ser ajustada com o comando abaixo

dokku ps:scale myapp web=2

• Mais detalhes podem ser encontrados na documentação do Dokku

Sites estáticos privados e Basic Auth

• O GitHub Pages é inconveniente para publicar sites estáticos privados com facilidade, porque exige uma conta Enterprise cara
• Com o Dokku, é possível implantar um site estático a partir de um repositório privado no GitHub e protegê-lo com senha
• Assume-se que o site estático esteja na pasta _site do repositório Git
• No host Dokku, crie o app e defina a variável de ambiente NGINX_ROOT como _site

dokku apps:create mysite
dokku config:set static-site NGINX_ROOT=_site

• Instale o basic auth no host Dokku e aplique a configuração de permissões para o plugin funcionar

sudo dokku plugin:install https://github.com/dokku/dokku-http-auth.git
sudo chmod +x /home/dokku

• Na raiz do repositório Git que contém o site estático, execute o seguinte

touch .static
echo BUILDPACK_URL=https://github.com/dokku/buildpack-nginx > .env
git remote add dokku dokku@dokku:mysite

• .static informa ao Dokku que se trata de um site estático
• BUILDPACK_URL define que o buildpack do nginx deve ser usado
  • Normalmente ele é detectado automaticamente, mas em projetos que misturam código e site estático, explicitar o buildpack do nginx ajuda a evitar confusão
• O deploy é feito com git push dokku main
• A autenticação é ativada no host Dokku com o comando abaixo

dokku http-auth:enable mysite <username> <password>

• É possível adicionar vários pares de usuário/senha e também filtrar IPs específicos
• O HTTPS pode ser configurado com o plugin do Let’s Encrypt, que também oferece renovação automática
• Se o HTTPS for tratado por um proxy da Cloudflare, pode-se usar uma configuração que delega isso à Cloudflare em vez de usar o plugin do Let’s Encrypt

Deploy automático com GitHub Actions

• Apps do Dokku podem ser implantados automaticamente com GitHub Actions
• Assim, não é preciso repetir manualmente o processo de dar push direto para o host Dokku
• O workflow de exemplo roda em workflow_dispatch e também em pushes para a branch main
• A configuração de concurrency cancela jobs anteriores para evitar o deploy lock do Dokku
• O workflow faz checkout do código, cria a chave SSH privada a partir de secrets.DOKKU_SSH_PRIVATE_KEY, adiciona o Git remote e faz push forçado para o Dokku

name: CI
on:
  workflow_dispatch:
  push:
    branches: [main]

concurrency:
  group: ${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy-dokku:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      - name: Install SSH key
        run: |
          echo "${{ secrets.DOKKU_SSH_PRIVATE_KEY }}" > private_key.pem
          chmod 600 private_key.pem

      - name: Add remote and push
        run: |
          git remote add dokku [e-mail]:llm-eval
          GIT_SSH_COMMAND="ssh -i private_key.pem -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no" git push dokku main -f

Comandos remotos de operação e rebuild

• O nome do app no exemplo é llm-eval, e o host é rechat.co
• Mesmo sem fazer login via SSH diretamente no host Dokku, é possível executar comandos remotos com o usuário dokku

ssh [e-mail] apps:list

• É possível invalidar o cache do Docker para forçar um novo build

ssh [e-mail] repo:purge-cache llm-eval

• Quando for necessário fazer rebuild sem push, há várias formas, e uma delas é o comando abaixo

ssh [e-mail] ps:rebuild llm-eval

Material de referência pessoal para deploys repetidos

• Isso foi organizado porque, a cada novo app implantado, era preciso procurar novamente os mesmos detalhes
• Fica como material de referência reutilizável para montar repetidamente uma plataforma pessoal de deploy com Dokku