Zenn
KWCPLUSPublicationへの投稿
🀄️

VCRアプリケーションをローカル環境で開発しよう

高橋克己（□い芸人）
2024/12/04に公開
Vonage
cpaas
tech

はじめに

みなさん、こんにちは。KDDI ウェブコミュニケーションズで CPaaS のエバンジェリストをしている高橋です。
この記事では、Vonage のアプリケーションサーバーである VCR(Vonage Cloud Runtime)をローカル環境で作成・実行する方法について解説をします。
VCR については、こちらの記事もご覧ください。

本記事の対象となる読者

  • Vonage のアプリケーションをホスティングするサーバーを探している方
  • Node.js + Express の仕組みがなんとなくわかる方
  • Vonage 上で、Twilio Functions や Assets のようなサービスを探している方
  • Vonage Cloud Runtime を始めてみたい方
  • VCR の開発をローカル環境で行いたいと考えている方

Vonage とは

Vonage_logo

Vonage は、米国ニュージャージー州に本社を置く、CPaaS（Communication Platform as a Service）企業です。
もともとは VoIP（Voice over IP）企業としてスタートしましたが、いくつかの企業買収を行うことで、コミュニケーションサービス全般をサポートすることができる企業に発展しました。現在はスウェーデンの大手通信機器会社エリクソンの傘下に入っています。

2024年2月14日より、株式会社KDDIウェブコミュニケーションズ（以後、KWC）が Vonage の再販事業を開始することとなりました。
KWC経由でアカウントを開設する場合、Vonageで直接開設したアカウントとは一部仕様が異なります。（※提供する機能面において違いはありません）

Vonage Cloud Runtime とは

Vonage Cloud Runtime （VCR）は、Vonage が提供するクラウド型のアプリケーションサーバーです。
VCR上に構築されたアプリケーションはVonage上にホスティングされるため、カスタマーは自身でAWSなどの外部サーバーを準備する必要がありません。
これにより、Vonage API を使ってすぐにPoCやテストが行えるほか、外部のAPIサービスと連携したアプリケーションを構築できます。

用語定義

用語 説明
プロジェクト VCRでは、作成するアプリケーションのことをプロジェクトと呼びます。
インスタンス ワークスペースをデプロイすることで立ち上がるサーバー環境です。
リージョン プロジェクトやインスタンスを管理するAWSリージョンで、Asia Pacific、US Virginia、Europe Irelandの3つから選択できます。

準備

事前に以下の準備を行っておいてください。

  • Vonage アカウントを保有していること

VCR CLI のインストール

ではまず、VCR を操作するための CLI(Command Line Interface)をインストールしましょう。
使用しているOSごとにインストール方法が異なります。

Windowsを利用している場合

以下のコマンドを使ってインストールを行います。

pwsh -Command "iwr https://raw.githubusercontent.com/Vonage/cloud-runtime-cli/main/script/install.ps1 -useb | iex"

macOS もしくは Linux を利用している場合

以下のコマンドを使ってインストールを行います。

curl -L https://raw.githubusercontent.com/Vonage/cloud-runtime-cli/main/script/install.sh | sh

アップデート

すでにインストール済みの CLI を最新バージョンにアップデートするには、以下のコマンドを使います。

vcr upgrade

環境設定

CLI で利用する Vonage の環境を設定します。
以下のコマンドを使って、対話形式で設定していきます。設定には、現在の Vonage アカウントのAPI KeyとAPI Secretが必要です。
それぞれ、Vonage のダッシュボードからコピーできます。

API Key & API Secret

vcr configure
? Enter your Vonage api key: ご自分の API Key を設定します。
? Enter your Vonage api secret: 同じく、ご自分の API Secret を設定します。
? Select your Vonage region: Asia Pacific (Sydney) / Asia Pacific (Singapore) / US Virginia / Europe Ireland のいずれかを選択します。
✓ New configuration file written to ~/.vcr-cli

設定ができたら、CLI が正しく動作するか以下のコマンドでアプリケーションの一覧を表示させてみます。

vcr app list

先ほど設定した Vonage アカウント内のアプリケーションの一覧が表示されれば CLI の設定は完了です。

アプリケーションの作成

ではここからhelloworldサンプルアプリケーションを作成してみます。

まずはアプリケーション用のディレクトリを作成します。

mkdir vcr-helloworld
cd vcr-helloworld

以下のコマンドを使って対話型で作成していくことができます。

vcr init
? Enter your project name: (vcr-helloworld) 
# プロジェクト名を入力します。
? Enter your Instance name: (dev)　
# インスタンスの名前を入力します。デフォルトはdevです。
? Select a runtime:  [Use arrows to move, type to filter] java19gradle / java21 / nodejs16 / nodejs18 / nodejs22 / php8 / python3 / ruby32 / ruby3.3 / dotnet6.0 / dotnet8.0 / go119 
# 今回は「nodejs22」を選択します。※現在、nodeとpython以外は対応していません。
? Select a region:  [Use arrows to move, type to filter] 
# リージョンを選択します。
? Select your Vonage application ID for deployment:  [Use arrows to move, type to filter] 
# 「CREATE NEW APP」を選択します。
? Enter your new Vonage application name for deployment: 
# アプリケーションの名前を入力します。今回は、「helloworld-vcr」とします。
? Select your Vonage application ID for debug: 
# デバッグ用のアプリケーションIDを選択します。「helloworld-vcr」を選択します。
? Select a product template for runtime nodejs22: 
# テンプレートを選択します。「Starter Project」を選択します。

