Guia de Deploy Intuitivo e Detalhado
Este documento fornece um passo a passo completo para realizar o deploy de aplicações em uma VPS Hetzner rodando Ubuntu 20.04. Abordaremos desde a edição de código até a publicação inicial e atualizações futuras.
Público-alvo: iniciantes.
Para facilitar o processo, preencha suas variáveis de deploy no painel à direita (ou no botão "Variáveis" no celular).
1 Preparação do Ambiente
Você precisará das seguintes ferramentas e recursos:
-
VPS Hetzner: servidor remoto com acesso via SSH.
-
Ubuntu 20.04: sistema operacional.
-
PostgreSQL: banco de dados local.
-
Nginx: proxy reverso para rotear requisições.
-
Let's Encrypt: emissão de certificados SSL gratuitos.
-
Cloudflare DNS: gerenciamento de DNS.
-
GitHub: versionamento de código.
-
Cursor: editor de código.
2 Configuração de DNS (Cloudflare)
Aponte seu domínio para a VPS através de um registro A no Cloudflare:
- Acesse o painel do Cloudflare e selecione seu domínio.
- Navegue até DNS → Add record.
- Configure o registro com os seguintes valores:
- Type: A
- Name: @ (para o domínio raiz)
- IPv4 address: 142.132.234.105
- TTL: Auto
- Clique em Save e aguarde a propagação (5-30 minutos).
Terminal
# Teste se o DNS está funcionando
ping seu-dominio.com
3 Criação do Repositório no GitHub
Crie um novo repositório no GitHub para armazenar o código do projeto:
- Acesse github.com e faça login na sua conta.
- Clique no botão New repository (ou "+" no canto superior direito).
- Configure o repositório:
- Nome: controlveiculo
- Visibilidade: Privada (recomendado para projetos comerciais)
- Clique em Create repository.
4 Envio Inicial ao GitHub
Para enviar seu código local ao repositório pela primeira vez:
Crie um arquivo
.gitignore para evitar enviar arquivos desnecessários ao repositório.
Terminal
# Crie um arquivo .gitignore com o seguinte conteúdo:
node_modules/
.env
.next/
.DS_Store
Terminal
# Inicialize o repositório Git
git init
# Adicione todos os arquivos
git add .
# Faça o commit inicial
git commit -m "Initial commit"
# Conecte ao repositório remoto
git remote add origin https://github.com/SEU_USUARIO/NOME_REPO.git
# Configure a branch principal
git branch -M main
# Envie para o GitHub
git push -u origin main
5 Acesso e Preparação da VPS
Conecte-se ao servidor e atualize o sistema operacional:
Terminal
# Conecte-se à VPS via SSH
ssh root@142.132.234.105
# Atualize os pacotes do sistema
apt update && apt upgrade -y
6 Verificação de Versões
Verifique se as ferramentas necessárias estão instaladas e suas versões:
Terminal
# Verifique a versão do Git
git --version
# Verifique a versão do Node.js
node --version
# Verifique a versão do npm
npm --version
# Verifique a versão do Prisma CLI
npx prisma --version
# Verifique a versão do PM2
pm2 --version
7 Instalação de Pacotes Essenciais
Instale as ferramentas necessárias para o deploy:
Terminal
# Adicione o repositório do Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
# Instale Node.js e Git
apt install -y nodejs git
# Instale o PM2 globalmente
npm install -g pm2
# Instale PostgreSQL
apt install -y postgresql postgresql-contrib
# Instale Nginx e UFW (firewall)
apt install -y nginx ufw
8 Configuração do PostgreSQL
Configure o banco de dados PostgreSQL para sua aplicação:
Terminal
# Acesse o PostgreSQL como usuário postgres
sudo -u postgres psql
# Crie um usuário para sua aplicação
CREATE USER appuser WITH PASSWORD 'SUA_SENHA';
# Crie um banco de dados e defina o proprietário
CREATE DATABASE appdb OWNER appuser;
# Saia do PostgreSQL
\q
Use uma senha forte para o usuário do banco de dados e anote-a para uso no arquivo .env posteriormente.
Para configurar acesso remoto ao PostgreSQL (opcional):
Terminal
# Edite o arquivo de configuração principal
nano /etc/postgresql/12/main/postgresql.conf
# Altere a linha: listen_addresses = '*'
# Edite o arquivo de controle de acesso
nano /etc/postgresql/12/main/pg_hba.conf
# Adicione a linha: host all all 0.0.0.0/0 md5
# Reinicie o serviço para aplicar as alterações
systemctl restart postgresql
Permitir acesso remoto ao banco de dados aumenta os riscos de segurança. Use essa configuração apenas se necessário e certifique-se de que o firewall esteja adequadamente configurado.
9 Configuração do Firewall (UFW)
Configure o firewall para permitir apenas as portas necessárias:
Terminal
# Configure as políticas padrão
ufw default deny incoming
ufw default allow outgoing
# Permita SSH (porta 22)
ufw allow 22/tcp
# Permita HTTP (porta 80)
ufw allow 80/tcp
# Permita HTTPS (porta 443)
ufw allow 443/tcp
# Permita PostgreSQL (portas 5432 e 5456)
ufw allow 5432/tcp
ufw allow 5456/tcp
# Ative o firewall
ufw enable
# Verifique o status
ufw status verbose
Certifique-se de que a porta SSH (22) esteja liberada antes de ativar o firewall, caso contrário você poderá perder o acesso ao servidor.
10 Preparar Diretório e Clonar Repositório
Crie o diretório para o projeto e clone o repositório:
Terminal
# Crie diretório para deploy
mkdir -p /var/www/nome-do-app
cd /var/www/nome-do-app
# Clone o repositório do GitHub
git clone https://github.com/SEU_USUARIO/NOME_REPO.git .
# Caso já exista, apenas atualize
git pull origin main
10.1 Definindo a Porta via .env
É recomendado usar uma variável de ambiente para definir a porta de cada aplicação, mantendo o código flexível entre ambientes.
Terminal
# 1. Crie (ou edite) o arquivo .env na raiz do projeto:
nano .env
# 2. Adicione a linha com a porta desejada:
PORT=3001
# 3. Ajuste o script de start no package.json para usar a variável:
{ "scripts": { "build": "next build", "start": "next start -p $PORT" } }
Ao iniciar com PM2, ele carregará a porta do arquivo .env automaticamente:
pm2 start npm --name app2 -- start
Terminal
# Verifique a aplicação escutando na porta definida:
pm2 list
11 Configurar Variáveis de Ambiente
Configure as variáveis de ambiente para a aplicação:
Terminal
# Copie exemplo e edite
cp .env.example .env
nano .env
# Exemplo de variáveis completo:
PORT=3020
DATABASE_URL="postgresql://userdb:123456@localhost:5456/leodb1"
MAX_INACTIVITY=60
ACCESS_TOKEN_EXPIRES_IN=20000
REFRESH_TOKEN_EXPIRES_IN=86400
JWT_SECRET="uma-chave-super-secreta-nao-revele"
Certifique-se de usar uma chave JWT_SECRET forte e única. Nunca compartilhe seus arquivos .env e sempre inclua-os no .gitignore.
12 Instalar Dependências e Build
Instale as dependências e gere o build da aplicação:
Terminal
# Instale dependências
npm install
# Gere arquivos do Prisma (se aplicável)
npx prisma generate
# Aplique migrações
npx prisma migrate deploy
# Compile aplicação Next.js
npm run build
13 Gerenciar Processo com PM2
Configure o PM2 para gerenciar o processo da aplicação:
Terminal
# Iniciar aplicação no PM2 (método básico)
pm2 start npm --name nome-do-app -- start
pm2 save
pm2 startup
# Método avançado (com variáveis e diretório definidos)
pm2 delete nome-do-app
PORT=3020 NODE_ENV=production pm2 start npm \
--name nome-do-app \
--cwd /var/www/nome-do-app \
-- start
pm2 save
# Para atualizar
pm2 pull nome-do-app
pm2 restart nome-do-app
O método avançado define o diretório de trabalho (--cwd) e injeta variáveis de ambiente diretamente no comando, útil quando você precisa sobrescrever valores do arquivo .env.
14 Configurar Nginx (Proxy Reverso)
Configure o Nginx como proxy reverso para a aplicação:
Terminal
# Crie arquivo de configuração
nano /etc/nginx/sites-available/nome-do-app
# Exemplo de vhost:
server {
listen 80;
server_name seu_dominio.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name seu_dominio.com;
ssl_certificate /etc/letsencrypt/live/seu_dominio.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/seu_dominio.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
}
# Habilitar e recarregar
ln -s /etc/nginx/sites-available/nome-do-app /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx
15 Emitir Certificado SSL com Let's Encrypt
Obtenha um certificado SSL gratuito para seu domínio:
Terminal
# Pare o Nginx (standalone)
systemctl stop nginx
# Emita certificado
certbot certonly --standalone -d seu_dominio.com --agree-tos --email [email protected]
# Inicie o Nginx
systemctl start nginx
# Verifique e recarregue
nginx -t && systemctl reload nginx
Certifique-se de que o domínio esteja apontando corretamente para o IP da VPS antes de solicitar o certificado SSL.
A1 Edição e Commit no GitHub
Para atualizar uma aplicação já implantada, comece editando o código:
- Abra o projeto no Cursor e faça suas alterações de código.
- Abra o terminal integrado (fundo preto, texto verde) usando o atalho Ctrl + ` (tecla crase).
- Execute os comandos Git:
Terminal
# Verifique o status do repositório
git status
# Adicione arquivos modificados
git add .
# Faça commit com mensagem descritiva
git commit -m "Detalhes da atualização"
# Envie para o GitHub
git push origin main
Um bom commit deve descrever claramente o que foi alterado. Ex: "Corrige bug de autenticação na tela de login".
A2 Conexão à VPS
Conecte-se ao servidor usando SSH:
Terminal
# Conecte-se à VPS via SSH
ssh root@SEU_IP_DA_VPS
A3 Atualizar Código e Reiniciar Serviço
Atualize o código na VPS e reinicie o serviço:
Terminal
# Acesse o diretório do projeto
cd /var/www/nome-do-app
# Puxe as últimas alterações do GitHub
git pull origin main
# Instale novas dependências (se houver)
npm install
# Atualize o Prisma (se necessário)
npx prisma migrate deploy
npx prisma generate
# Gere novo build
npm run build
# Reinicie a aplicação com PM2
pm2 restart nome-do-app
É sempre uma boa prática verificar os logs após uma atualização para garantir que tudo está funcionando corretamente. Use
pm2 logs para isso.
Glossário de Comandos Essenciais
Esta seção apresenta os comandos mais úteis para cada tecnologia utilizada no processo de deploy.
Git
| Comando | Descrição |
|---|---|
| git clone [url] | Clona um repositório remoto para sua máquina local |
| git pull | Atualiza seu repositório local com as alterações do repositório remoto |
| git add . | Adiciona todas as alterações para o próximo commit |
| git commit -m "mensagem" | Cria um novo commit com as alterações adicionadas |
| git push | Envia os commits locais para o repositório remoto |
| git status | Mostra o estado atual do repositório (arquivos modificados, etc.) |
| git branch | Lista todas as branches locais |
Prisma
| Comando | Descrição |
|---|---|
| npx prisma generate | Gera o cliente Prisma baseado no schema |
| npx prisma migrate dev | Cria e aplica migrações durante o desenvolvimento |
| npx prisma migrate deploy | Aplica migrações em ambiente de produção |
| npx prisma studio | Abre a interface visual para gerenciar dados |
| npx prisma db pull | Gera um schema a partir de um banco existente |
| npx prisma format | Formata o arquivo schema.prisma |
Linux
| Comando | Descrição |
|---|---|
| ls -la | Lista todos os arquivos (incluindo ocultos) com detalhes |
| cd [diretório] | Navega para o diretório especificado |
| mkdir [nome] | Cria um novo diretório |
| touch [arquivo] | Cria um arquivo vazio |
| rm [arquivo] | Remove um arquivo |
| rm -rf [diretório] | Remove um diretório recursivamente (cuidado!) |
| cp [origem] [destino] | Copia arquivos/diretórios |
| mv [origem] [destino] | Move ou renomeia arquivos/diretórios |
| cat [arquivo] | Exibe o conteúdo de um arquivo |
| nano [arquivo] | Edita um arquivo com o editor Nano |
PostgreSQL
| Comando | Descrição |
|---|---|
| sudo -u postgres psql | Acessa o terminal PostgreSQL como usuário postgres |
| \l | Lista todos os bancos de dados |
| \c [banco] | Conecta a um banco de dados específico |
| \dt | Lista todas as tabelas no banco conectado |
| \du | Lista todos os usuários |
| CREATE DATABASE [nome]; | Cria um novo banco de dados |
| CREATE USER [nome] WITH PASSWORD 'senha'; | Cria um novo usuário com senha |
| GRANT ALL PRIVILEGES ON DATABASE [banco] TO [usuário]; | Concede todas as permissões em um banco para um usuário |
| \q | Sai do terminal PostgreSQL |
PM2
| Comando | Descrição |
|---|---|
| pm2 start [script] | Inicia uma aplicação |
| pm2 start npm --name [nome] -- start | Inicia uma aplicação Node.js usando npm start |
| pm2 list | Lista todas as aplicações gerenciadas |
| pm2 stop [id|nome] | Para uma aplicação específica |
| pm2 restart [id|nome] | Reinicia uma aplicação específica |
| pm2 delete [id|nome] | Remove uma aplicação da gestão do PM2 |
| pm2 logs | Exibe logs de todas as aplicações |
| pm2 logs [id|nome] | Exibe logs de uma aplicação específica |
| pm2 monit | Abre um monitor em tempo real de todas as aplicações |
| pm2 save | Salva a lista atual de processos |
| pm2 startup | Gera e configura script para inicialização automática |
Nginx
| Comando | Descrição |
|---|---|
| systemctl start nginx | Inicia o serviço Nginx |
| systemctl stop nginx | Para o serviço Nginx |
| systemctl restart nginx | Reinicia o serviço Nginx |
| systemctl reload nginx | Recarrega a configuração sem interromper conexões |
| systemctl status nginx | Verifica o status do serviço Nginx |
| nginx -t | Testa a sintaxe da configuração |
| ls -la /etc/nginx/sites-available/ | Lista arquivos de configuração disponíveis |
| ls -la /etc/nginx/sites-enabled/ | Lista arquivos de configuração habilitados |
| ln -s /etc/nginx/sites-available/[arquivo] /etc/nginx/sites-enabled/ | Habilita um arquivo de configuração |
| cat /var/log/nginx/error.log | Exibe o log de erros do Nginx |