Entenda o Deploy de Node.js no Debian 12 com PM2

19 min de leitura  ·  Guia técnico

Deploy de Node.js no Debian 12 com PM2 é o processo de colocar uma aplicação Node.js em produção utilizando o gerenciador de processos PM2, garantindo que ela rode de forma contínua, resiliente e com reinicialização automática. Para realizar o fluxo completo, siga estes passos:

1. Instale o Node.js via NodeSource no Debian 12
2. Instale o PM2 globalmente com npm
3. Configure sua aplicação e inicie com PM2
4. Configure o PM2 para iniciar automaticamente no boot com pm2 startup
5. Instale e configure o Nginx como proxy reverso
6. Ative HTTPS com Certbot e teste o ambiente de produção

Pré-requisitos para o deploy de Node.js com PM2 no Debian 12

Antes de iniciar o processo de implantação, certifique-se de que os seguintes itens estão disponíveis e configurados corretamente no seu ambiente:

• Servidor Debian 12 (Bookworm) com acesso root ou usuário com privilégios sudo
• Node.js 20.x LTS ou superior (será instalado via NodeSource)
• npm 10.x incluído na instalação do Node.js
• PM2 5.x instalado globalmente via npm
• Nginx 1.22+ para atuar como proxy reverso
• Domínio apontado para o IP do servidor (necessário para configurar HTTPS)
• Porta 80 e 443 liberadas no firewall (UFW ou iptables)
• Acesso SSH ao servidor — veja o guia Acessando servidores VPS Linux da AviraHost se precisar de ajuda com a conexão

Instalando o Node.js no Debian 12 via NodeSource

O repositório oficial do Debian frequentemente disponibiliza versões desatualizadas do Node.js. Para garantir compatibilidade com aplicações modernas, utilize o repositório NodeSource, que oferece as versões LTS mais recentes diretamente.

Atualize os pacotes do sistema e instale as dependências necessárias:

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl gnupg2 ca-certificates lsb-release

Adicione o repositório NodeSource para o Node.js 20.x:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

Instale o Node.js:

sudo apt install -y nodejs

Verifique as versões instaladas:

node -v && npm -v

v20.18.0
10.8.2

Com o Node.js instalado corretamente, o próximo passo é instalar o PM2 para gerenciar os processos da aplicação em produção.

Instalando e configurando o PM2 no Debian 12

O PM2 é o gerenciador de processos mais utilizado em ambientes de produção Node.js. Ele mantém a aplicação em execução como daemon, monitora falhas, reinicia automaticamente e centraliza os logs — funcionalidades indispensáveis para qualquer deploy sério.

Instale o PM2 globalmente:

sudo npm install -g pm2

added 184 packages in 12s

Verifique a instalação:

pm2 -v

5.4.2

Agora, navegue até o diretório da sua aplicação. Para este guia, usaremos um exemplo em /var/www/minha-app:

mkdir -p /var/www/minha-app
cd /var/www/minha-app

Crie um arquivo de exemplo para testar o deploy:

cat > app.js << 'EOF'
const http = require("http");
const PORT = process.env.PORT || 3000;

const server = http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain" });
  res.end("Aplicacao Node.js rodando com PM2 no Debian 12\n");
});

server.listen(PORT, () => {
  console.log(`Servidor rodando na porta ${PORT}`);
});
EOF

Inicie a aplicação com PM2, atribuindo um nome descritivo ao processo:

pm2 start app.js --name "minha-app"

[PM2] Starting /var/www/minha-app/app.js in fork_mode (1 instance)
[PM2] Done.
┌────┬──────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┐
│ id │ name         │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │
├────┼──────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┤
│ 0  │ minha-app    │ default     │ N/A     │ fork    │ 12345    │ 0s     │ 0    │ online    │
└────┴──────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┘

Verifique o status da aplicação a qualquer momento com:

pm2 status

Para visualizar os logs em tempo real:

pm2 logs minha-app

Configurando o PM2 para iniciar automaticamente no boot do servidor

