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:

```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` |