프로덕션 설정: 단일 인스턴스

이 문서에서는 프로덕션에서 WhatsApp Business API 클라이언트의 단일 인스턴스를 설정하는 방법을 안내합니다.

시작하기 전에

다음과 같은 항목이 필요합니다.

• Docker
• Docker Compose
  

  • Docker 설치와 함께 번들로 제공되어야 하지만, 제공되지 않은 경우 설치할 수 있습니다.
• WhatsApp Business API 클라이언트를 실행할 서버

  • 시스템 요구 사항은 FAQ에서 WhatsApp Business API 클라이언트를 실행하기 위한 서버 시스템 요구 사항은 무엇인가요?를 참조하세요.
• MySQL 또는 PostgreSQL 프로세스를 실행하는 독립형 데이터베이스 서버

  • 데이터베이스 서버는 WhatsApp Business API 클라이언트를 호스팅하는 서버에서 지연이 몇 밀리초 이내로만 발생해야 합니다.

WhatsApp Business API 클라이언트의 최초 설정

1단계: 설정 스크립트를 위한 biz 디렉터리 만들기

WhatsApp Business API 클라이언트의 원하는 위치에서 다음 코드를 실행합니다.

mkdir ~/biz; cd ~/biz;

2단계: WhatsApp Business API 클라이언트 구성 파일 가져오기

WhatsApp-Business-API-Setup-Scripts GitHub 리포지토리의 설치 디렉터리에 있는 prod-docker-compose.yml과 db.env 구성 파일을 1단계에서 생성한 ~/biz 디렉터리로 복사합니다.

3단계: WA_API_VERSION 환경 변수 설정

WA_API_VERSION 환경 변수는 다음을 사용하여 최신 버전으로 설정해야 합니다.

export WA_API_VERSION=current-whatsapp-version

4단계: 데이터베이스 환경 변수 설정

~/biz 디렉터리에 있는 db.env 파일의 데이터베이스 환경 변수를 MySQL/PostgreSQL 구성에 맞게 변경합니다.

WA_DB_ENGINE=MYSQL | PGSQL
WA_DB_HOSTNAME=your-database-server
WA_DB_PORT=your-database-server-port
WA_DB_USERNAME=your-database-username
WA_DB_PASSWORD=your-database-password

5단계: 로컬 미디어 볼륨 설정

prod-docker-compose.yml 파일에 정의된 로컬 미디어 볼륨(기본값: whatsappMedia:/usr/local/wamedia)을 미디어 파일 저장에 사용합니다. 기본적으로 이 볼륨은 Docker 기기의 디렉터리에 마운팅됩니다. 또는 미디어 볼륨을 호스트 디렉터리에 마운팅할 수도 있습니다. 미디어 볼륨의 마운트 지점을 변경하려면 whatsappMedia에서 services 섹션 내의 볼륨 정의를 사용 중인 호스트 디렉터리의 경로로 변경하세요.

services:
  wacore:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ...          
  waweb:
    ...
    volumes:
      - /your-local-media-volume-path:/usr/local/wamedia
    ... 

6단계: WhatsApp Business API 클라이언트 시작

Webapp 컨테이너 1개 및 Coreapp 컨테이너 1개를 포함한 WhatsApp Business API 클라이언트를 시작하려면 다음을 실행하세요.

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

결과로 나오는 출력은 다음과 같습니다.

Creating biz_wacore_1 ... done
Creating biz_waweb_1  ... done

7단계: 컨테이너가 실행 중인지 확인

다음을 실행하여 모든 컨테이너가 UP 상태인지 확인할 수 있습니다.

docker-compose -f prod-docker-compose.yml  ps

결과로 나오는 출력은 다음과 같습니다.

     Name                    Command               State                   Ports
-------------------------------------------------------------------------------------------------
biz_wacore_1   /opt/whatsapp/bin/wait_on_ ...   Up      6250/tcp, 6251/tcp, 6252/tcp, 6253/tcp
biz_waweb_1    /opt/whatsapp/bin/wait_on_ ...   Up      0.0.0.0:9090->443/tcp

