Skip to main content

はじめに

Square Cloud で Evolution API を開発してホストするには、構成と前提条件の体系的な手順に従うことが不可欠です。この技術ガイドでは、初期セットアップから本番環境へのデプロイまで、プロセス全体を解説します。

前提条件

  • Square Cloud アカウント: 登録ページからメールアドレスを使って登録します。
  • 有効なプラン: アプリケーションに専用リソースと最適化されたパフォーマンスを提供します。利用可能なプランを確認し、ニーズに最も適したものを選択してください。

Evolution API を使う理由

Evolution API は、WhatsApp 向けのオープンソース API です。ウェブの管理画面または REST API から複数の WhatsApp インスタンスを 1 か所で管理し、n8n、Chatwoot、Typebot などのツールと連携できます。

プロジェクトのセットアップ

Square Cloud へのデプロイに必要なファイルがすでに含まれている当社の evolutionapi-web のリリース、または公式リポジトリからプロジェクトをダウンロードします。
公式リポジトリでは typescript が devDependencies に記載されています。Square Cloud は devDependencies を除いた本番モードで依存関係をインストールするため、npm run build の手順が失敗します。当社のリリースではすでに dependencies に移動済みです。公式リポジトリを使う場合は、ご自身で移動してください。
Evolution API は起動時にプロジェクトのルートにある .env ファイルを読み込むため、このファイルは ZIP に含めます。当社のリリースの .env (または公式リポジトリの .env.example) を元に、以下の変数を編集してください。ダッシュボードの Environment Variables で設定した変数は .env ファイルより優先されるため、AUTHENTICATION_API_KEY や DATABASE_CONNECTION_URI などのシークレットはダッシュボードで設定するのがおすすめです。環境変数を参照してください。

データベースの設定

Evolution API には PostgreSQL データベースが必要です。Standard プラン以上であれば、Square Cloud でホスティングできます。マネージドデータベースの作成と接続の方法を参照してください。 作成後、.env に URL を DATABASE_CONNECTION_URI として設定し、PostgreSQL 接続用のクライアント証明書も用意します。必要な設定の例を以下に示します。
.env
Evolution API は Prisma で接続し、Prisma はクライアント証明書を .p12 ファイルとして受け取ります。ダッシュボードのデータベースのページから証明書ファイル (.crt と .key) をダウンロードし、変換して .p12 をプロジェクトに置きます。
エクスポート時に決めたパスワードが URL の sslpassword になり、sslidentity は .p12 ファイルへのパスです。アプリケーションはディスクから .p12 を読み込むため、ZIP に含めたままにしてください。 環境変数と証明書を設定したら、データベースにマイグレーションを適用します。手元のコンピューターのプロジェクトフォルダで、npm install で依存関係をインストールし (runWithProvider.js ファイルが必要です)、次のコマンドを実行してください。

サーバーの設定

リポジトリの .env.example ファイルに示されているとおり、サーバーの変数 SERVER_TYPE、SERVER_PORT、SERVER_URL と言語を設定します。
.env
Evolution API はポートを (PORT ではなく) SERVER_PORT から読み込み、指定がない場合は 8080 を使うため、SERVER_PORT=80 のままにしてください。 不正アクセスを防ぐために、安全なグローバル API キーを設定することが重要です。ご自身で決めた長いランダムな値に置き換えてください。サンプルファイルのキーは公開されています。
.env

Square Cloud の設定

プロジェクトのルートに squarecloud.app ファイルを作成します。START コマンドは Prisma クライアントを生成し、プロジェクトをビルドして起動します。インストールとビルドには約 3072 MB の RAM が必要です。
squarecloud.app
SUBDOMAIN は SERVER_URL のアドレスと一致させる必要があります。ダッシュボードからアップロードする場合は、「Web Publication」を選択して同じサブドメインを設定し、START コマンドを起動コマンドとして貼り付けてください。

デプロイ

ダッシュボード経由

1

アップロードページにアクセス

アップロードページにアクセスし、プロジェクトの zip ファイルをアップロードします。
2

環境を設定

zip をアップロードした後、プロジェクトの名前、メインファイルまたはランタイム環境、その他の設定を構成する必要があります。
ウェブプロジェクトをアップロードする場合は、必ず「Web Publication」を選択し、プロジェクトにサブドメインを設定してください。
3

プロジェクトをデプロイ

最後に「Deploy」ボタンをクリックして、プロジェクトを Square Cloud にホストします。
デプロイ後、ダッシュボードからプロジェクトのステータスとログを監視できます。
Square Cloud へのアプリケーションのアップロード
4

