infracloud/vps/vim/deployment_guide.md

Guia de Deploy e Manutenção - Vim

Este guia descreve o processo completo para implantar, atualizar e manter serviços no servidor Vim utilizando a plataforma Dokku.

Visão Geral da Plataforma

O servidor Vim utiliza o Dokku como plataforma de deploy PaaS (Platform as a Service) self-hosted. O Dokku é uma ferramenta open-source que transforma um servidor Linux em um PaaS similar ao Heroku, permitindo o deploy de aplicações através de Git pushes. A plataforma utiliza o Docker para isolar as aplicações e o Nginx como proxy reverso para roteamento de tráfego baseado em domínios.

Esta arquitetura foi escolhida por oferecer um equilíbrio entre simplicidade e funcionalidade. Diferente de um cluster Kubernetes completo, o Dokku não requer conhecimento avançado de contêineres e permite que desenvolvedores façam deploys apenas com conhecimento de Git. A plataforma detecta automaticamente a linguagem de programação da aplicação (Node.js, Go, Python, etc.) através de buildpacks e configura o ambiente de execução apropriado.

Pré-requisitos

Antes de fazer deploy no servidor Vim, certifique-se de ter os seguintes pré-requisitos atendidos:

Primeiro, você precisa de acesso SSH ao servidor com chave SSH configurada. A chave pública deve estar autorizada no arquivo ~/.ssh/authorized_keys do servidor. Sem isso, você não conseguirá fazer o push do código. Segundo, você precisa do Dokku client instalado localmente. Em sistemas Debian/Ubuntu, instale com sudo apt-get install dokku. Terceiro, você precisa ter o Git instalado em sua máquina de desenvolvimento. E quarto, o repositório da aplicação deve ter um Dockerfile ou um dos buildpacks suportados (Node.js, Go, Python, Ruby, Java, PHP, Gradle, .NET Core).

Estrutura de Repositórios

Cada projeto deve seguir uma estrutura específica para funcionar corretamente no Dokku. O repositório precisa ter um arquivo de configuração apropriado para a linguagem utilizada. Para Node.js, é necessário ter um package.json com scripts de start definidos. Para Go, o go.mod é essencial. O Dokku detecta automaticamente a linguagem e aplica o buildpack correto.

Abaixo está um exemplo de package.json otimizado para Dokku:

{
  "name": "gohorse-backend",
  "version": "1.0.0",
  "main": "dist/index.js",
  "scripts": {
    "start": "node dist/index.js",
    "build": "tsc",
    "dev": "nodemon src/index.ts"
  },
  "dependencies": {
    "express": "^4.18.2",
    "pg": "^8.11.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@types/node": "^20.0.0"
  }
}

Para aplicações Go, o go.mod deve seguir este formato:

module github.com/sua-empresa/gohorse-backend

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/lib/pq v1.10.9
)

Fazendo o Primeiro Deploy

O processo de deploy no Dokku é simples e segue o fluxo similar ao Heroku. Primeiro, você precisa adicionar o remote do Dokku ao seu repositório Git local. No diretório do seu projeto, execute o comando para adicionar o remote Dokku, substituindo o nome do app e o usuário:

git remote add dokku dokku@vim.rede5.com.br:gohorse-backend

Este comando configura o remote "dokku" apontando para o servidor Vim. Note que o nome após os dois pontos deve corresponder exatamente ao nome do app que você criou no Dokku. Se o app se chamar "gohorse-backend", você deve usar "gohorse-backend" no remote.

Se o app ainda não existe no Dokku, você pode criá-lo diretamente com o push:

git push dokku main:master

Quando o Dokku recebe o primeiro push para um app que não existe, ele automaticamente cria o app e inicia o processo de deploy. Se preferir criar o app manualmente antes do primeiro deploy, você pode SSH no servidor e executar:

dokku apps:create gohorse-backend

Configurando Variáveis de Ambiente

As variáveis de ambiente são essenciais para o funcionamento correto das aplicações. No Dokku, você pode definir variáveis de ambiente tanto pelo servidor quanto através de arquivos .env. Para definir uma variável de ambiente pelo terminal, primeiro faça SSH no servidor:

ssh root@vim.rede5.com.br

Então, defina a variável para o app específico:

dokku config:set gohorse-backend DATABASE_URL=postgres://user:password@host:5432/dbname
dokku config:set gohorse-backend NODE_ENV=production
dokku config:set gohorse-backend PORT=5000

Para ver todas as variáveis de um app:

dokku config gohorse-backend

Para desenvolvimento local, crie um arquivo .env na raiz do projeto (que deve estar no .gitignore):

DATABASE_URL=postgres://postgres:password@localhost:5432/gohorse_dev
NODE_ENV=development
PORT=5000

Em aplicações Node.js, utilize a biblioteca dotenv para carregar essas variáveis:

import dotenv from 'dotenv';
dotenv.config();

const port = process.env.PORT || 3000;
const dbUrl = process.env.DATABASE_URL;

Configurando Bancos de Dados PostgreSQL

O servidor Vim possui dois bancos de dados PostgreSQL gerenciados pelo Dokku: o postgres-main (versão 17) e o agno-db (versão 18.1). Para conectar uma aplicação a um banco de dados, você deve criar um link entre o serviço e o app.

Para criar o link (isso automaticamente define a variável DATABASE_URL):

dokku postgres:link postgres-main gohorse-backend

Para desvincular:

dokku postgres:unlink postgres-main gohorse-backend

Para criar um novo banco de dados:

dokku postgres:create meu-novo-banco
dokku postgres:link meu-novo-banco minha-app

Para verificar informações do banco:

dokku postgres:info postgres-main
dokku postgres:list

Configurando Domínios e SSL

O Dokku permite configurar domínios customizados para cada aplicação. Para adicionar um domínio:

dokku domains:set gohorse-backend gohorse.dokku.rede5.com.br

Para habilitar HTTPS com Let's Encrypt (plugin instalado):

dokku letsencrypt:enable gohorse-backend

Para renewal automático de certificados:

dokku letsencrypt:auto-renew gohorse-backend

Sem o plugin Let's Encrypt, você pode configurar SSL manualmente através do Nginx ou usando certificados propios. O Nginx do servidor Vim está configurado para aceitar conexões HTTPS nas portas 80 e 443, então você pode também gerenciar certificados manualmente se preferir.

Mapeamento de Portas

O Dokku expõe automaticamente as aplicações em portas dinâmicas. Por padrão, ele usa a variável PORT definida no ambiente do container. Para configurar o mapeamento de portas explicitamente:

dokku ports:set gohorse-backend http:80:5000

Este comando mapeia a porta 80 do host para a porta 5000 do container. Para múltiplas portas (HTTP e HTTPS):

dokku ports:set gohorse-backend http:80:8080 https:443:8080

Comandos de Deploy

Deploy Padrão

Para fazer o deploy de uma nova versão, basta fazer push para o remote Dokku:

git push dokku main:master

O Dokku mostrará o progresso do build e informará quando o deploy estiver completo. Você pode acompanhar os logs do deploy em tempo real.

Rollback

Se algo der errado após o deploy, você pode fazer rollback para a versão anterior:

dokku releases:rollback gohorse-backend

Para ver o histórico de releases:

dokku releases gohorse-backend

Deploy com Build Especial

Se você precisa fazer build local e apenas enviar a imagem:

docker build -t dokku/gohorse-backend:latest .
docker push dokku/gohorse-backend:latest
dokku deploy gohorse-backend

Gerenciando Serviços

Verificar Status

Para ver o status de uma aplicação:

dokku apps:info gohorse-backend

Para ver os logs em tempo real:

dokku logs gohorse-backend -t

Para ver logs de uma quantidade específica de linhas:

dokku logs gohorse-backend -n 100

Reiniciar Aplicação

dokku ps:restart gohorse-backend

Parar e Iniciar

dokku ps:stop gohorse-backend
dokku ps:start gohorse-backend

Escalar Aplicação

O Dokku suporta múltiplas instâncias de um app (apenas para Dockerfiles):

dokku ps:scale gohorse-backend=2

