WhatsApp BusinessプラットフォームオンプレミスAPI

開発者セットアップ:ハイアベイラビリティとマルチコネクト

このドキュメントでは、開発者マシンでハイアベイラビリティクラスタを設定する方法を示します。また、それに加えてマルチコネクトを有効にする方法、そしてハイアベイラビリティマルチコネクトクラスタで必要になる変更についても説明します。

本番環境の設定については、それに関して本番環境の設定に示されている手順を実行してください。

開始する前に

事前に開発者セットアップ:単一インスタンスの手順に従って開発者マシン上でWhatsAppビジネスAPIクライアントを設定している場合、このドキュメントの残りの部分に進む前に、マイグレーションガイドの手順を実行してください。

このガイドの内容は、フレッシュインストールを前提としています。

以下が必要です。

  • Docker
  • Docker Compose
    • これはDockerインストールにバンドルされているはずですが、バンドルされていない場合はインストールできます。
  • 開発環境でテストアカウントをローカルに設定する
    • これを実行する目的は、開発の時間短縮のため、また新しいリリースをテストするためです。

また、アベイラビリティとスケーリングのガイドを読んで、ハイアベイラビリティとマルチコネクトの詳細について確認することをも強くおすすめします。

ハイアベイラビリティクラスタを設定する

ステップ1: 設定スクリプトを格納するbizディレクトリを作成する

WhatsApp Business APIクライアント用に選択した場所で次のコマンドを実行します。

mkdir ~/biz; cd ~/biz;

ステップ2: WhatsApp Business APIクライアントの構成ファイルを取得する

WhatsApp Business APIクライアントの構成ファイルは、GitHubリポジトリWhatsApp-Business-API-Setup-Scripts内にあります。WhatsApp Business APIクライアントは、MySQLかPostgresのいずれかのデータベースインスタンスを使用して設定できます。

ステップ3: WA_API_VERSION環境変数を設定する

次のコマンドを使用して、WA_API_VERSION環境変数を現在のバージョンに設定します。

export WA_API_VERSION=current-whatsapp-version

ステップ4: ハイアベイラビリティでWhatsApp Business APIクライアントを起動する

「ハイアベイラビリティについて」の中で示されている図のように、背景で1つのデータベースコンテナ、1つのWebappコンテナ、2つのMasterコンテナ、および2つのCoreappコンテナでハイアベイラビリティクラスタを起動するには、以下のコマンドを実行します。

docker-compose -f multiconnect-compose.yml up -d db waweb master1 master2 wacore1 wacore2

結果の出力は次のようになります。

Creating network "biz_default" with the default driver
Creating volume "biz_mysqlData" with local driver
Creating volume "biz_whatsappMedia" with local driver
Creating biz_db_1 ... done
Creating biz_waweb_1 ... done
Creating biz_master1_1 ... done
Creating biz_master2_1 ... done
Creating biz_wacore2_1 ... done
Creating biz_wacore1_1 ... done

ステップ5: コンテナが実行されていることを確認する

次のコマンドを実行して、すべてのコンテナの状態がUPであることを確認します。

docker-compose -f multiconnect-compose.yml ps

結果の出力は次のようになります。

      Name                    Command               State                                                 Ports
--------------------------------------------------------------------------------------------------------------------------------------------------------------
biz_db_1        docker-entrypoint.sh mysqld      Up      0.0.0.0:33060->3306/tcp, 33060/tcp
biz_master1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32931->6250/tcp, 0.0.0.0:32930->6251/tcp, 0.0.0.0:32928->6252/tcp, 0.0.0.0:32926->6253/tcp
biz_master2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32929->6250/tcp, 0.0.0.0:32927->6251/tcp, 0.0.0.0:32925->6252/tcp, 0.0.0.0:32924->6253/tcp
biz_wacore1_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32937->6250/tcp, 0.0.0.0:32935->6251/tcp, 0.0.0.0:32933->6252/tcp, 0.0.0.0:32932->6253/tcp
biz_wacore2_1   /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:32939->6250/tcp, 0.0.0.0:32938->6251/tcp, 0.0.0.0:32936->6252/tcp, 0.0.0.0:32934->6253/tcp
biz_waweb_1     /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

