Heroku スターターガイド (Node.js)
はじめに
このチュートリアルでは、Node.js アプリを Heroku にデプロイする方法を簡単に紹介します。
少し時間を取り、Heroku プラットフォームを最大限に活用する方法をご確認ください。
このチュートリアルでは、以下が用意されていることを前提としています。
- 確認済みの Heroku アカウント
- Node.js および npm がローカルにインストールされている
- Eco dyno プランのサブスクリプション (推奨)
dyno を使用してこのチュートリアルを完了した場合、使用量のカウントに入ります。低料金プランを使用してこのチュートリアルを完了することをお勧めします。資格のある学生の皆様は、新しい Heroku for GitHub Students プログラムを通じてプラットフォームクレジットを申請できます。
設定する
Heroku CLI には、一般によく使われている Git というバージョン管理システムが必要です。Git がまだインストールされていない場合は、先に進む前に次の手順を完了してください。
このステップでは、Heroku Command Line Interface (CLI) をインストールします。CLI は、アプリケーションの管理やスケール、アドオンのプロビジョニング、アプリケーションログの表示、アプリケーションのローカル実行に使用します。
お使いのプラットフォーム用のインストーラをダウンロードし、実行してください。
macOS$ brew tap heroku/brew && brew install heroku
Windowsインストールが完了したら、ターミナルで heroku コマンドを使用できます。
Windows では、コマンドプロンプト (cmd.exe) または Powershell を起動して、コマンドシェルを開きます。
heroku login コマンドを使って Heroku CLI にログインします。
$ heroku login
heroku: 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... done
Logged in as me@example.com
このコマンドにより、Web ブラウザで Heroku ログインページが開きます。ブラウザですでに Heroku にログインしている場合は、ページに表示されている[Log in] (ログイン) ボタンをクリックします。
この認証は、heroku と git コマンドが正常に動作するために必要な操作です。
外部の HTTP/HTTPS サービスへの接続にプロキシの使用が必要なファイアウォールを使っている場合は、heroku コマンドを実行する前に、ローカルの開発環境で HTTP_PROXY または HTTPS_PROXY 環境変数を設定できます。
手順を進める前に、前提条件の項目が正しくインストールされていることを確認します。次の各コマンドを実行し、インストールしたバージョンが表示されることを確認します (実際のバージョンが以下の例と異なる場合があります)。バージョン情報が表示されない場合は、このチュートリアルの最初に戻り、前提条件の項目をインストールしてください。
「アプリの依存関係を宣言する」およびそれ以降の手順を実行するには、ローカル環境で次の設定がすべて完了している必要があります。
このチュートリアルでは、Node のバージョン 10 以降が必要です。Node のバージョンを確認します。
$ node --version
v18.14.2
Node と一緒にインストールされる npm がインストールされていることを確認します。インストールされていない場合は、より新しいバージョンの Node をインストールしてください。
$ npm --version
9.5.0
git がインストールされていることを確認します。 インストールされていない場合は、もう一度インストールして、テストしてください。
$ git --version
git version 2.39.2
アプリを準備する
このステップでは、Heroku にデプロイできるサンプルアプリケーションを準備します。
Heroku をはじめて使う場合は、 Heroku が提供するサンプルアプリケーションを使ってこのチュートリアルを行うことをお勧めします。
ただし、デプロイする既存のアプリケーションを用意してある場合は、 Heroku へのデプロイを準備する方法について、この記事を 参照してください。
Heroku にデプロイするサンプルアプリケーションのローカルバージョンをクローンするには、ローカルのコマンドシェルまたはターミナルで次のコマンドを実行します。
$ git clone https://github.com/heroku/node-js-getting-started.git
$ cd node-js-getting-started
これで、シンプルなアプリケーションと、Node の依存関係マネージャが使用する package.json ファイルを格納した、正常な Git リポジトリを準備できました。
アプリをデプロイする
このステップでは、アプリを Heroku にデプロイします。
dyno を使用してこのチュートリアルを完了した場合、使用量のカウントに入ります。コストを抑制するために、完了したらすぐにアプリを削除してください。
Eco にサブスクライブしている場合、アプリではデフォルトで Eco dyno が使用されます。それ以外の場合は、デフォルトで Basic dyno が使用されます。Eco dyno プランは、アカウントのすべての Eco dyno 間で共有され、多数の小さなアプリを Heroku にデプロイする場合にお勧めします。詳細は、こちらを参照してください。資格のある学生の皆様は、Heroku for GitHub Students プログラムを通じてプラットフォームクレジットを申請できます。
Heroku でアプリを作成すると、Heroku でソースコードを受け取ることができるよう準備できます。
$ heroku create
Creating app... done, ⬢ shrouded-anchorage-35377
https://shrouded-anchorage-35377.herokuapp.com/ | https://git.heroku.com/shrouded-anchorage-35377.git
アプリを作成すると、heroku という名前の git リモートリポジトリも作成され、ローカルの git リポジトリと関連付けられます。
Heroku によってランダムなアプリ名 (この場合は shrouded-anchorage-35377) が生成されます。パラメータを渡して独自のアプリ名を指定することもできます。
コードをデプロイします。
$ git push heroku main
Enumerating objects: 554, done.
Counting objects: 100% (554/554), done.
Delta compression using up to 20 threads
Compressing objects: 100% (412/412), done.
Writing objects: 100% (554/554), 248.74 KiB | 124.37 MiB/s, done.
Total 554 (delta 109), reused 548 (delta 106), pack-reused 0
remote: Compressing source files... done.
remote: Building source:
remote:
remote: -----> Building on the Heroku-22 stack
remote: -----> Determining which buildpack to use for this app
remote: -----> Node.js app detected
remote:
remote: -----> Creating runtime environment
remote:
remote: NPM_CONFIG_LOGLEVEL=error
remote: NODE_VERBOSE=false
remote: NODE_ENV=production
remote: NODE_MODULES_CACHE=true
remote:
remote: -----> Installing binaries
remote: engines.node (package.json): 18.x || 16.x
remote: engines.npm (package.json): unspecified (use default)
remote:
remote: Resolving node version 18.x || 16.x...
remote: Downloading and installing node 18.14.2...
remote: Using default npm version: 9.5.0
remote:
remote: -----> Installing dependencies
remote: Installing node modules (package.json)
remote:
remote: added 160 packages, and audited 161 packages in 4s
remote:
remote: 64 packages are looking for funding
remote: run `npm fund` for details
remote:
remote: found 0 vulnerabilities
remote:
remote: -----> Build
remote:
remote: -----> Caching build
remote: - node_modules
remote:
remote: -----> Pruning devDependencies
remote:
remote: up to date, audited 74 packages in 450ms
remote:
remote: 9 packages are looking for funding
remote: run `npm fund` for details
remote:
remote: found 0 vulnerabilities
remote:
remote: -----> Build succeeded!
remote: -----> Discovering process types
remote: Procfile declares types -> web
remote:
remote: -----> Compressing...
remote: Done: 43.4M
remote: -----> Launching...
remote: Released v3
remote: https://shrouded-anchorage-35377.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.
To https://git.heroku.com/shrouded-anchorage-35377.git
* [new branch] main -> main
アプリケーションがデプロイされました。 アプリのインスタンスが 1 つ以上実行されていることを確認します。
$ heroku ps:scale web=1
アプリ名で生成された URL にあるアプリを開きます。 次のショートカットを使うと、簡単に Web サイトを開くことができます。
$ heroku open
ログを表示する
Heroku では、すべてのアプリと Heroku コンポーネントの出力ストリームを、時系列のイベントストリームに集約してログを作成するため、1 か所ですべてのイベントを確認できます。
実行中のアプリに関する情報を表示するには、ログコマンドの 1 つである、heroku logs --tail を使います。
$ heroku logs --tail
2023-03-02T19:56:09.671017+00:00 heroku[web.1]: Starting process with command `npm start`
2023-03-02T19:56:12.617099+00:00 app[web.1]:
2023-03-02T19:56:12.617126+00:00 app[web.1]: > node-js-getting-started@0.3.0 start
2023-03-02T19:56:12.617127+00:00 app[web.1]: > node index.js
2023-03-02T19:56:12.617127+00:00 app[web.1]:
2023-03-02T19:56:12.738203+00:00 app[web.1]: Listening on 16832
2023-03-02T19:56:13.217147+00:00 heroku[web.1]: State changed from starting to up
ブラウザで再びアプリケーションを表示すると、別のログメッセージが生成されます。
ログのストリーム出力を停止するには、Control+C を押します。
Procfile を定義する
Procfile は、アプリケーションのルートディレクトリにあるテキストファイルです。このファイルを使って、アプリの起動時に実行するコマンドを明示的に宣言します。
先ほどデプロイしたサンプルアプリの Procfile は、次のようになっています。
web: npm start
単一のプロセスタイプの web と、その実行に必要なコマンドを宣言しています。 ここでは、web という名前が重要です。 これは、このプロセスタイプを Heroku の HTTP ルーティングスタックにアタッチし、デプロイ後に Web トラフィックを受信することを宣言しています。このコマンドでは、package.json で指定される start スクリプトを使用します。
Procfile には追加のプロセスタイプを含めることができます。 たとえば、アイテムをキューから外す処理を実行するバックグラウンドプロセスを追加で宣言できます。
アプリをスケールする
現在、アプリは単一の Web dyno で実行されています。 dyno とは、Procfile で指定されているコマンドを実行する軽量のコンテナのようなものです。
実行されている dyno の数を確認するには、ps コマンドを使います。
$ heroku ps
=== web (Eco): npm start (1)
web.1: up 2023/03/02 15:56:13 -0400 (~ 6m ago)
デフォルトでは、アプリは Eco dyno でデプロイされます。Eco dyno はアイドル状態 (トラフィックを何も受信しない状態) が 30 分続くとスリープします。 スリープすると、スリープ解除するときの最初のリクエスト時に数秒の遅延が発生します。その後のリクエストは正常に処理されます。 Eco dyno は、月ごとに割り当てられるアカウント別の Eco dyno 時間を消費します。割り当て時間が残っている限り、Eco アプリはすべて稼働し続けます。
dyno がスリープしないようにするには、「dyno タイプ」の記事で紹介されている Basic または Professional の dyno タイプにアップグレードできます。たとえば、アプリを Professional dyno に移行すると、Heroku に特定の数の dyno の実行を指示するコマンドを実行し、各 dyno で Web プロセスタイプを実行させて、アプリを簡単にスケールすることができます。
Heroku でアプリケーションをスケールするとは、実行する dyno の数を変更することを意味します。 Web dyno の数を 0 にスケールしてみます。
$ heroku ps:scale web=0
ブラウザのタブで更新ボタンを押してアプリにアクセスするか、heroku open コマンドを使ってブラウザのタブで開きます。 リクエストに応答できる Web dyno がないので、エラーメッセージが表示されます。
もう一度スケールしてみましょう。
$ heroku ps:scale web=1
アプリの依存関係を宣言する
Heroku では、アプリのルートディレクトリに package.json ファイルがあると、そのアプリを Node.js と認識します。独自のアプリでこのファイルを作成するには、npm init --yes を実行します。
デプロイしたデモ用アプリには、事前に次のような package.json が用意されています。
{
"name": "node-js-getting-started",
"version": "0.3.0",
...
"engines": {
"node": "18.x || 16.x"
},
"dependencies": {
"ejs": "^3.1.5",
"express": "^4.15.2"
},
...
}
package.json ファイルでは、Heroku でのアプリケーション実行に使用される Node.js のバージョンと、アプリケーションと一緒にインストールする必要がある依存関係を定義します。
このコマンドをローカルディレクトリで実行して依存関係をインストールし、アプリをローカルで実行できるようにシステムを準備します。
$ npm install
added 160 packages in 6s
依存関係がインストールされたら、アプリをローカルで実行する準備は完了です。npm install が実行されると、package-lock.json ファイルが生成されます。これを Git にチェックインしてください。後続の依存関係が追加されると、npm でこのファイルが変更されるため、これらの変更も Git に追加するようにしてください。
アプリがデプロイされると、Heroku は package.json を読み取って適切なノードバージョンをインストールし、package-lock.json を読み取って依存関係をインストールします。
アプリをローカルで実行する
heroku local コマンドを使ってアプリケーションをローカルで起動します。このコマンドは、Heroku CLI の一部としてインストールされています。
$ heroku local web --port 5001
[OKAY] Loaded ENV .env File as KEY=VALUE Format
4:09:49 p.m. web.1 | > node-js-getting-started@0.3.0 start
4:09:49 p.m. web.1 | > node index.js
4:09:49 p.m. web.1 | Listening on 5001
Heroku と同じように、heroku local も Procfile を確認して実行する内容を判断します。
Web ブラウザで「http://localhost:5001」を開きます。ローカルで実行されているアプリが表示されます。
アプリのローカル実行を停止するには、CLI で Ctrl+C を押して終了します。
ローカルの変更をプッシュする
このステップでは、アプリケーションへのローカルでの変更を Heroku に反映させる方法を学びます。 例として、アプリケーションを変更して依存関係を追加し、それを使用するコードも追加します。
まず、package.json で cool-ascii-faces の依存関係を追加します。 これを行うため、次のコマンドを実行します。
$ npm install cool-ascii-faces
added 11 packages in 2s
起動時にこのモジュールが必要 ( requires ) になるように、index.js を編集します。 これを使用する新しいルート (/cool) も追加します。 最終的に、コードは次のようになります。
const cool = require('cool-ascii-faces')
const express = require('express')
const path = require('path')
const PORT = process.env.PORT || 5001
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 }`))
ローカルでテストします。
$ npm install
$ heroku local --port 5001
「http://localhost:5001/cool」でアプリケーションにアクセスすると、更新する度にこのような ( ⚆ _ ⚆ ) 絵文字が表示されます。
次にデプロイします。 Heroku へのデプロイは、ほとんどの場合、このパターンで行います。 まず、変更したファイルをローカルの git リポジトリに追加します。
$ git add .
次に、変更内容をリポジトリにコミットします。
$ git commit -m "Add cool face API"
前と同じ方法でデプロイします。
$ git push heroku main
最後に、すべて正常に動作しているかどうかを確認します。
$ heroku open cool
また絵文字が表示されることを確認してください。
アドオンをプロビジョニングする
アドオンは、アプリケーションですぐに使える追加サービスを提供するサードパーティのクラウドサービスです。永続性、ログ記録、モニタリングなど、さまざまなアドオンがあります。
Heroku では、デフォルトで 1500 行のアプリケーションログが記録されますが、 完全なログストリームもサービスとして提供しています。複数のアドオンプロバイダがこのサービスを利用し、ログの永続化、検索、メールや SMS 通知などの機能を実現するログサービスを提供しています。
このステップでは、このようなログに関するアドオンの 1 つである、Papertrail をプロビジョニングします。
Papertrail のアドオンをプロビジョニングします。
$ heroku addons:create papertrail
Creating papertrail on ⬢ shrouded-anchorage-35377... free
Welcome to Papertrail. Questions and ideas are welcome (technicalsupport@solarwinds.com). Happy logging!
Created papertrail-fluffy-46630 as PAPERTRAIL_API_TOKEN
Use heroku addons:docs papertrail to view documentation
アドオンがデプロイされ、アプリケーション用に設定されました。 アプリのアドオンは、次のコマンドで一覧表示できます。
$ heroku addons
このアドオンが動作していることを確認するため、アプリケーションの Heroku URL に数回アクセスします。アクセスする度にログメッセージが生成され、Papertrail のアドオンに送られるようになります。 Papertrail のコンソールにアクセスし、ログメッセージを確認します。
$ heroku addons:open papertrail
ブラウザで Papertrail の Web コンソールが開き、最新のログイベントが表示されます。 このインターフェースでは、検索したり通知を設定したりできます。
コンソールを起動する
dyno の仕組みに慣れるため、別の One-off dyno を作成し、この dyno でシェルを開く bash コマンドを実行してみましょう。シェルが開いたら、そこでコマンドを実行できます。dyno にはそれぞれ固有の一時的なファイル領域が割り当てられ、アプリとその依存関係がそこに格納されます。コマンド (この場合は bash) が完了すると、dyno は削除されます。
$ heroku run bash
Running bash on ⬢ shrouded-anchorage-35377... up, run.1662 (Eco)
~ $ ls
Procfile README.md app.json index.js node_modules package-lock.json package.json public test.js views
~ $ exit
exit
Error connecting to process というエラーが表示された場合は、ファイアウォールの設定が必要な可能性があります。
必ず exit と入力してシェルを閉じ、dyno を終了してください。
環境設定を定義する
Heroku では、設定を外部に置き、暗号鍵や外部リソースのアドレスなどのデータを環境設定に保存できます。
環境設定は、ランタイムに環境変数としてアプリケーションに提供されます。 例として、index.js を編集し、環境変数 TIMES の値に応じてあるアクションを繰り返し実行する、/times という新しいルートを追加します。 既存の get() という呼び出しの下に、次のようにもう 1 つ追加します。
.get('/times', (req, res) => res.send(showTimes()))
ファイルの最後に、showTimes() という新しい関数の定義を次のように追加します。
function showTimes() {
const times = process.env.TIMES || 5
let result = ''
for (i = 0; i < times; i++) {
result += i + ' '
}
return result
}
heroku local は、ローカルディレクトリにある .env ファイルの内容に応じて、環境を自動的に設定します。 プロジェクトのトップレベルディレクトリにはすでに .env ファイルがあり、以下の行が含まれています。
TIMES=2
heroku local --port 5001 でアプリを実行して http://localhost:5001/times を開くと、毎回 2 つの数値が生成されることがわかります。
Heroku で環境設定を設定するには、次のコマンドを実行します。
$ heroku config:set TIMES=2
heroku config を使って設定した環境設定を表示します。
$ heroku config
=== shrouded-anchorage-35377 Config Vars
PAPERTRAIL_API_TOKEN: w9EnziexBT2mzMDtS4M
TIMES: 2
変更したアプリケーションを Heroku にデプロイし、heroku open times を実行してアクセスします。
データベースをプロビジョニングする
データベースを使用してこのチュートリアルを完了した場合、使用量のカウントに入ります。コストを抑制するために、完了したらすぐにデータベースを削除してください。低料金プランについて確認してください。資格のある学生の皆様は、Heroku for GitHub Students プログラムを通じてプラットフォームクレジットを申請できます。
add-on marketplace には、Redis や MongoDB、Postgres、MySQL など、多数のデータストアが揃っています。 このステップでは、Heroku Mini Postgres Starter Tier dev データベースをアプリに追加します。
データベースを追加します。
$ heroku addons:create heroku-postgresql:mini
Creating heroku-postgresql:mini on ⬢ shrouded-anchorage-35377... $5/month
Database has been created and is available
! This database is empty. If upgrading, you can transfer
! data from another database with pg:copy
Created postgresql-asymmetrical-00466 as DATABASE_URL
Use heroku addons:docs heroku-postgresql to view documentation
このコマンドによりデータベースが作成され、環境変数 DATABASE_URL が設定されます (heroku config を実行して確認できます)。
npm を使用して、node-postgres を依存関係に追加します。
$ npm install pg
added 14 packages in 2s
"dependencies": {
"cool-ascii-faces": "^1.3.4",
"ejs": "^3.1.5",
"express": "^4.15.2",
"pg": "^8.9.0"
},
次に、このモジュールを使って DATABASE_URL 環境変数で指定したデータベースに接続できるように、index.js ファイルを編集します。 次の行を上部付近に追加します。
const { Pool } = require('pg')
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
ssl: {
rejectUnauthorized: false
}
})
既存の .get('/', ...) のすぐ後ろに次のコードを追加して、別のルート /db を追加します。
.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);
}
})
このように編集することで、/db ルートでアプリにアクセスしたときに、テーブル test_table のすべての行が返されるようになります。
これを Heroku にデプロイします。 /db にアクセスすると、データベースにテーブルがないため、エラーが表示されます。 ローカル環境に Postgres がインストールされているという前提で、heroku pg:psql コマンドを使ってリモートデータベースに接続し、テーブルを作成して行を挿入します。
$ heroku pg:psql
--> Connecting to postgresql-asymmetrical-00466
psql (14.7 (Homebrew))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.
shrouded-anchorage-35377::DATABASE=> create table test_table (id integer, name text);
CREATE TABLE
shrouded-anchorage-35377::DATABASE=> insert into test_table values (1, 'hello database');
INSERT 0 1
shrouded-anchorage-35377::DATABASE=> \q
この後、heroku open db でアプリの /db ルートにアクセスすると、次のように表示されます。
詳細は、「Heroku PostgreSQL」を参照してください。
MongoDB や Redis のアドオンをインストールするときも、同様のテクニックを利用できます。
次のステップ
ここまで、アプリのデプロイ、アプリの設定変更、ログの表示、スケール、アドオンのアタッチを行う方法を説明しました。
次にお勧めするリソースを紹介します。 1 つ目の記事では、基本的な理解をさらに深めることができます。 2 つ目のリンクからは、この Dev Center にある Node.js カテゴリをご覧いただけます。
- 「Heroku の仕組み」では、アプリケーションの作成、設定、デプロイ、および実行時に必要な技術的な概念の概要を紹介しています。
- Node.js カテゴリでは、Node.js アプリケーションの開発とデプロイに関する詳細を確認できます。
- 「Heroku で Node.js アプリをデプロイする」では、既存の Node.js アプリを Heroku にデプロイする方法を紹介しています。
- Heroku の開発者としての体験および CI/CD 機能についての詳細は、「Heroku Enterprise Developer Learning Journey」を参照してください。