Configurando Persistent Storage

Se sua aplicação precisa de armazenamento persistente (uploads, arquivos, etc.), você pode configurar volumes:

dokku storage:mount gohorse-backend /var/lib/dokku/gohorse-backend/uploads:/app/uploads

O primeiro caminho é no host (servidor) e o segundo é dentro do container. Após adicionar um mount, reinicie o app:

dokku ps:restart gohorse-backend

Para listar mounts:

dokku storage:list gohorse-backend

Troubleshooting

Aplicação Não Inicia

Se o container não inicia, verifique os logs:

dokku logs gohorse-backend

Erros comuns incluem: variável PORT incorreta (o Dokku define automaticamente a variável PORT baseado no Dockerfile ou Procfile), dependências faltando no package.json ou go.mod, e banco de dados não vinculado corretamente.

Erro de Build

Se o build falha, verifique a saída do comando git push. Erros comuns incluem: versão do Node/Go não compatível, memória insuficiente durante o build (pode precisar de swap), e dependências privadas não acessíveis.

Problemas de Conexão com Banco

Se a aplicação não conecta ao banco: verifique se o link foi criado corretamente com dokku postgres:info postgres-main, confirme que a variável DATABASE_URL está correta com dokku config gohorse-backend, e verifique se o banco está rodando com dokku postgres:status postgres-main.

Container em Estado de Crash

Se o container está constantemente reiniciando:

dokku logs gohorse-backend --num 50

Pode ser necessário ajustar a configuração de healthcheck ou verificar se há erros de inicialização no código.

Checklist de Boas Práticas

Antes de fazer deploy para produção, siga esta checklist:

Garanta que o arquivo Procfile ou Dockerfile esteja correto e defina o comando de start apropriado. Para Node.js com package.json, o Dokku detecta automaticamente. Para outros casos, crie um Procfile:

web: npm start
worker: npm run worker

Confirme que todas as variáveis de ambiente necessárias estão configuradas no Dokku. O banco de dados está linkado corretamente. Os domínios estão configurados e DNS está apontando para o servidor. Os certificados SSL estão válidos (se aplicável). Os logs estão funcionando e você consegue acessar para debugar.

Limpeza e Manutenção

Para limpar recursos não utilizados:

# Limpar containers Docker órfãos
docker container prune -f

# Limpar imagens não utilizadas
docker image prune -a -f

# Limpar volumes não utilizados
docker volume prune -f

# Limpar builds antigos do Dokku
dokku cleanup

Para verificar uso de disco:

df -h
docker system df

Referência Rápida de Comandos

Ação	Comando
Listar apps	dokku apps:list
Criar app	dokku apps:create nome-app
Deletar app	dokku apps:destroy nome-app
Ver config	dokku config nome-app
Setar config	dokku config:set nome-app CHAVE=valor
Ver logs	dokku logs nome-app -t
Reiniciar	dokku ps:restart nome-app
Listar bancos	dokku postgres:list
Info banco	dokku postgres:info nome-banco
Link banco	dokku postgres:link nome-banco nome-app

GoHorseJobs - Fluxo Git

O gohorsejobs eh um monorepo hospedado em dois remotes. O GitHub eh a origem de desenvolvimento e o Forgejo eh mirror.

Remotes

Remote	URL	Funcao
origin	github.com/rede5/gohorsejobs	Desenvolvimento (PRs, CI)
pipe	pipe.gohorsejobs.com/bohessefm/gohorsejobs	Mirror Forgejo
dokku	dokku@localhost:gohorsejobs	Deploy app principal
dokku-frontend	dokku@localhost:gohorse-frontend	Deploy frontend

Sincronizacao GitHub -> Forgejo

cd /root/gohorsejobs
git pull origin dev       # Puxa do GitHub
git push pipe dev         # Envia para Forgejo

Repetir para branches main e hml conforme necessario.

Regra: GitHub primeiro, Forgejo depois

Todo codigo novo entra via GitHub (PRs, Codex, commits diretos). O Forgejo recebe via push manual na VPS. Nunca commitar direto no Forgejo.