A começar em Heroku com Node.js

Introdução

Este tutorial vai permitir-lhe implantar uma aplicação Node.js em Heroku em minutos.

Espere mais alguns minutos para aprender como tirar o máximo partido da plataforma de Heroku.

O tutorial assume que tem uma conta Heroku gratuita, e que tem o Node.js e npm instalado localmente.

Configurar

O Heroku CLI requer o Git, o popular sistema de controlo de versões. Se ainda não tiver Git instalado, complete o seguinte antes de prosseguir:

  • Instalação de Git
  • First-time Git setup

Neste passo, instalará a Interface de Linha de Comando de Heroku (CLI). Utiliza o CLI para gerir e escalonar as suas aplicações, adicionar provisões, ver os seus registos de aplicações, e executar a sua aplicação localmente.

p>Download e execute o instalador da sua plataforma:

apple logomacOS

Descarregue o instalador

Também disponível via Homebrew:

$ brew install heroku/brew/heroku

logótipo do WindowsWindows

Downloader o instalador apropriado para a sua instalação Windows:

instalador 64-bit

instalador 32-bit

logótipo doubuntuUbuntu 16+

Executar o seguinte a partir do seu terminal:

$ sudo snap install heroku --classic

Snap também está disponível noutros sistemas operativos Linux.

Quando a instalação estiver concluída, pode usar o comando heroku do seu terminal.

No Windows, inicie o Prompt de Comando (cmd.exe) ou Powershell para aceder ao comando shell.

Utiliza o comando heroku login para entrar no CLI:

$ heroku loginheroku: Press any key to open up the browser to login or q to exit › Warning: If browser does not open, visit › https://cli-auth.heroku.com/auth/browser/***heroku: Waiting for login...Logging in... doneLogged in as [email protected]

Este comando abre o seu navegador web para a página de início de sessão de Heroku. Se o seu navegador já estiver ligado a Heroku, basta clicar no botão Log in exibido na página.

Esta autenticação é necessária tanto para os comandos heroku como git para funcionar correctamente.

se estiver atrás de uma firewall que requer o uso de um proxy para se ligar a serviços HTTP/HTTPS externos, pode definir o comando HTTP_PROXY ou HTTPS_PROXY variáveis de ambiente no seu ambiente de desenvolvimento local antes de executar o comando heroku.

Antes de continuar, verifique se tem os pré-requisitos instalados correctamente. Digite cada comando abaixo e certifique-se de que exibe a versão que tem instalada. (As suas versões podem ser diferentes do exemplo.) Se nenhuma versão for devolvida, volte à introdução deste tutorial e instale os pré-requisitos.

Todos os seguintes passos de configuração local serão necessários para completar o “Declare app dependencies” e os passos subsequentes.

Este tutorial funcionará para qualquer versão do Nó maior que 10 – verifique se está lá:

$ node --versionv14.15.4

npm está instalado com Nó, por isso verifique se está lá. Se não o tiver, instale uma versão mais recente do Nó:

$ npm --version6.14.11

Agora verifique se tem git instalado. Se não, instale-o e teste novamente.

$ git --versiongit version 2.28.0

Prepare o aplicativo

Neste passo, irá preparar uma aplicação de amostra que está pronta para ser implantada em Heroku.

Se é novo em Heroku, recomenda-se que complete este tutorial usando a aplicação de amostra fornecida por Heroku.

No entanto, se tiver a sua própria aplicação existente que pretende implementar em vez disso, veja este artigo para aprender a prepará-la para a implementação de Heroku.

Para clonar uma versão local da aplicação de amostra que pode então implementar em Heroku, execute os seguintes comandos na sua shell ou terminal de comando local:

$ git clone https://github.com/heroku/node-js-getting-started.git$ cd node-js-getting-started

Tem agora um repositório Git funcional que contém uma aplicação simples bem como um ficheiro package.json, que é utilizado pelo gestor de dependências do Node.