デフォルトの場合、Webappコンテナは9090ポートで実行され、データベースコンテナはポート33060で実行されます。

ステップ6: ヘルスチェックを実行する

FacebookのPostmanコレクションをダウンロードして構成すると、コマンドラインを使用せずにWhatsApp Business APIを操作できます。

WhatsApp Business APIクライアントにヘルスチェックを実行するには、healthノードへのAPI呼び出しを使用します。

結果の出力は次のようになります。

{
    "health": {
      "master1:b28d835cd579": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "master2:7fe542d305b4": {
          "gateway_status": "unregistered",
          "role": "primary_master"
      },
      "wacore1:35a5fabfc79d": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      },
      "wacore2:05e1a6d70665": {
          "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
          ]
      }
  }
}

WhatsApp Business APIクライアントがまだ登録されていないので、応答にはプライマリMasterコンテナのgateway_statusとして、unregisteredのgateway_statusが表示されます。

ステップ7: WhatsApp Business APIクライアントを登録する

WhatsApp Business APIクライアントを登録するには、accountノードに対するAPI呼び出しを使用します。

ステップ8: ヘルスチェックをもう一度実行する

登録完了後、healthノードへのAPI呼び出しを使用して、もう一度WhatsApp Business APIクライアントのヘルスチェックを実行し、Coreappコンテナの1つについてgateway_statusがconnectedになっていることを確認します。

結果の出力は次のようになります。

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

注: ハイアベイラビリティモードでは、1つのCoreapp(この例ではwacore1)だけがWhatsappサーバーに接続され、プライマリMasterを含む他のすべてのノードのgateway_statusはdisconnectedになります。wacore1がダウンした場合は、代わりにwacore2がWhatsappサーバーに接続して、ハイアベイラビリティを維持します。

これで、ハイアベイラビリティモードのWhatsApp Business APIクライアントが設定されました。このモードでは、常に1つのCoreappだけがWhatsAppサーバーに接続してメッセージを送信できます。メッセージのスループットを向上させるために、複数のCoreappが同時にメッセージを送信するようにしたい場合は、以下の「ハイアベイラビリティマルチコネクトクラスタを設定する」セクションの手順に従います。

ハイアベイラビリティマルチコネクトクラスタを設定する

ステップ1: 2つのシャードを設定する

シャードエンドポイントを使用して、2つのシャードを設定します。201 CreatedステータスのHTTP応答が表示されるはずです。

ステップ2: ヘルスチェックを実行する

WhatsApp Business APIクライアントにヘルスチェックを実行するには、healthノードへのAPI呼び出しを使用します。

結果の出力は次のようになります。

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}

注: シャードが2つのマルチコネクトモードでは、2つのCoreapp(この例ではwacore1とwacore2)がWhatsAppサーバーに接続され、プライマリMaster(この例ではmaster2)もWhatsAppサーバーに接続されます。

ステップ3: ハイアベイラビリティを維持するために第3のCoreappを起動する

この例では、Coreappコンテナが2つあり、それらの間でメッセージ負荷が分割されています。ただし、Coreappコンテナの1つがダウンすると、メッセージ送信の半数が失敗します。この新しいマルチコネクト設定でハイアベイラビリティを維持するために、3番目のCoreappを起動すると、1つのCoreappがダウンしても耐えられます。これは、「マルチコネクトについて」の図と同様です。

3番目のCoreappコンテナを起動するには、次のコマンドを実行します。

docker-compose -f multiconnect-compose.yml up -d wacore3

結果の出力は次のようになります。

biz_db_1 is up-to-date
biz_waweb_1 is up-to-date
biz_master1_1 is up-to-date
Creating biz_wacore3_1 ... done

ステップ4: ヘルスチェックをもう一度実行する

healthノードへのAPI呼び出しを使用して、再度ヘルスチェックを実行することにより、すべてのノードが適切に実行されていることを確認します。

結果の出力は次のようになります。