以下のようなファイルが作成されます。

.
├── README.md
├── __MACOSX
│   └── public
├── cc.png
├── debug.png
├── index.js
├── node_modules
├── package-lock.json
├── package.json
├── public
│   ├── index.html
│   └── styles.css
└── vcr.yml

デバッグモードで起動

nodemon がインストールされていない場合はインストールします。

npm install -g nodemon

以下のコマンドを使って、デバッグモードで起動してみましょう。

npm run debug

> helloworld@1.0.0 debug
> vcr debug

Are you sure you want to debug with instance app id ? [y/n]: y
! Debug environment values were not detected in the manifest, the instance environment values were loaded as an alternative. Please consider adding debug environment values
✓ Debug server deployed: service_name="neru-XXXXXXXX-debug-debug"

/-------
| 🐞 Debugger proxy connection established - Have a play around!
| Application Name: neru-XXXXXXXX-debug-debug
| Application Host: https://neru-XXXXXXXX-debug-debug.apse1.runtime.vonage.cloud
\-------

[nodemon] 3.1.7
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,cjs,json
[nodemon] starting `node --inspect index.js`
Debugger listening on ws://127.0.0.1:9229/f90eed6a-f7f3-4b34-a046-ed6d350ee759
For help, see: https://nodejs.org/en/docs/inspector
(node:31291) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
App listening on port 3000

途中で、Are you sure you want to debug with instance app id ?と聞かれますので、yと応答してください。

上記のように表示されればデバッグモードでの起動は成功です。
ブラウザでhttp://localhost:3000にアクセスすると、以下のようなページが表示されます。

debug run

デバッグモードを終了するには、Ctrl+C を押します。

ブレークポイントを使ったデバッグ

VS Code エディタやCursor エディタを使うことで、ブレークポイントを使ったデバッグができるようになります。

デバッグ用のポートの設定

.vscode/launch.jsonを開き、"command": "npm run debug",を"command": "VCR_PORT=3001 npm run start",に書き換えます。

launch.json
{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "command": "VCR_PORT=3001 npm run start", # この行を書き換えます
            "name": "Start Debugger",
            "request": "launch",
            "type": "node-terminal"
        }
    ]
}

ブレークポイントの設定

ブレークポイントを使ったデバッグを実施するために、index.jsに/testエンドポイントを追加します。

index.js
import { Vonage } from "@vonage/server-sdk";
import { vcr } from "@vonage/vcr-sdk";
import express from 'express';

const app = express();
const port = process.env.VCR_PORT;

const vonage = new Vonage(
    {
        applicationId: process.env.API_APPLICATION_ID,
        privateKey: process.env.PRIVATE_KEY
    }
);

app.use(express.json());
app.use(express.static('public'));

app.get('/_/health', async (req, res) => {
    res.sendStatus(200);
});

// ここから
app.get('/test', async (req, res) => {
    res.send('OK');
});
// ここまでを追加します。

app.listen(port, () => {
    console.log(`App listening on port ${port}`)
});

今追加したres.send('OK')の行にブレークポイントを設定します。

set breakpoint

エディタの実行とデバッグメニューを開いて、さらに緑色の三角ボタンを押してデバッガーをスタートします。

start debug

ブラウザを開いてhttp://localhost:3001/testを開くと、ブレークポイントで実行が一時停止することが確認できます。
停止したプログラムを進めたり停止させるにはデバッガーツールの各ボタンを利用します。

debugger

デバッガーツールの赤い□を押すとデバッガーが停止します。

デプロイ

では最後に、今作成したアプリケーションを VCR にデプロイしてみます。

以下のコマンドを入力すると、アプリケーションがデプロイされます。

vcr deploy
✓ Project "vcr-helloworld" created: project_id="614e6e72-2665-4b00-bfa9-96e9da5c8468"
✓ Source code uploaded.
✓ Package created: package_id="6880d99c-5539-49f0-ae53-20893e5961a6"
ℹ Waiting for build to start...
INFO[2024-11-28T03:49:10Z] updating package status 

（中略）

INFO[2024-11-28T03:49:25Z] updating package status package_id="6880d99c-5539-49f0-ae53-20893e5961a6" status="completed"
✓ Package "6880d99c-5539-49f0-ae53-20893e5961a6" built successfully
/-------
| Instance has been deployed!
| Instance id: d7c67f84-a23c-4d30-a728-35135e06c312
| Instance service name: neru-XXXXXXXX-vcr-helloworld-dev
| Instance host address: https://neru-XXXXXXXX-vcr-helloworld-dev.apse1.runtime.vonage.cloud
\-------

正常にデプロイが終了すると、上記のようにURLが払い出されます。
払い出されたURL（host address）にブラウザでアクセスして、先ほどと同じような画面が表示されればOKです。

Vonage ダッシュボードからもインスタンスができていることが確認できます。

instance

サーバー側のログは、インスタンスのLogsタブで確認することができます。

instance logs

まとめ

今回は、VCR の開発環境をローカルで作成してみました。
ワークスペースを使って開発するのに比べて、自分の好きなエディタで開発ができるようになるため、エンジニアにとってはより身近に感じられるかと思います。
次回の記事では、ローカル開発環境を GitHub と連携するとともに、GitHub Actions を使った自動デプロイの方法についても説明する予定です。

KWCPLUS
KWCPLUSPublication

株式会社KDDIウェブコミュニケーションズ Tech Blog

Discussion