393 lines
12 KiB
Markdown
393 lines
12 KiB
Markdown
# 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```go
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
ssh root@vim.rede5.com.br
|
|
```
|
|
|
|
Então, defina a variável para o app específico:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
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):
|
|
|
|
```bash
|
|
dokku postgres:link postgres-main gohorse-backend
|
|
```
|
|
|
|
Para desvincular:
|
|
|
|
```bash
|
|
dokku postgres:unlink postgres-main gohorse-backend
|
|
```
|
|
|
|
Para criar um novo banco de dados:
|
|
|
|
```bash
|
|
dokku postgres:create meu-novo-banco
|
|
dokku postgres:link meu-novo-banco minha-app
|
|
```
|
|
|
|
Para verificar informações do banco:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
dokku domains:set gohorse-backend gohorse.dokku.rede5.com.br
|
|
```
|
|
|
|
Para habilitar HTTPS com Let's Encrypt (plugin instalado):
|
|
|
|
```bash
|
|
dokku letsencrypt:enable gohorse-backend
|
|
```
|
|
|
|
Para renewal automático de certificados:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
dokku releases:rollback gohorse-backend
|
|
```
|
|
|
|
Para ver o histórico de releases:
|
|
|
|
```bash
|
|
dokku releases gohorse-backend
|
|
```
|
|
|
|
### Deploy com Build Especial
|
|
|
|
Se você precisa fazer build local e apenas enviar a imagem:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
dokku apps:info gohorse-backend
|
|
```
|
|
|
|
Para ver os logs em tempo real:
|
|
|
|
```bash
|
|
dokku logs gohorse-backend -t
|
|
```
|
|
|
|
Para ver logs de uma quantidade específica de linhas:
|
|
|
|
```bash
|
|
dokku logs gohorse-backend -n 100
|
|
```
|
|
|
|
### Reiniciar Aplicação
|
|
|
|
```bash
|
|
dokku ps:restart gohorse-backend
|
|
```
|
|
|
|
### Parar e Iniciar
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
dokku ps:scale gohorse-backend=2
|
|
```
|
|
|
|
## Configurando Persistent Storage
|
|
|
|
Se sua aplicação precisa de armazenamento persistente (uploads, arquivos, etc.), você pode configurar volumes:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
dokku ps:restart gohorse-backend
|
|
```
|
|
|
|
Para listar mounts:
|
|
|
|
```bash
|
|
dokku storage:list gohorse-backend
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Aplicação Não Inicia
|
|
|
|
Se o container não inicia, verifique os logs:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|