{
    "health": {
        "master1:b28d835cd579": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "master2:7fe542d305b4": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "wacore1:35a5fabfc79d": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore2:05e1a6d70665": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "wacore3:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}

新しいCoreappコンテナ(この例ではwacore3)はスタンバイコンテナとして動作するようになっていますが、この時点ではWhatsAppサーバーに接続していません。wacore1またはwacore2のいずれかが機能しなくなった場合、wacore3がWhatsAppサーバーに接続して、全体のシャード数を2に維持します。

WhatsApp Business APIクライアントのアップグレード

アップグレード処理中はダウンタイムが発生します。

アップグレードする前に、現在のアプリの設定をバックアップして、すぐに復旧して実行できるようにすることを強くおすすめします。「バックアップと復元」のドキュメントをご覧ください。

アップグレードは常に最も忙しくない時間帯に実行することをおすすめします。

ステップ1: WA_API_VERSION環境変数を新規バージョンに変更する

次のコマンドを使用して、WA_API_VERSION環境変数を新しいバージョン番号に更新します。

export WA_API_VERSION=new-whatsapp-version

ステップ2: Dockerコンテナを再起動する

次のコマンドを実行して、Dockerコンテナを再起動します。

docker-compose -f multiconnect-compose.yml up -d

MySQLデータベースユーザーがv2.23.x以上にアップグレードする場合

ダウンタイムを回避するため、アプリの実行中にデータベースをアップグレードできるデータベースアップグレードサービスが利用可能になりました。

ステップ1: 構成ファイルをダウンロードする

dbupgrade-compose.ymlファイルには、コンテナのバージョンを示すフィールドがあります。

例:

services:
  dbupgrade:
    image: docker.whatsapp.biz/coreapp:v${WA_API_VERSION:-2.21.3}

ステップ2: コンテナを起動する

インストール環境をアップグレードするには、次のようにWA_API_VERSION環境変数を最新バージョンに設定して、dbupgrade-serviceコンテナを起動します。

WA_API_VERSION=new-whatsapp-version docker-compose -f dbupgrade-compose.yml up -d

注: 終了時に終了コードにかかわらずコンテナを再起動するオーケストレーションを使用している場合は、EXIT_ON_SUCCESS環境変数をFALSEに設定してサービスを開始し、終了コードが0のときにコンテナが終了しないようにします。

ステップ3: アップグレードが完了するまで待機する

データベースのアップグレードが成功すると、コンテナはコード0で終了します。次のDockerコマンドを使用して、ステータスをトラッキングできます。

docker wait your-database-upgrade-container-name

このコマンドにより、dbupgrade-serviceコンテナの終了コードが出力されます。

ステップ4: CoreappコンテナとWebappコンテナを再起動する

次のようにWA_API_VERSION環境変数を最新バージョンに設定して、CoreappとWebappのDockerコンテナを再起動します。

WA_API_VERSION=new-whatsapp-version docker-compose -f multiconnect-compose.yml up -d

WhatsApp Business APIクライアントのアンインストール

アンインストールする前に、現在のアプリの設定をバックアップすることを強くおすすめします。「バックアップと復元」のドキュメントをご覧ください。

すべてのコンテナを削除して開発環境をリセットする必要がある場合は、multiconnect-compose.ymlファイルを配置したディレクトリから次のコマンドを実行します。

docker-compose -f multiconnect-compose.yml down

コンテナに加え、multiconnect-compose.ymlファイルで定義されているすべてのボリュームも削除するには、-vパラメーターを指定してdownを実行します。

docker-compose -f multiconnect-compose.yml down -v

トラブルシューティング

すべてのコンテナからログを収集するには、次のコマンドを実行します:

docker-compose -f multiconnect-compose.yml logs > debug_output.txt

特定のサービスのログを収集するには、サービス名(waweb、master1、wacore1など)をdocker-compose logsコマンドの末尾に追加します。

docker-compose -f multiconnect-compose.yml logs waweb > debug_output.txt

ログは、現在のディレクトリのdebug_output.txtファイルに作成されます。

このソフトウェアでは、LGPLv2.1でライセンス付与されているFFmpegのコードを使用しています。ソースはこちらからダウンロードできます。