Desdobrar a aplicação

Neste passo, você irá desdobrar a aplicação para Heroku.

Criar uma aplicação em Heroku, que prepara Heroku para receber o seu código fonte.

$ heroku createCreating sharp-rain-871... done, stack is heroku-18http://sharp-rain-871.herokuapp.com/ | https://git.heroku.com/sharp-rain-871.gitGit remote heroku added

Quando cria uma aplicação, um git remoto (chamado heroku) é também criado e associado ao seu repositório local de git.

Heroku gera um nome aleatório (neste caso sharp-rain-871) para a sua aplicação, ou pode passar um parâmetro para especificar o seu próprio nome de aplicação.

Agora aplique o seu código:

$ git push heroku mainCounting objects: 488, done.Delta compression using up to 8 threads.Compressing objects: 100% (367/367), done.Writing objects: 100% (488/488), 231.85 KiB | 115.92 MiB/s, done.Total 488 (delta 86), reused 488 (delta 86)remote: Compressing source files... done.remote: Building source:remote:remote: -----> Node.js app detectedremote:remote: -----> Creating runtime environmentremote:remote: NPM_CONFIG_LOGLEVEL=errorremote: NODE_VERBOSE=falseremote: NODE_ENV=productionremote: NODE_MODULES_CACHE=trueremote:remote: -----> Installing binariesremote: engines.node (package.json): 14.xremote: engines.npm (package.json): unspecified (use default)remote:remote: Resolving node version 14.x...remote: Downloading and installing node 14.15.4...remote: Using default npm version: 6.14.11 ....remote: -----> Build succeeded!remote: -----> Discovering process typesremote: Procfile declares types -> webremote:remote: -----> Compressing...remote: Done: 19Mremote: -----> Launching...remote: Released v3remote: http://sharp-rain-871.herokuapp.com deployed to Herokuremote:remote: Verifying deploy... done.To https://git.heroku.com/nameless-savannah-4829.git * main -> main

A aplicação está agora implementada. Certifique-se de que pelo menos uma instância da aplicação está em execução:

$ heroku ps:scale web=1

Agora visite a aplicação na URL gerada pelo seu nome de aplicação. Como um atalho útil, pode abrir o website da seguinte forma:

$ heroku open

Ver logs

Heroku trata os logs como fluxos de eventos ordenados pelo tempo agregados a partir dos fluxos de saída de todos os componentes da sua aplicação e Heroku, fornecendo um único canal para todos os eventos.

Ver informação sobre a sua aplicação em execução usando um dos comandos de registo, heroku logs --tail:

$ heroku logs --tail2011-03-10T10:22:30-08:00 heroku: State changed from created to starting2011-03-10T10:22:32-08:00 heroku: Running process with command: `npm start`2011-03-10T10:22:33-08:00 heroku: Listening on 183202011-03-10T10:22:34-08:00 heroku: State changed from starting to up

Visitar novamente a sua aplicação no browser, e verá gerada outra mensagem de registo.

Imprimir Control+C para parar a transmissão dos logs.

Definir um Procfile

Utilizar um Procfile, um ficheiro de texto no directório raiz da sua aplicação, para declarar explicitamente que comando deve ser executado para iniciar a sua aplicação.

O Procfile no exemplo da aplicação que implementou parece-se com isto:

web: npm start

Esta declara um único tipo de processo, web, e o comando necessário para o executar. O nome web é importante aqui. Declara que este tipo de processo será anexado à pilha de encaminhamento HTTP de Heroku, e receberá tráfego web quando implantado. Este comando utilizará o start script que é especificado no package.json.

Perfis pode conter tipos de processo adicionais. Por exemplo, pode declarar um para um processo de trabalhador de fundo que processa itens fora de uma fila.

escala a aplicação

direita agora, a sua aplicação está a correr num único dino da web. Pense num dyno como um recipiente leve que executa o comando especificado no Procfile.

