Como Instalar Node.js e PM2 no Ubuntu: Um Guia Completo de Produção

Node.js é um runtime JavaScript assíncrono e orientado a eventos, construído sobre o motor V8 do Chrome, projetado para executar código JavaScript no lado do servidor com alto rendimento. PM2 é um gestor de processos de nível de produção para aplicações Node.js que fornece daemonização, recuperação automática de falhas, agregação de logs, balanceamento de carga em modo cluster e geração de scripts de inicialização — tudo a partir de uma única interface CLI.

Este guia abrange todos os métodos de instalação, opções de configuração e padrões operacionais necessários para executar aplicações Node.js de forma fiável no Ubuntu 20.04, 22.04 ou 24.04 LTS em ambiente de produção.

Pré-requisitos

Antes de prosseguir, confirme o seguinte:

• Sistema operativo: Ubuntu 20.04, 22.04 ou 24.04 LTS (servidor ou desktop)
• Privilégios de utilizador: `sudo` ou acesso root
• Acesso à rede: HTTPS de saída para descarregar pacotes e scripts
• curl instalado: Execute `sudo apt install curl -y` se ainda não estiver presente

Se estiver a executar isto num servidor cloud, um ambiente de VPS Hosting é o destino de implementação mais comum para cargas de trabalho Node.js, e tudo neste guia aplica-se diretamente.

Passo 1: Atualizar Pacotes do Sistema

Sincronize sempre o índice de pacotes e aplique as atualizações pendentes antes de instalar novo software. Metadados de pacotes desatualizados são uma fonte frequente de conflitos de dependências.

“`bash

sudo apt update

sudo apt upgrade -y

“`

Após a conclusão da atualização, reinicie se o kernel foi atualizado:

“`bash

sudo reboot

“`

Passo 2: Instalar Node.js — Escolher o Método Correto

Existem três métodos principais de instalação do Node.js no Ubuntu. Cada um tem compromissos distintos em termos de controlo de versão, isolamento e disponibilidade em todo o sistema.

Comparação de Métodos

Método 1: Instalar Node.js via NodeSource (Recomendado para Servidores)

O NodeSource mantém repositórios Debian/Ubuntu atualizados para cada linha de lançamento ativa do Node.js. Esta é a abordagem preferida para servidores de produção onde é necessária uma versão única e estável em todo o sistema.

Adicionar o repositório NodeSource para a versão LTS atual:

“`bash

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

“`

Este script executa várias ações: deteta a sua versão do Ubuntu, adiciona o repositório apt NodeSource apropriado, importa a chave de assinatura GPG e executa `apt-get update`. O sinalizador `-E` preserva as suas variáveis de ambiente ao escalar para sudo, o que é importante se tiver configurações de proxy.

Instalar Node.js e npm:

“`bash

sudo apt install nodejs -y

“`

O pacote NodeSource inclui tanto `node` como `npm` num único pacote `nodejs`. Ao contrário do pacote universe do Ubuntu, não os separa.

Verificar a instalação:

“`bash

node -v

npm -v

“`

Exemplo de saída esperada:

“`

v20.14.0

10.7.0

“`

Fixar numa versão principal específica: Se precisar do Node.js 18 em vez do LTS atual, substitua `setup_lts.x` por `setup_18.x` no comando curl. Os streams disponíveis incluem `setup_18.x`, `setup_20.x` e `setup_22.x`.

Método 2: Instalar Node.js via NVM (Recomendado para Desenvolvimento e Ambientes Multi-Versão)

O NVM (Node Version Manager) instala o Node.js no seu diretório home, não necessitando de privilégios root nem para o próprio Node.js nem para pacotes npm instalados globalmente. Isto elimina os problemas de permissões que surgem frequentemente ao executar `npm install -g` no Node.js instalado no sistema.

Instalar NVM:

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

“`

Verifique o repositório oficial do NVM para a tag de lançamento mais recente antes de executar este comando — o número de versão no URL muda a cada lançamento.

Recarregar o ambiente da shell:

“`bash