アプリが稼働していることを確認

最初のデプロイは、通常 1 分もかからずに完了します。ダッシュボードでアプリケーションのステータスが running になるのを待ち、起動時のエラーがないかログを確認してください。
ウェブサイトや API をデプロイした場合は、ブラウザで https://<your-subdomain>.squareweb.app を開き、アプリケーションが応答することを確認してください。ボットをデプロイした場合は、コマンドを送信してオンラインになっていることを確認してください。
アプリが起動しませんか?よくある原因と修正方法はトラブルシューティングガイドを参照してください。

CLI 経由

この方法を使用するには、プロジェクトのルートに squarecloud.app という名前の設定ファイルが必要です。このファイルは、アプリケーションの実行方法を Square Cloud に伝えます。

設定ファイルガイド

アプリケーションの環境を定義する squarecloud.app 設定ファイルの作成方法を学びます。
1

CLI をインストール

Square Cloud CLI をインストールします。すでにお持ちの場合は、同じコマンドを実行すると更新されます:
2

ログイン

次のコマンドを実行します。ブラウザが開くので、そこでログインを承認すれば CLI の準備は完了です。API キーをコピーする必要はありません。スクリプトや CI については、CLI の認証を参照してください。
3

プロジェクトをアップロード

プロジェクトのフォルダで次のコマンドを実行します。CLI は squarecloud.ignore に記載されたものを除いて現在のフォルダを zip にし、アップロードします:
自分で作成した zip をアップロードするには、--file で指定します:
4

アプリが稼働していることを確認

最初のデプロイは、通常 1 分もかからずに完了します。ターミナルから直接、アプリケーションのステータスとログを確認してください。
ウェブサイトや API をデプロイした場合は、ブラウザで https://<your-subdomain>.squareweb.app を開き、アプリケーションが応答することを確認してください。ボットをデプロイした場合は、コマンドを送信してオンラインになっていることを確認してください。
アプリが起動しませんか?よくある原因と修正方法はトラブルシューティングガイドを参照してください。

追加情報

初回実行後は、RAM を 1536MB または 2048MB に減らし、起動コマンドを次のみに設定できます。

キャッシュシステム

Evolution API でキャッシュシステムを設定できます。そのためには、Square Cloud でもホスティングできる Redis データベースが必要です。
設定するには、証明書をダウンロードして接続用の URL を設定する必要もあります。スキームが rediss:// である点に注意してください。Square Cloud のデータベースは TLS 接続のみを受け付けます。
.env

トラブルシューティング

カスタムドメイン

デフォルトの URL mysite.squareweb.app の代わりにカスタムドメイン(例: mysite.com)を使用するには、Standard プラン以上が必要です。デフォルトの URL は設定ファイルの SUBDOMAIN フィールドから決まります。独自ドメインを接続するには、独自ドメインの設定方法に従ってください。

最小 RAM 要件

ウェブサイトと API は最小 512MB RAMです。これは静的ランタイムで静的ビルドを配信するには十分な量です。サーバー上でページをレンダリングするアプリ(Next.js、Nuxt、Angular SSR など)には、最低 1GB RAMを推奨します。より大規模なアプリケーションでは、メモリ不足でアプリケーションがクラッシュするのを防ぐため、より多くの RAM を割り当ててください。

このサイトが見つかりませんでした。

サブドメイン/ドメインが SUBDOMAIN フィールドまたはカスタムドメイン設定で構成されている内容と一致しているか確認してください。サイトをアップロードしたばかりの場合は、Square が初回アクセスを有効化するまで最大 60 秒お待ちください。

サイトの応答に時間がかかりすぎました…

サーバーはポート 80 とホスト 0.0.0.0 でリッスンする必要があります。Square Cloud はアプリケーションに環境変数 PORT(80)と HOST(0.0.0.0)を設定します。別の値をハードコーディングせず、コードでこれらを読み込んでください。localhost や 127.0.0.1 だけでリッスンしているサーバーには、リクエストが届きません。

次のステップ

マネージドデータベース

Evolution API に必要な PostgreSQL データベースを作成します。

データベース接続エラー

SSL/TLS や接続のエラーを修正します。

WhatsApp ボット

whatsapp-web.js または Baileys で単体の WhatsApp ボットを作成します。

お問い合わせ

技術的な問題が解決しない場合は、専門のサポートチームがお手伝いします。お問い合わせいただければ、どのような問題でも喜んで解決をサポートいたします。サポートの質の高さも、開発者が Google と Trustpilot で Square Cloud に402 件のレビューで 4.9/5という評価をつけている理由の 1 つです。