기본적으로 Webapp 컨테이너는 9090 포트에서 실행됩니다.

8단계: 상태 점검 수행

health 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트에 상태 점검을 수행할 수 있습니다.

결과로 나오는 출력은 다음과 같습니다.

{
    "health": {
        "gateway_status": "unregistered"
    }
}

응답에서는 unregistered의 gateway_status가 gateway_status로 표시되는데, WhatsApp Business API 클라이언트가 아직 등록되지 않았기 때문입니다.

9단계: WhatsApp Business API 클라이언트 등록

account 노드에 API 호출을 보내서 WhatsApp Business API 클라이언트를 등록할 수 있습니다.

10단계: 두 번째 상태 점검 수행

등록을 완료한 후에 health 노드로 API 호출을 보내서 WhatsApp Business API 클라이언트에 다시 한 번 상태 점검을 수행합니다.

결과로 나오는 출력은 다음과 같습니다.

{
    "health": {
        "gateway_status": "connected"
    }
}

connected의 gateway_status는 Coreapp 컨테이너가 WhatsApp 서버로 연결되어 연락처를 확인하고 메시지를 전송할 수 있다는 의미입니다.

WhatsApp Business API 클라이언트 업그레이드

1단계: WA_API_VERSION 환경 변수를 새 버전으로 변경

WA_API_VERSION 환경 변수는 다음을 사용하여 새 버전 번호로 업데이트해야 합니다.

export WA_API_VERSION=new-whatsapp-version

2단계: Docker 컨테이너 다시 시작

다음을 실행하여 Docker 컨테이너를 다시 시작합니다.

docker-compose -f prod-docker-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 prod-docker-compose.yml up -d

WhatsApp Business API 클라이언트 사용자를 2.29.3 버전 이상으로 업그레이드

v2.29.1, v2.29.2에서 업그레이드하고 있거나 또는 해당 버전으로 업그레이드 중에 문제가 발생해서 안정화를 위해 롤백해야 할 경우, v2.29.3으로 업그레이드한 다음 Webapp Docker 컨테이너에서 다음 명령을 실행하는 것이 좋습니다.

chown -R root your-media-directory/incoming your-media-directory/outgoing your-media-directory/shared

변경하지 않은 경우 기본 미디어 디렉터리는 /usr/local/wamedia입니다.

참고:

• 이 명령은 기존의 미디어 볼륨 크기에 따라 완료하는 데 다소 시간이 걸릴 수 있으므로 유지관리 기간에 업그레이드하는 즉시 이 명령을 시작하는 것이 좋습니다.
• 이 명령은 백그라운드에서 미디어 볼륨의 소유권만 수정합니다(미디어 작업에 대한 영향/가동 중단이나 실행 도중에 지연/성능 저하가 발생하지 않습니다).
• v2.29.1과 v2.29.2에서 이전 버전 호환성 문제를 해결하기 위한 일회성 업그레이드 경로입니다.

WhatsApp Business API 클라이언트 제거

모든 컨테이너를 삭제하여 개발 환경을 재설정해야 하는 경우 prod-docker-compose.yml 파일이 포함된 디렉터리에서 다음 명령을 실행하세요.

docker-compose -f prod-docker-compose.yml down

결과로 나오는 출력은 다음과 같습니다.

Stopping biz_waweb_1  ... done
Stopping biz_wacore_1 ... done
Removing biz_waweb_1  ... done
Removing biz_wacore_1 ... done

컨테이너와 함께 prod-docker-compose.yml 파일에 정의된 모든 볼륨을 제거하려면 -v 매개변수로 down 명령을 실행하세요.

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

문제 해결

WADebug를 사용할 수 없거나 도구 반환 오류를 실행하는 경우 다음 명령을 실행하여 모든 컨테이너에서 로그를 수집하세요.

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

특정 서비스의 로그를 수집하려면 서비스 이름(waweb 또는 wacore)을 docker-compose logs 명령에 추가하세요.

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

현재 디렉터리의 debug_output.txt 파일에서 로그를 찾을 수 있습니다.