source ~/.bashrc

“`

Se utilizar Zsh, utilize `~/.zshrc` em vez disso. O instalador do NVM acrescenta o seu bloco de inicialização ao ficheiro de configuração da shell que detetar.

Instalar a versão LTS mais recente do Node.js:

“`bash

nvm install –lts

“`

Instalar uma versão específica juntamente com a LTS:

“`bash

nvm install 18

nvm install 20

“`

Alternar entre versões instaladas:

“`bash

nvm use 20

nvm alias default 20

“`

O comando `alias default` define a versão que é ativada em novas sessões de shell, o que é crítico para scripts e tarefas cron que não carregam o perfil interativo da shell.

Verificar:

“`bash

node -v

npm -v

“`

Problema crítico do NVM para produção: Como o NVM é de âmbito de utilizador, os scripts de inicialização e as unidades systemd do PM2 não terão acesso ao binário Node.js gerido pelo NVM a menos que configure explicitamente o caminho. Consulte o Passo 5 para saber como lidar com isto corretamente.

Passo 3: Instalar PM2

O PM2 é distribuído como um pacote npm e deve ser instalado globalmente para que a sua CLI esteja disponível em todo o sistema.

Instalar PM2:

“`bash

sudo npm install -g pm2

“`

Se instalou o Node.js via NVM, omita `sudo`:

“`bash

npm install -g pm2

“`

Verificar a instalação:

“`bash

pm2 -v

“`

Instalar uma versão específica do PM2 (útil ao fixar infraestrutura):

“`bash

sudo npm install -g pm2@5.3.1

“`

A versão 5.x do PM2 é a linha estável atual. Introduziu melhorias significativas no painel web (pm2 plus), rotação de logs e sistema de módulos em comparação com a v4.

Passo 4: Gerir Aplicações Node.js com PM2

Iniciar uma Aplicação

Navegue até ao diretório da sua aplicação e inicie-a:

“`bash

cd /var/www/my-app

pm2 start app.js –name "my-app"

“`

Atribua sempre um sinalizador `–name`. Sem ele, o PM2 usa o nome do ficheiro como nome do processo, o que se torna ambíguo quando tem múltiplos serviços.

Iniciar com opções adicionais:

“`bash

pm2 start app.js –name "my-app" –watch –max-memory-restart 300M

“`

• `–watch`: Reinicia o processo quando os ficheiros de origem mudam (útil em staging, não recomendado em produção)
• `–max-memory-restart 300M`: Reinicia automaticamente o processo se exceder 300 MB de memória RSS — uma salvaguarda crítica contra fugas de memória

Ver Processos em Execução

“`bash

pm2 list

“`

Isto apresenta uma tabela com ID do processo, nome, modo (fork/cluster), PID, estado, utilização de CPU, consumo de memória e contagem de reinícios.

Para um painel em tempo real:

“`bash

pm2 monit

“`

Controlar Processos

“`bash

pm2 restart my-app # Graceful restart

pm2 reload my-app # Zero-downtime reload (cluster mode only)

pm2 stop my-app # Stop without removing from process list

pm2 delete my-app # Stop and remove from process list

“`

A diferença entre `restart` e `reload`: `restart` termina o processo e inicia um novo, causando uma breve interrupção. `reload` (disponível apenas em modo cluster) alterna os workers um de cada vez, mantendo a disponibilidade durante todo o processo. Utilize sempre `reload` em implementações de cluster em produção.

Gestão de Logs

“`bash

pm2 logs # Stream logs from all processes

pm2 logs my-app # Stream logs for a specific process

pm2 logs my-app –lines 200 # Show last 200 lines

pm2 flush # Clear all log files

“`

O PM2 armazena logs em `~/.pm2/logs/` por padrão. Para servidores de produção, instale o módulo de rotação de logs para evitar o esgotamento do disco:

“`bash

pm2 install pm2-logrotate

pm2 set pm2-logrotate:max_size 50M