Pode verificar quantos dynos estão a correr utilizando o ps comando:

$ heroku ps=== web (Free): `npm start`web.1: up 2014/04/25 16:26:38 (~ 1s ago)

Por defeito, a sua aplicação é implantada num dyno livre. Os dinos livres dormirão após meia hora de inactividade (se não receberem qualquer tráfego). Isto provoca um atraso de alguns segundos para o primeiro pedido ao acordar. Os pedidos subsequentes terão um desempenho normal. Os dinos livres também consomem de uma quota mensal, ao nível de conta, de horas de dino livre – enquanto a quota não for esgotada, todas as aplicações livres podem continuar a funcionar.

Para evitar o sono dos dinos livres, pode passar a ser um passatempo ou tipo de dino profissional como descrito no artigo Dyno Types. Por exemplo, se migrar a sua aplicação para um dyno profissional, pode facilmente escalá-la executando um comando dizendo a Heroku para executar um número específico de dinos, cada um executando o seu tipo de processo web.

Escalar uma aplicação em Heroku é equivalente a alterar o número de dinos que estão em execução. Aumente o número de dinos da web para zero:

$ heroku ps:scale web=0

Acesso à aplicação de novo pressionando refresh na aba web, ou heroku open para a abrir numa aba web. Receberá uma mensagem de erro porque já não tem nenhum dínamo web disponível para servir pedidos.

escala novamente:

$ heroku ps:scale web=1

Para prevenção de abusos, escalar uma aplicação não livre para mais do que um dínamo requer verificação de conta.

Declarar dependências de aplicações

Heroku reconhece uma aplicação como Node.js pela existência de um ficheiro package.json no directório raiz. Para as suas próprias aplicações, pode criar uma executando npm init --yes.

A aplicação demo que implantou já tem um package.json, e parece-se com isto:

{ "name": "node-js-getting-started", "version": "0.3.0", ... "engines": { "node": "14.x" }, "dependencies": { "ejs": "^3.1.5", "express": "^4.17.1" }, ...}

O ficheiro package.json determina tanto a versão do Nó.js que será usado para executar a sua aplicação em Heroku, bem como as dependências que devem ser instaladas com a sua aplicação.

Executar este comando no seu directório local para instalar as dependências, preparando o seu sistema para executar a aplicação localmente:

$ npm installadded 132 packages in 3.368s

Once dependencies are installed, you will be ready to run your app locally. Notará que um ficheiro package-lock.json é gerado quando npm install é executado. Certifique-se de verificar isto no git. Quando dependências subsequentes são adicionadas, npm fará alterações a este ficheiro, por isso certifique-se de adicionar também essas alterações ao git.

Quando uma aplicação é implementada, Heroku lê o package.json para instalar a versão apropriada do nó e o package-lock.json para instalar as dependências.

Executar a aplicação localmente

Inicie agora a sua aplicação localmente utilizando o comando heroku local, que foi instalado como parte do CLI de Heroku:

$ heroku local web Loaded ENV .env File as KEY=VALUE Format1:23:15 PM web.1 | Node app is running on port 5000

Apenas como Heroku, heroku local examina o Procfile para determinar o que deve executar.

p>Abrir http://localhost:5000 com o seu web browser. Deverá ver a sua aplicação a correr localmente.

Para impedir a aplicação de correr localmente, no CLI, prima CtrlC para sair.

Push local changes

Neste passo aprenderá como propagar uma alteração local à aplicação através de Heroku. Como exemplo, irá modificar a aplicação para adicionar uma dependência adicional e o código para a utilizar.

Begin adicionando uma dependência para cool-ascii-faces em package.json. Execute o seguinte comando para fazer isto:

$ npm install cool-ascii-faces+ [email protected] 9 packages in 2.027s

Modificar index.js para que requires este módulo no início. Acrescentar também uma nova rota (/cool) que o utilize. O seu código final deve ser parecido com isto:

const cool = require('cool-ascii-faces');const express = require('express');const path = require('path');const PORT = process.env.PORT || 5000;express() .use(express.static(path.join(__dirname, 'public'))) .set('views', path.join(__dirname, 'views')) .set('view engine', 'ejs') .get('/', (req, res) => res.render('pages/index')) .get('/cool', (req, res) => res.send(cool())) .listen(PORT, () => console.log(`Listening on ${ PORT }`));

Now test locally:

$ npm install$ heroku local

Visitar a sua aplicação em http://localhost:5000/cool, deve ver caras bonitas exibidas em cada actualização: ( ⚆ _ ⚆ ).

p>Agora implantar. Quase todas as implantações em Heroku seguem este mesmo padrão. Primeiro, adicionar os ficheiros modificados ao repositório local git:

$ git add .

Agora submeta as alterações ao repositório:

$ git commit -m "Add cool face API"

Agora desdobre, tal como fez anteriormente:

$ git push heroku main

Finalmente, verifique se tudo está a funcionar:

$ heroku open cool

Você deve ver outra face.

Adicionar add-ons

Adicionar-ons são serviços de nuvens de terceiros que fornecem serviços adicionais prontos a usar para a sua aplicação, desde a persistência até à monitorização e mais.

Por defeito, Heroku armazena 1500 linhas de logs da sua aplicação. No entanto, disponibiliza o fluxo de registo completo como um serviço – e vários fornecedores de add-on têm serviços de registo escritos que fornecem coisas tais como persistência de registo, pesquisa, e alertas de e-mail e SMS.

Neste passo irá fornecer um destes add-ons de registo, Papertrail.

Prover o add-on de registo Papertrail:

$ heroku addons:create papertrailAdding papertrail on sharp-rain-871... done, v4 (free)Welcome to Papertrail. Questions and ideas are welcome ([email protected]). Happy logging!Use `heroku addons:docs papertrail` to view documentation.

Para ajudar na prevenção de abusos, o aprovisionamento de um add-on requer verificação de conta. Se a sua conta não tiver sido verificada, será direccionado para visitar o sítio de verificação.

O add-on está agora implementado e configurado para a sua aplicação. Pode listar add-ons para a sua aplicação como so:

$ heroku addons

Para ver este add-on específico em acção, visite o URL de Heroku da sua aplicação algumas vezes. Cada visita irá gerar mais mensagens de registo, que devem agora ser encaminhadas para o add-on papertrail. Visite a consola Papertrail para ver as mensagens de registo:

$ heroku addons:open papertrail

O seu navegador irá abrir uma consola Web Papertrail, mostrando os últimos eventos de registo. A interface permite-lhe pesquisar e configurar alertas:

Tela de consola

Iniciar uma consola

Para obter uma sensação real de como os dinos funcionam, pode criar outro dino único e executar o comando bash, que abre uma concha nesse dino. Pode então executar comandos ali. Cada dino tem o seu próprio espaço de ficheiros efémero, preenchido com a sua aplicação e as suas dependências – uma vez concluído o comando (neste caso, bash), o dino é removido.

$ heroku run bashRunning `bash` attached to terminal... up, run.3052~ $ lsProcfile README.md package.json package-lock.json src tests~ $ exitexit

Se receber um erro, Error connecting to process, então poderá ter de configurar a sua firewall.

Não se esqueça de escrever exit para sair da shell e terminar o dyno.

Definir config vars

Heroku permite-lhe externalizar a configuração – armazenando dados tais como chaves de encriptação ou endereços de recursos externos em config vars.

Em tempo de execução, as config vars são expostas como variáveis de ambiente à aplicação. Por exemplo, modificar index.js de modo a introduzir uma nova rota, /times, que repete uma acção dependendo do valor da variável de ambiente TIMES. Sob a existente get() call, adicionar outra:

.get('/times', (req, res) => res.send(showTimes()))