Uma das vantagens mais importantes do PM2 em produção é a capacidade de registrar um serviço systemd que reinicia todos os processos salvos automaticamente após um reboot do servidor Debian 12. Sem essa configuração, sua aplicação ficaria offline após qualquer reinicialização.

Gere o script de inicialização automática:

pm2 startup

O PM2 exibirá um comando que você deve copiar e executar com sudo. Ele terá um formato semelhante a:

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u seu-usuario --hp /home/seu-usuario

Atenção: copie e execute exatamente o comando exibido no seu terminal, pois ele é gerado com base no usuário e caminhos do seu sistema específico.

Após executar o comando gerado, salve o estado atual dos processos PM2:

pm2 save

[PM2] Saving current process list...
[PM2] Successfully saved in /home/seu-usuario/.pm2/dump.pm2

Para confirmar que o serviço systemd foi criado corretamente:

systemctl status pm2-seu-usuario

● pm2-seu-usuario.service - PM2 process manager
     Loaded: loaded (/etc/systemd/system/pm2-seu-usuario.service; enabled)
     Active: active (running)

A partir deste momento, sua aplicação Node.js será reiniciada automaticamente sempre que o servidor for reiniciado, sem qualquer intervenção manual.

Configurando o Nginx como proxy reverso para a aplicação Node.js

Expor diretamente a porta 3000 ao público não é uma prática recomendada em produção. O Nginx atua como proxy reverso, recebendo as requisições na porta 80 (HTTP) e 443 (HTTPS) e encaminhando-as para a aplicação Node.js na porta interna. Isso também permite hospedar múltiplas aplicações no mesmo servidor.

Instale o Nginx:

sudo apt install -y nginx

Crie um arquivo de configuração para o seu domínio:

sudo nano /etc/nginx/sites-available/minha-app

Insira o seguinte conteúdo, substituindo seudominio.com.br pelo seu domínio real:

server {
    listen 80;
    server_name seudominio.com.br www.seudominio.com.br;

    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_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Ative o site criando um link simbólico e teste a configuração do Nginx:

sudo ln -s /etc/nginx/sites-available/minha-app /etc/nginx/sites-enabled/
sudo nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Recarregue o Nginx para aplicar as mudanças:

sudo systemctl reload nginx

Para habilitar HTTPS com certificado gratuito Let's Encrypt, instale o Certbot:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d seudominio.com.br -d www.seudominio.com.br

O Certbot modificará automaticamente o arquivo de configuração do Nginx para redirecionar HTTP para HTTPS. Consulte também o artigo Como redirecionar um site http para https? para entender o processo de redirecionamento em detalhes.

Usando o modo cluster do PM2 para melhor performance

Para aplicações que precisam aproveitar todos os núcleos de CPU disponíveis no servidor, o PM2 oferece o modo cluster. Neste modo, múltiplas instâncias da aplicação são criadas automaticamente, distribuindo a carga entre os núcleos e aumentando a capacidade de processamento de requisições simultâneas.

Atenção: antes de ativar o modo cluster em produção, certifique-se de que sua aplicação é stateless ou utiliza um mecanismo de sessão compartilhado (como Redis), pois cada instância roda em um processo separado.

Para iniciar a aplicação em modo cluster utilizando todos os núcleos disponíveis:

pm2 delete minha-app
pm2 start app.js --name "minha-app" -i max

[PM2] Starting /var/www/minha-app/app.js in cluster_mode (4 instances)
[PM2] Done.
┌────┬──────────────┬─────────────┬─────────┬─────────┬──────────┬────────┬──────┬───────────┐
│ id │ name         │ namespace   │ version │ mode    │ pid      │ uptime │ ↺    │ status    │
├────┼──────────────┼─────────────┼─────────┼─────────┼──────────┼────────┼──────┼───────────┤
│ 0  │ minha-app    │ default     │ N/A     │ cluster │ 12346    │ 0s     │ 0    │ online    │
│ 1  │ minha-app    │ default     │ N/A     │ cluster │ 12347    │ 0s     │ 0    │ online    │
│ 2  │ minha-app    │ default     │ N/A     │ cluster │ 12348    │ 0s     │ 0    │ online    │
│ 3  │ minha-app    │ default     │ N/A     │ cluster │ 12349    │ 0s     │ 0    │ online    │
└────┴──────────────┴─────────────┴─────────┴─────────┴──────────┴────────┴──────┴───────────┘

Para atualizar a aplicação em produção sem interromper o serviço, utilize o reload gradual:

pm2 reload minha-app

Salve novamente o estado após qualquer alteração nos processos:

pm2 save

Para monitorar o consumo de CPU e memória de cada instância em tempo real, use o painel interativo do PM2:

pm2 monit

Gerenciando variáveis de ambiente e o arquivo ecosystem.config.js

Em ambientes de produção, hardcodar configurações diretamente no código é uma má prática. O PM2 suporta o arquivo ecosystem.config.js, que centraliza as configurações de inicialização, variáveis de ambiente e modo de execução de cada aplicação gerenciada.

Crie o arquivo de configuração no diretório da aplicação:

cat > /var/www/minha-app/ecosystem.config.js << 'EOF'
module.exports = {
  apps: [
    {
      name: "minha-app",
      script: "./app.js",
      instances: "max",
      exec_mode: "cluster",
      watch: false,
      max_memory_restart: "500M",
      env: {
        NODE_ENV: "development",
        PORT: 3000
      },
      env_production: {
        NODE_ENV: "production",
        PORT: 3000
      }
    }
  ]
};
EOF

Inicie a aplicação usando o arquivo ecosystem com o ambiente de produção:

pm2 start ecosystem.config.js --env production

A opção max_memory_restart instrui o PM2 a reiniciar automaticamente a instância caso ela ultrapasse 500 MB de uso de memória, prevenindo vazamentos de memória que poderiam derrubar o servidor. Consulte as Dicas de Otimização de Servidores Linux para complementar a configuração do seu ambiente.

Problemas comuns e como resolver

Sintoma: aplicação com status "errored" no pm2 status

Causa: a aplicação encontrou um erro fatal durante a inicialização ou em tempo de execução, como uma porta já em uso, variável de ambiente ausente ou erro de sintaxe no código.
Solução: execute pm2 logs minha-app --lines 50 para visualizar as últimas 50 linhas de log e identificar a mensagem de erro exata. Verifique se a porta configurada já está em uso com ss -tlnp | grep 3000. Corrija o problema no código ou configuração e execute pm2 restart minha-app.

Sintoma: Nginx retorna "502 Bad Gateway" após o deploy

Causa: o Nginx não consegue se conectar à aplicação Node.js na porta configurada. Isso ocorre quando a aplicação não está rodando, está escutando em uma porta diferente da configurada no proxy_pass, ou houve um erro de inicialização.
Solução: verifique se a aplicação está online com pm2 status. Confirme a porta em uso com ss -tlnp | grep node. Certifique-se de que o valor em proxy_pass no Nginx corresponde exatamente à porta da aplicação. Verifique os logs do Nginx com sudo tail -f /var/log/nginx/error.log.

Sintoma: aplicação não reinicia após reboot do servidor

Causa: o comando pm2 startup foi executado, mas o pm2 save não foi rodado em seguida, ou o serviço systemd não foi habilitado corretamente.
Solução: execute pm2 save para salvar o estado atual dos processos. Verifique se o serviço está habilitado com systemctl is-enabled pm2-seu-usuario. Se retornar disabled, habilite com sudo systemctl enable pm2-seu-usuario. Reinicie o servidor e confirme com pm2 status.

Sintoma: erro "EACCES: permission denied" ao iniciar a aplicação

Causa: a aplicação está tentando escutar em uma porta privilegiada (abaixo de 1024) sem permissões de root, ou o diretório da aplicação pertence a outro usuário.
Solução: configure a aplicação para usar portas acima de 1024 (como 3000, 8080) e deixe o Nginx fazer o proxy para as portas 80 e 443. Verifique a propriedade do diretório com ls -la /var/www/minha-app e ajuste com sudo chown -R seu-usuario:seu-usuario /var/www/minha-app.

Sintoma: alto consumo de memória com múltiplas instâncias em modo cluster

Causa: cada instância do Node.js em modo cluster consome memória independentemente. Em servidores com pouca RAM, iniciar com -i max pode esgotar os recursos disponíveis.
Solução: defina um número fixo de instâncias compatível com a RAM disponível, como -i 2 para servidores com 1-2 GB de RAM. Utilize a opção max_memory_restart no ecosystem.config.js para limitar o consumo por instância e configure alertas de monitoramento com pm2 monit.

Perguntas frequentes sobre deploy de Node.js com PM2

O PM2 reinicia a aplicação Node.js automaticamente após reboot do servidor?

Sim. Após executar pm2 startup e pm2 save, o PM2 registra um serviço systemd que reinicia todos os processos salvos automaticamente quando o servidor é reiniciado. Isso garante que sua aplicação Node.js volte ao ar sem intervenção manual. O serviço criado pode ser verificado com systemctl status pm2-seu-usuario.

Qual a diferença entre usar PM2 e rodar Node.js diretamente com 'node app.js'?

Rodar com node app.js diretamente encerra o processo quando a sessão SSH é fechada e não oferece reinicialização automática em caso de falha. O PM2 mantém o processo em execução como daemon, monitora falhas, reinicia automaticamente e fornece logs centralizados, sendo indispensável em ambientes de produção. Além disso, o PM2 oferece modo cluster, monitoramento de recursos e suporte a variáveis de ambiente por perfil.

Como verificar se a aplicação Node.js está rodando corretamente com PM2?

Execute pm2 status para ver o estado de todos os processos gerenciados. O campo status deve exibir online. Para ver os logs em tempo real, use pm2 logs nome-da-app. Se o status for errored, consulte os logs para identificar a causa raiz — geralmente um erro de inicialização, porta em uso ou dependência ausente.

É possível fazer deploy de múltiplas aplicações Node.js no mesmo servidor Debian 12?

Sim. Cada aplicação deve escutar em uma porta diferente (ex: 3000, 3001, 4000). O Nginx atua como proxy reverso, roteando requisições de domínios distintos para as portas correspondentes. O PM2 gerencia todos os processos de forma independente, com nomes distintos para cada aplicação. Basta criar um bloco server separado no Nginx para cada domínio e apontar o proxy_pass para a porta correta.

Como atualizar a aplicação Node.js em produção sem downtime com PM2?

Use o comando pm2 reload nome-da-app em vez de pm2 restart. O reload realiza uma reinicialização gradual (zero-downtime reload), mantendo pelo menos uma instância ativa enquanto as demais são reiniciadas. Para aplicações em modo cluster, isso é especialmente eficaz, pois o tráfego continua sendo atendido durante todo o processo de atualização.

Conclusão

O fluxo completo de deploy de Node.js no Debian 12 com PM2 cobre desde a instalação do runtime até a configuração de proxy reverso com Nginx e HTTPS. Com as configurações apresentadas neste guia, sua aplicação estará preparada para um ambiente de produção robusto e confiável.

• Configure o pm2 startup e pm2 save imediatamente após o primeiro deploy para garantir que a aplicação sobreviva a reboots do servidor sem intervenção manual.
• Utilize o arquivo ecosystem.config.js para centralizar configurações de ambiente, limites de memória e modo de execução, facilitando a manutenção e o versionamento das configurações de deploy.
• Monitore ativamente com pm2 monit e pm2 logs nos primeiros dias após o deploy para identificar gargalos de memória, erros recorrentes ou comportamentos inesperados antes que afetem os usuários finais.

Leia também

• Guia: Laravel não conecta ao MySQL no Debian 12
• Otimizar PHP 8.3 no Debian 12: OPcache, JIT e pool FPM
• Entenda TTFB de uma vez por todas (sem enrolação)

Precisa de ajuda com deploy de Node.js no seu servidor?

Configurar um ambiente de produção Node.js com PM2 e Nginx exige atenção a detalhes de segurança, performance e disponibilidade. Um VPS com recursos adequados e suporte especializado faz toda a diferença para manter sua aplicação estável.

Conheça os planos de VPS da AviraHost e hospede sua aplicação Node.js com desempenho e confiabilidade