pm2 set pm2-logrotate:retain 10

pm2 set pm2-logrotate:compress true

“`

Isto roda os logs quando atingem 50 MB, retém 10 arquivos comprimidos e evita o crescimento descontrolado de logs — um problema comum em servidores de longa duração que é frequentemente ignorado até o espaço em disco esgotar.

Passo 5: Configurar o PM2 para Iniciar no Arranque do Sistema

O PM2 deve ser configurado para sobreviver a reinícios do servidor. Isto é tratado através de uma unidade de serviço systemd gerada pelo próprio PM2.

Gerar o comando de inicialização:

“`bash

pm2 startup

“`

O PM2 irá apresentar um comando adaptado ao seu sistema init e utilizador atual. Tem este aspeto:

“`

[PM2] Init System found: systemd

[PM2] To setup the Startup Script, copy/paste the following command:

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

“`

Copie e execute esse comando exato. Não o modifique — o caminho para o binário PM2 e o diretório home devem corresponder à configuração do seu sistema.

Configuração de inicialização específica para NVM: Se instalou o Node.js via NVM, o caminho no comando gerado apontará para o seu binário gerido pelo NVM. Isto está correto, mas deve garantir que a versão NVM está definida como padrão antes de executar `pm2 startup`:

“`bash

nvm alias default 20

pm2 startup

“`

Guardar a lista de processos atual:

“`bash

pm2 save

“`

Isto escreve a lista de processos em `~/.pm2/dump.pm2`. No reinício, a unidade systemd lê este ficheiro e restaura todos os processos guardados. Se adicionar ou remover aplicações posteriormente, execute `pm2 save` novamente para atualizar o snapshot.

Verificar se a unidade systemd está ativa:

“`bash

systemctl status pm2-ubuntu

“`

Substitua `ubuntu` pelo seu nome de utilizador real.

Passo 6: Implementação em Produção com Ficheiros de Ecossistema PM2

Para qualquer coisa além de uma aplicação de script único, utilize o ficheiro de configuração de ecossistema do PM2. Fornece definições de processos reproduzíveis e controladas por versão, eliminando a necessidade de memorizar longos sinalizadores CLI.

Gerar o Ficheiro de Ecossistema

“`bash

pm2 ecosystem

“`

Isto cria `ecosystem.config.js` no diretório atual.

Uma Configuração de Ecossistema Pronta para Produção

“`javascript

module.exports = {

apps: [

{

name: 'api-server',

script: './src/server.js',

instances: 'max',

exec_mode: 'cluster',

watch: false,

max_memory_restart: '500M',

log_date_format: 'YYYY-MM-DD HH:mm:ss Z',

error_file: '/var/log/pm2/api-server-error.log',

out_file: '/var/log/pm2/api-server-out.log',

merge_logs: true,

env: {

NODE_ENV: 'development',

PORT: 3000

},

env_production: {

NODE_ENV: 'production',

PORT: 8080

}

},

{

name: 'worker',

script: './src/worker.js',

instances: 2,

exec_mode: 'fork',

cron_restart: '0 2 * * *',

env_production: {

NODE_ENV: 'production'

}

}

]

};

“`

Decisões de configuração chave explicadas:

• `instances: 'max'`: O PM2 cria automaticamente um worker por núcleo de CPU lógico. Num servidor de 4 núcleos, isto cria 4 processos Node.js, utilizando totalmente o hardware.
• `exec_mode: 'cluster'`: Utiliza o módulo cluster nativo do Node.js. Todas as instâncias partilham a mesma porta através do balanceamento de carga de socket do sistema operativo.
• `exec_mode: 'fork'`: Executa o processo como um processo filho autónomo. Necessário para aplicações que não são servidores HTTP (workers de fila, tarefas agendadas, servidores WebSocket com sessões fixas).
• `merge_logs: true`: Combina o stdout de todas as instâncias do cluster num único ficheiro de log, tornando a análise de logs significativamente mais fácil.
• `cron_restart`: Agenda reinícios automáticos usando sintaxe cron. Útil para workers que acumulam estado ou para aplicar alterações de configuração noturnas.

Iniciar com o Ficheiro de Ecossistema

“`bash