No fim do ficheiro, adicionar a seguinte definição para a nova função, showTimes():

showTimes = () => { let result = ''; const times = process.env.TIMES || 5; for (i = 0; i < times; i++) { result += i + ' '; } return result;}

heroku local irá automaticamente configurar o ambiente com base no conteúdo do ficheiro .env no seu directório local. No directório de nível superior do seu projecto, já existe um ficheiro .env que tem o seguinte conteúdo:

TIMES=2

Se executar a aplicação com heroku local, verá que serão gerados dois números de cada vez.

Para definir a config var em Heroku, execute o seguinte:

$ heroku config:set TIMES=2

Veja as config vars que são definidas usando heroku config:

$ heroku config== sharp-rain-871 Config VarsPAPERTRAIL_API_TOKEN: erdKhPeeeehIcdfY7neTIMES: 2

Disponibilize a sua aplicação alterada para Heroku e depois visite-a correndo heroku open times.

Prover uma base de dados

O mercado add-on tem um grande número de armazéns de dados, desde fornecedores Redis e MongoDB, até Postgres e MySQL. Neste passo, irá adicionar uma base de dados gratuita do Postgres Postgres Starter Tier Dev Dev à sua app.

Adicionar a base de dados:

$ heroku addons:create heroku-postgresql:hobby-devAdding heroku-postgresql:hobby-dev... done, v3 (free)

Isto cria uma base de dados, e define uma variável de ambiente DATABASE_URL (pode verificar executando heroku config).

Utilizar npm para adicionar node-postgres às suas dependências:

$ npm install pg+ [email protected] 17 packages in 4.002s
 "dependencies": { "cool-ascii-faces": "^1.3.4", "ejs": "^3.1.5", "express": "^4.17.1", "pg": "^8.5.1" },

Agora edite o seu index.js ficheiro para utilizar este módulo para se ligar à base de dados especificada no seu DATABASE_URL variável de ambiente. Adicione isto perto do topo:

const { Pool } = require('pg');const pool = new Pool({ connectionString: process.env.DATABASE_URL, ssl: { rejectUnauthorized: false }});

Agora adicione outra rota, /db, adicionando o seguinte logo após a existente .get('/', ...):

.get('/db', async (req, res) => { try { const client = await pool.connect(); const result = await client.query('SELECT * FROM test_table'); const results = { 'results': (result) ? result.rows : null}; res.render('pages/db', results ); client.release(); } catch (err) { console.error(err); res.send("Error " + err); } })

Isto assegura que ao aceder à sua aplicação utilizando a rota /db, devolverá todas as linhas na tabela test_table.

Disponibilizar isto para Heroku. Se aceder a /db receberá um erro, uma vez que não há tabela na base de dados. Assumindo que tem Postgres instalado localmente, utilize o comando heroku pg:psql para se ligar à base de dados remota, criar uma tabela e inserir uma linha:

Agora, quando aceder à sua aplicação /db rota, verá algo como isto:

Resultados da base de dados são 1 olá base de dados

Leia mais sobre o PostgreSQL de Heroku.

Uma técnica semelhante pode ser usada para instalar MongoDB ou Redis add-ons.

Sabes agora como implementar uma aplicação, alterar a sua configuração, ver logs, escalar, e anexar add-ons.

Aqui está alguma leitura recomendada. A primeira, um artigo, dar-lhe-á uma compreensão mais firme das noções básicas. O segundo é um ponteiro para a categoria principal do Node.js aqui no Dev Center:

  • Leia Como Heroku Funciona para uma visão geral técnica dos conceitos que encontrará enquanto escreve, configura, implementa e executa aplicações.
  • Visitar a categoria Node.js para aprender mais sobre o desenvolvimento e implementação de aplicações Node.js.
  • Ler Implementar aplicações Node.js em Heroku para compreender como levar uma aplicação Node.js existente e implementá-la em Heroku.