Node.js: Primeiros passos

Saiba como implementar rapidamente e de forma segura um serviço Node.js na Stackhero

👋 Bem-vindo à documentação do Stackhero!

A Stackhero oferece uma solução Node.js cloud pronta a usar que proporciona uma série de benefícios, incluindo:

Implemente a sua aplicação em segundos com um simples git push.

Utilize o seu próprio nome de domínio e beneficie da configuração automática de certificados HTTPS para uma segurança reforçada.

Desfrute de tranquilidade com backups automáticos, atualizações com um clique, e preços simples, transparentes e previsíveis.

Obtenha desempenho ótimo e segurança robusta graças a uma VM privada e dedicada.

Poupe tempo e simplifique a sua vida: só leva 5 minutos para experimentar a solução de hospedagem cloud Node.js da Stackhero!

Implementar o seu serviço Node.js na Stackhero foi pensado para ser rápido, eficiente e fiável. Neste guia, iremos percorrer os passos essenciais para colocar a sua aplicação online em apenas alguns minutos, mantendo sempre a segurança e o desempenho como prioridades.

Iniciar um serviço Node.js

Para começar, vamos criar um serviço Node.js na Stackhero. Isto será a base para o deployment da sua aplicação e dará acesso a todas as vantagens do alojamento cloud da Stackhero.

Pré-requisitos

Antes de começar, certifique-se de que tem as seguintes ferramentas prontas:

Git: Pode descarregar em https://git-scm.com/downloads.
Utilizadores Windows: Para uma experiência mais fluida, recomenda-se utilizar o Windows Terminal, disponível na Microsoft Store.

Configurar o seu serviço

O principal passo de configuração é atualizar a sua chave pública SSH. Esta chave permite que a Stackhero aceda de forma segura ao seu repositório de código.

Para encontrar a sua chave pública, pode executar um dos seguintes comandos no seu terminal:

cat ~/.ssh/id_rsa.pub

cat ~/.ssh/id_ed25519.pub

Se ainda não tiver um par de chaves SSH, pode gerar um executando ssh-keygen no Linux ou macOS, ou ssh-keygen.exe no Windows.

Depois de obter a sua chave pública, aceda ao dashboard da Stackhero, selecione o seu serviço Node.js, vá à secção de configuração e cole a sua chave no campo indicado.

Tip: Se pretender que a sua chave pública SSH esteja disponível para todos os serviços futuros, pode defini-la globalmente. Basta aceder ao dashboard da Stackhero, clicar na sua foto de perfil (canto superior direito), ir a "O seu perfil" e colar aí a sua chave pública SSH.

Clonar o exemplo

Para facilitar o início, disponibilizamos uma aplicação Node.js de exemplo que demonstra como funciona o deployment na Stackhero. Pode clonar o repositório com estes comandos:

git clone https://github.com/stackhero-io/nodejsGettingStarted.git stackhero-nodejs-getting-started
cd stackhero-nodejs-getting-started

Configurar o repositório remoto

O deployment da sua aplicação via Git na Stackhero é simples. Na página principal do seu serviço, encontrará um comando para adicionar um remoto Git, semelhante a este:

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Pode copiar e colar este comando no seu terminal para configurar o remoto.

Implementar a sua aplicação Node.js

Para implementar, basta fazer push do seu código para a Stackhero com:

git push stackhero main

Na primeira vez que fizer push, ser-lhe-á pedido para confirmar a impressão digital da chave. Basta escrever "yes" para continuar.