pm2 start ecosystem.config.js –env production

pm2 save

“`

Fluxo de Trabalho de Implementação sem Tempo de Inatividade

Ao implementar uma nova versão da sua aplicação:

“`bash

git pull origin main

npm install –production

pm2 reload ecosystem.config.js –env production

“`

`pm2 reload` envia um `SIGINT` a cada worker um de cada vez, aguarda que o novo worker fique pronto e depois termina o antigo. A sua aplicação deve tratar `SIGINT` de forma elegante e sinalizar prontidão usando `process.send('ready')` para que isto funcione corretamente.

Gestor de encerramento elegante na sua aplicação:

“`javascript

process.on('SIGINT', () => {

server.close(() => {

console.log('HTTP server closed');

process.exit(0);

});

});

“`

Passo 7: Monitorização e Observabilidade do PM2

Monitorização Integrada

“`bash

pm2 monit

“`

Apresenta gráficos de CPU e memória em tempo real para cada processo no terminal.

Informação do Processo

“`bash

pm2 show my-app

“`

Apresenta metadados detalhados: tempo de atividade, contagem de reinícios, versionamento, caminho do interpretador, variáveis de ambiente e localizações dos ficheiros de log.

Painel Web PM2 (PM2 Plus)

O PM2 oferece um painel de monitorização alojado em pm2.io. Ligue o seu servidor:

“`bash

pm2 link <secret_key> <public_key>

“`

Isto fornece métricas históricas, alertas e gestão remota de processos — particularmente valioso ao gerir múltiplos servidores ou quando necessita de visibilidade sem acesso SSH.

Passo 8: Atualizar Node.js e PM2

Atualizar PM2

“`bash

sudo npm install -g pm2@latest

pm2 update

“`

`pm2 update` é essencial após atualizar o binário PM2 — atualiza o daemon PM2 em memória sem interromper os processos em execução.

Atualizar Node.js via NodeSource

Re-execute o script de configuração para a nova versão principal:

“`bash

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

sudo apt install nodejs -y

“`

Após atualizar o Node.js, reinicie o PM2 para garantir que utiliza o novo binário:

“`bash

pm2 restart all

“`

Atualizar Node.js via NVM

“`bash

nvm install 22

nvm alias default 22

nvm use 22

pm2 restart all

“`

Se alterou a versão padrão do NVM, regenere o script de inicialização do PM2 para atualizar o caminho do binário na unidade systemd:

“`bash

pm2 unstartup

pm2 startup

pm2 save

“`

Considerações de Reforço de Segurança

Executar aplicações Node.js em produção requer atenção além da gestão de processos:

• Executar como utilizador não-root: Nunca execute PM2 ou Node.js como root. Crie um utilizador de sistema dedicado (`adduser –system –group nodeapp`) e execute o PM2 sob essa conta.
• Gestão de variáveis de ambiente: Não codifique segredos em `ecosystem.config.js`. Utilize um ficheiro `.env` carregado via `dotenv`, ou injete segredos através do seu pipeline de implementação. O ficheiro de ecossistema é tipicamente submetido ao controlo de versão.
• Proxy reverso: Coloque Nginx ou Caddy à frente da sua aplicação Node.js. Isto trata da terminação TLS, servindo ficheiros estáticos, limitação de taxa e buffering de pedidos. Combine isto com uma solução de Certificados SSL para impor HTTPS.
• Regras de firewall: Bloqueie o acesso direto à porta do seu Node.js (ex.: 3000, 8080) a partir da internet pública. Apenas o proxy reverso deve comunicar com o Node.js.
• Limites de recursos: Defina `max_memory_restart` no PM2 e configure valores `ulimit` ao nível do sistema para evitar que um único processo descontrolado desestabilize o servidor.

Para implementações de produção de alto tráfego onde o isolamento de recursos é crítico, um ambiente de Servidores Dedicados fornece controlo total do hardware e elimina o problema de vizinho ruidoso inerente à infraestrutura partilhada.

Escolher o Ambiente de Alojamento Correto para Node.js

Lista de Verificação de Decisões Técnicas

Utilize esta lista de verificação antes de implementar Node.js e PM2 em produção:

• [ ] Node.js instalado via NodeSource (servidor) ou NVM (desenvolvimento) — não o pacote universe do Ubuntu
• [ ] PM2 instalado globalmente com as permissões corretas para o seu método de instalação
• [ ] Aplicação iniciada com o sinalizador `–name` e um limiar `–max-memory-restart` definido
• [ ] Modo cluster ativado para servidores HTTP; modo fork utilizado para workers em segundo plano
• [ ] `pm2 startup` executado e o comando gerado executado com sudo
• [ ] `pm2 save` executado após todos os processos estarem configurados
• [ ] Módulo de rotação de logs instalado e configurado
• [ ] Nginx ou Caddy configurado como proxy reverso com TLS
• [ ] Aplicação trata `SIGINT` de forma elegante para recarregamentos sem tempo de inatividade
• [ ] Segredos geridos fora de `ecosystem.config.js`
• [ ] Unidade systemd PM2 verificada com `systemctl status pm2-<username>`
• [ ] Firewall bloqueia acesso direto às portas Node.js a partir da internet pública

FAQ

Qual é a diferença entre o modo fork e o modo cluster do PM2?

O modo fork cria a aplicação como um único processo filho — uma instância, um núcleo de CPU utilizado. O modo cluster utiliza o módulo cluster nativo do Node.js para criar múltiplos processos worker que partilham todos a mesma porta TCP, permitindo a utilização real de múltiplos núcleos e recarregamentos sem tempo de inatividade. Utilize o modo cluster para servidores HTTP/HTTPS e o modo fork para workers, tarefas cron ou aplicações que mantêm estado interno incompatível com partilha multi-processo.

Por que razão o PM2 não reinicia após um reinício do servidor mesmo tendo executado `pm2 startup`?

A causa mais comum é que `pm2 save` não foi executado após configurar os processos, pelo que o ficheiro dump está vazio ou em falta. A segunda causa mais comum é uma incompatibilidade de caminho NVM: se a versão padrão do NVM foi alterada após gerar o script de inicialização, a unidade systemd aponta para um binário inexistente. Resolva isto executando `pm2 unstartup`, definindo o padrão NVM correto e depois re-executando `pm2 startup` e `pm2 save`.

O PM2 pode gerir processos não-Node.js?

Sim. O PM2 pode gerir qualquer executável especificando o interpretador. Por exemplo: `pm2 start script.py –interpreter python3`. Isto torna o PM2 útil como supervisor de processos de uso geral para arquiteturas de microsserviços de linguagem mista.

Como executo múltiplas aplicações Node.js em portas diferentes atrás de um único servidor?

Defina cada aplicação como uma entrada separada em `ecosystem.config.js` com variáveis de ambiente `PORT` distintas. Configure o Nginx como proxy reverso com blocos `server` separados ou diretivas `location` a encaminhar para cada porta. Todas as aplicações partilham o mesmo daemon PM2 e são geridas através de uma única vista `pm2 list`.

Devo utilizar NVM ou NodeSource para um VPS de produção?

O NodeSource é geralmente preferível para servidores de produção. Instala o Node.js como um pacote de sistema, tornando-o disponível para todos os utilizadores e serviços do sistema sem dependências de inicialização de shell. O modelo de ativação por utilizador e por shell do NVM introduz modos de falha subtis em unidades systemd, tarefas cron e pipelines CI/CD que são executados fora de uma sessão de shell interativa. Reserve o NVM para máquinas de desenvolvimento local onde gerir múltiplas versões do Node.js simultaneamente é um requisito genuíno.