Em poucos instantes, a sua aplicação estará online. Pode verificar o estado visitando o URL apresentado no dashboard da Stackhero (por exemplo, https://<XXXXXX>.stackhero-network.com).

E está feito, a sua aplicação está agora implementada.

Se precisar de fazer alterações, basta atualizar o ficheiro app.js, fazer commit e push das suas modificações:

git add -A .
git commit -m "Update app.js"
git push stackhero main

Implementar uma aplicação existente

Se já tem uma aplicação Node.js, pode adicionar o remoto Stackhero como descrito acima e implementar o seu código com:

git push stackhero main

Resolver o erro "failed to push some refs to '[...]'"

Se encontrar este erro:

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
(e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Isto significa que o seu repositório local está desatualizado em relação ao remoto. Pode forçar o push com:

git push -f stackhero main

Resolver o erro "src refspec main does not match any"

Se vir o seguinte ao fazer push:

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

Isto normalmente significa que o branch main não existe. Pode tentar fazer push do branch master em alternativa:

git push stackhero master

Resolver o erro "Everything up-to-date" ao fazer push

Se o Git indicar "Everything up-to-date" mas as suas alterações não forem implementadas, pode ser porque se esqueceu de fazer commit. Experimente executar:

git add -A .
git commit -m "A sua mensagem de commit"
git push stackhero main

Se não tiver alterações mas quiser forçar um deployment, pode criar um commit vazio:

git commit --allow-empty -m "Force update"
git push stackhero main

Implementar um branch diferente de main

Se quiser implementar um branch diferente de main, como por exemplo production, pode fazê-lo com:

git push stackhero production:main

Implementar uma tag

Se utiliza tags e pretende implementar uma tag específica (por exemplo, v1.0), execute:

git push stackhero 'v1.0^{}:main'

O ^{} garante que o commit associado à tag é enviado.

Reverter ou implementar um commit específico

Se precisar de implementar um commit específico, primeiro encontre o hash do commit com git log. Depois implemente-o com:

git push -f stackhero <HASH>:main

Implementar em múltiplos ambientes

Pode querer separar ambientes de produção e de staging. Para renomear o remoto atual de stackhero para stackhero-staging, execute:

git remote rename stackhero stackhero-staging

De seguida, crie um novo serviço Node.js no dashboard da Stackhero e adicione-o como stackhero-production:

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Depois pode implementar em cada ambiente com:

git push stackhero-production main

git push stackhero-staging main

Guardar a password da sua chave privada SSH no keychain do macOS

No macOS, pode ser-lhe pedida a password da sua chave SSH sempre que faz push de código. Para maior comodidade e segurança, pode guardá-la no keychain do macOS executando:

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

Este comando guarda a password da sua chave para que não seja novamente solicitado nos deployments futuros.

Gerir secrets

Ao trabalhar com ambientes de staging e produção, é fundamental gerir secrets como tokens ou passwords de forma segura. Em vez de guardar estes secrets no repositório, utilize variáveis de ambiente para maior segurança.

Pode adicionar variáveis de ambiente no dashboard da Stackhero e aceder-lhes no seu código Node.js. Por exemplo, se definir uma variável chamada mySecret, pode aceder-lhe assim na sua aplicação:

process.env.mySecret

Abrir outros ports de rede

Se a sua aplicação precisar de utilizar protocolos além de HTTP, pode abrir ports TCP ou UDP adicionais. Isto faz-se diretamente no dashboard da Stackhero, especificando o port de entrada público, o port de destino no seu serviço Node.js e o protocolo (TCP ou UDP).

Armazenar ficheiros

Para armazenar ficheiros de utilizador, como fotografias, recomenda-se utilizar uma solução de object storage. Isto permite-lhe partilhar ficheiros entre vários serviços e instâncias, mantendo o seu código separado dos dados. Recomendamos MinIO como uma solução rápida, simples e poderosa, compatível com o protocolo Amazon S3.

Se preferir armazenamento local, pode utilizar o armazenamento persistente disponível na sua instância Node.js. Este armazenamento encontra-se em /persistent/storage/.

ATENÇÃO: Guarde sempre os dados dentro da pasta /persistent/storage/.

Os dados guardados fora desta pasta podem ser perdidos se a sua instância reiniciar ou se fizer push de alterações de código.

Encerramento gracioso (graceful shutdown)

Quando implementa uma nova versão da sua aplicação, a versão anterior recebe um sinal de terminação antes de ser encerrada. Isto permite que a aplicação feche ligações à base de dados e termine outros serviços de forma controlada.

O sinal de terminação SIGTERM é enviado para a sua aplicação. Pode tratá-lo no seu código desta forma:

process.on('SIGTERM', () => {
  // Este log aparece no dashboard da Stackhero no separador "logs"
  console.info('SIGTERM signal received.');

  // Feche aqui as ligações à base de dados ou outros serviços
  // ...
});

Utilizar múltiplos núcleos de CPU

Por predefinição, o Node.js utiliza apenas um núcleo e uma thread. Para tirar partido de todos os núcleos de CPU disponíveis, pode usar a API cluster do Node.js. A documentação oficial está disponível aqui: https://nodejs.org/api/cluster.html.

Aqui está um exemplo simples que cria um servidor HTTP utilizando todos os CPUs disponíveis:

const cluster = require('cluster');
const http = require('http');
const cpusCount = require('os').cpus().length;

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  // Fork workers
  for (let i = 0; i < cpusCount; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`Worker ${worker.process.pid} died`);
  });
} else {
  // Os workers partilham qualquer ligação TCP, neste caso, um servidor HTTP
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}