Configuración de producción: alta disponibilidad y conexión múltiple

Este documento te indica cómo configurar un grupo de alta disponibilidad en producción. También proporciona orientación sobre cómo activar la conexión múltiple y describe los cambios necesarios para un grupo de conexión múltiple de alta disponibilidad.

Antes de empezar con cualquiera de estas configuraciones, comprueba nuestros requisitos.

Para configurar un grupo de alta disponibilidad:

1. Crea un directorio biz para los scripts de configuración.
2. Obtén los archivos de configuración del cliente de la API de WhatsApp Business.
3. Establece las variables de entorno de la base de datos.
4. Configura el volumen de contenido multimedia local.
5. Inicia el cliente de la API de WhatsApp Business.
6. Verifica que los contenedores se están ejecutando.
7. Realiza una comprobación de estado.
8. Registra el cliente de la API de WhatsApp Business.
9. Realiza una comprobación de estado.

Para configurar un grupo de conexión múltiple de alta disponibilidad:

1. Configura dos particiones.
2. Realiza una comprobación de estado.
3. Inicia una tercera aplicación principal para mantener la alta disponibilidad.
4. Realiza una segunda comprobación de estado.

Una vez que hayas configurado la instancia por completo, puedes elegir actualizarla. Para desinstalar el cliente, sigue estos pasos.

Antes de empezar

Necesitarás lo siguiente:

• Varios servidores de ordenadores para ejecutar los distintos componentes del cliente de la API de WhatsApp Business (p. ej., aplicación web, maestro y aplicación principal).

  • Para conocer los requisitos del sistema, consulta ¿Cuáles son los requisitos del sistema del servidor para ejecutar el cliente de la API de WhatsApp Business? en las preguntas frecuentes.
  • Para una configuración de alta disponibilidad en producción, recomendamos al menos una máquina para el contenedor de la aplicación web, dos máquinas para los contenedores de la aplicación principal y dos máquinas para los contenedores maestros. Las cargas en los maestros son ligeras y puedes ubicar los contenedores maestros y de aplicación principal en el mismo host.
• Instala Docker Desktop y Docker Compose.
• Un servidor de base de datos independiente que ejecuta un proceso MySQL o PostgreSQL.

  • El servidor de base de datos no debe ejecutarse en ninguno de los otros servidores que alojan el cliente de la API de WhatsApp Business y debe estar a pocas milésimas de segundo de latencia de los demás servidores.

• Un sistema de archivos compartidos (p. ej., NFS) montado en un directorio local en todos los hosts de aplicación web, maestros y de aplicación principal si quieres que se puedan enviar y recibir mensajes multimedia.

  • Asegúrate de que 755 está establecido como el modo de archivo en la ruta de montaje y todos los subdirectorios.

mkdir your-local-media-volume-path
mount -t nfs nfs_server_IP_addr:/shared_directory /your-local-media-volume-path

Configuración de un grupo de alta disponibilidad

Paso 1: Crear un directorio biz para los scripts de configuración

Ejecuta el siguiente código en tu ubicación preferida para el cliente de la API de WhatsApp Business:

mkdir ~/biz; cd ~/biz;

Paso 2: Obtener los archivos de configuración del cliente de la API de WhatsApp Business

Clona los archivos de configuración prod-multiconnect-compose.yml y db.env del directorio de instalación del repositorio de GitHub WhatsApp-Business-API-Setup-Scripts en el directorio ~/biz que creaste en el paso 1.

Paso 3: Establecer las variables de entorno de la base de datos

Cambia las variables de entorno de la base de datos en el archivo db.env del directorio ~/biz para reflejar tu configuración de 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

Paso 4: Configurar el volumen de contenido multimedia local

El volumen de contenido multimedia local (whatsappMedia:/usr/local/wamedia de forma predeterminada) definido en el archivo prod-docker-compose.yml se utiliza para almacenar archivos multimedia. De forma predeterminada, el volumen se monta en un directorio de la máquina Docker. También puedes montar el volumen de contenido multimedia en un directorio del host. Para cambiar el punto de montaje del volumen de contenido multimedia, modifica la definición del volumen de la sección services de whatsappMedia y cámbiala por el directorio del host que estás utilizando.

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

Paso 5: Iniciar el cliente de la API de WhatsApp Business

Para iniciar el cliente de la API de WhatsApp Business con un contenedor de aplicación web, dos contenedores maestros y dos contenedores de aplicación principal de forma similar al diagrama de introducción a la alta disponibilidad, utiliza los siguientes comandos con los cambios necesarios para tu entorno (es decir, nombres del host, nombres de usuario del host y rutas locales):

# copy configuration scripts to each Webapp host, ssh to each Webapp host, execute scripts to install Webapp on the host
for host in your-webapp-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd waweb
done 
# copy configuration scripts to each Master host, ssh to each Master host, execute scripts to install Master on the host
for host in your-master1-hostname your-master2-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd master
done
# copy configuration scripts to each Coreapp host, ssh to each Coreapp host, execute scripts to install Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

En resumen, los comandos anteriores harán lo siguiente:

• copiar los archivos de configuración prod-multiconnect-compose.yml y db.env en todos los hosts de la aplicación web (your-webapp-hostname en este ejemplo) e iniciar el servicio waweb en estos hosts;
• copiar los archivos de configuración prod-multiconnect-compose.yml y db.env en todos los hosts maestros (your-master1-hostname y your-master2-hostname en este ejemplo) e iniciar el servicio maestro en estos hosts;
• copiar los archivos de configuración prod-multiconnect-compose.yml y db.env en todos los hosts de la aplicación principal (your-coreapp1-hostname y your-coreapp2-hostname en este ejemplo) e iniciar el servicio wacore en estos hosts.

Paso 6: Verificar que los contenedores se están ejecutando

Puedes comprobar que todos los contenedores tienen estado EN EJECUCIÓN ejecutando:

EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f prod-multiconnect-compose.yml ps

Paso 7: Realizar una comprobación de estado

Puedes realizar una comprobación de estado en el cliente de la API de WhatsApp Business utilizando una llamada a la API del nodo health.

La salida resultante debería tener el siguiente aspecto:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "unregistered",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "errors": [
              {
                  "code": 1011,
                  "title": "Service not ready",
                  "details": "Wacore is not instantiated. Please check wacore log for details."
              }
            ]
        }
    }
}
200

La respuesta muestra un valor unregistered en el parámetro gateway_status como parámetro gateway_status porque el cliente de la API de WhatsApp Business aún no está registrado.

Paso 8: Registrar el cliente de la API de WhatsApp Business

Puedes registrar el cliente de la API de WhatsApp Business mediante una llamada de API al nodo account.

Paso 7: Realizar una segunda comprobación de estado

Realiza otra comprobación de estado en el cliente de la API de WhatsApp Business mediante una llamada de API al nodo health después de completar el registro y asegúrate de que uno de los contenedores de la aplicación principal tiene un valor de connected en el parámetro gateway_status.

La salida resultante debería tener el siguiente aspecto:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}
200

Nota:En el modo de alta disponibilidad, solo se conectará una aplicación principal (your-coreapp1-hostname:753efb1cf72c en este ejemplo) al servidor de WhatsApp y los demás nodos, incluido el maestro principal, tendrán el valor disconnected en el parámetro gateway_status. Si se cae your-coreapp1-hostname:753efb1cf72c, your-coreapp2-hostname:75d7355eaaaa lo sustituirá y se conectará al servidor de WhatsApp para mantener la alta disponibilidad.

Ya has configurado el cliente de la API de WhatsApp Business en modo de alta disponibilidad. En este modo, solo una aplicación principal se puede conectar al servidor de WhatsApp y enviar mensajes en cualquier momento. Si quieres tener varias aplicaciones principales enviando mensajes al mismo tiempo para aumentar el rendimiento de los mensajes, sigue los pasos en la sección Configuración de un grupo de conexión múltiple de alta disponibilidad a continuación.

Configuración de un grupo de conexión múltiple de alta disponibilidad

Paso 1: Configurar dos particiones

Usa el extremo de particiones para configurar dos particiones. Deberías ver una respuesta HTTP con el estado 201 Created.

Paso 2: Realizar una comprobación de estado

Puedes realizar una comprobación de estado en el cliente de la API de WhatsApp Business mediante una llamada de API al nodo health para verificar que todos los nodos se están ejecutando correctamente.

La salida resultante debería tener el siguiente aspecto:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "connected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "connected",
            "role": "coreapp"
        }
    }
}      
200    

Nota: En el modo de conexión múltiple con dos particiones, se conectarán dos aplicaciones principales (your-coreapp1-hostname:753efb1cf72c y your-coreapp2-hostname:75d7355eaaaa en este ejemplo) al servidor de WhatsApp, y el maestro principal (your-master2-hostname:8dd3f5bea27d en este ejemplo) también se conectará al servidor.

Paso 3: Iniciar una tercera aplicación principal para mantener la alta disponibilidad

Hasta ahora en este ejemplo, tienes dos contenedores de aplicación principal y las cargas de los mensajes se dividen entre los dos. Sin embargo, si se cae uno de los contenedores de aplicación principal, la mitad de los mensajes no se enviará. A fin de mantener la alta disponibilidad en esta nueva configuración de conexión múltiple, puedes iniciar una tercera aplicación principal en un nuevo host de aplicación principal (

en este ejemplo) para que se permita el fallo de una aplicación principal, de forma similar al diagrama que se muestra en la sección Introducción a la conexión múltiple.

Para iniciar el tercer contenedor de la aplicación principal, ejecuta el siguiente comando:

# copy configuration scripts to the 3rd Coreapp host, ssh to the Coreapp host, execute scripts to install Coreapp on the host
for host in your-coreapp3-hostname; do
    scp db.env prod-multiconnect-compose.yml username@$host:/local/path/
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

Paso 4: Realizar una segunda comprobación de estado

Realiza otra comprobación de estado para verificar que todos los nodos se están ejecutando correctamente utilizando una llamada de API al nodo health.

La salida resultante debería tener el siguiente aspecto:

{
    "health": {
        "your-master1-hostname:85cdd51506fd": {
            "gateway_status": "disconnected",
            "role": "secondary_master"
        },
        "your-master2-hostname:8dd3f5bea27d": {
            "gateway_status": "disconnected",
            "role": "primary_master"
        },
        "your-coreapp1-hostname:753efb1cf72c": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp2-hostname:75d7355eaaaa": {
            "gateway_status": "connected",
            "role": "coreapp"
        },
        "your-coreapp3-hostname:23b50199bec2": {
            "gateway_status": "disconnected",
            "role": "coreapp"
        }
    }
}      
200 

El nuevo contenedor de aplicación principal (your-coreapp3-hostname:23b50199bec2 en este ejemplo) actúa ahora como contenedor en espera, pero no está conectado en este momento al servidor de WhatsApp. Si alguno de los otros dos contenedores de aplicación principal conectados deja de funcionar, el tercer contenedor se conectará al servidor de WhatsApp para mantener un número total de dos particiones.

Normas y prácticas recomendadas

Número de aplicaciones web

Para que se puedan admitir 100-150 mensajes/segundo, se recomiendan al menos dos aplicaciones web. Si quieres alcanzar una alta disponibilidad para aplicación web, puedes ejecutar contenedores de aplicación web en más de dos hosts y alojarlos tras un equilibrador de carga como HAProxy, Nginx o ELB. En lugar de acceder a los extremos del cliente de la API de WhatsApp Business a través de https://your-webapp-hostname:your-webapp-port/, debes usar https://your-load-balancer-name:your-load-balancer-port/.

Número de maestros

Se recomienda tener tres maestros ejecutándose en distintos hosts. No hay ninguna razón para tener más de tres maestros en producción independientemente de cuántas particiones tengas. Las cargas en los maestros son ligeras y las puedes ubicar junto con contenedores de aplicación principal.

Número de aplicaciones principales

Se recomienda tener un número de aplicaciones principales igual a shard_number + X ejecutándose en distintos hosts para que se admita un número X de fallos del host.

Actualizar el cliente de la API de WhatsApp Business

La variable de entorno WA_API_VERSION debe actualizarse al nuevo número de versión. Ejecuta los siguientes comandos con los cambios necesarios para tu entorno (es decir, nombres del host, nombres de usuario del host y rutas locales):

# ssh to each Webapp host, execute scripts with new WA_API_VERSION to upgrade Webapp on the host
for host in your-webapp-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd waweb
done
# ssh to each Master host, execute scripts with new WA_API_VERSION to upgrade Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts with new WA_API_VERSION to upgrade Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname your-coreapp3-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.x docker-compose -f /local/path/prod-multiconnect-compose.yml up -d"
    ssh username@$host $cmd wacore
done

Para los usuarios de la base de datos MySQL que actualizan a la versión 2.23.x y posteriores

Ahora se puede hacer uso del servicio de actualización de la base de datos, que permite actualizar la base de datos mientras la aplicación se ejecuta para evitar tiempos de inactividad.

Paso 1: Descargar el archivo de configuración

El archivo dbupgrade-compose.yml contiene campos que indican la versión del contenedor.

Ejemplo:

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

Paso 2: Iniciar el contenedor

Para actualizar una instalación, inicia el contenedor de servicio “dbupgrade” con la variable de entorno WA_API_VERSION establecida en la versión más reciente:

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

Nota: Si vas a utilizar una orquestación que reinicia el contenedor al salir independientemente del código de salida, inicia el servicio con la variable de entorno EXIT_ON_SUCCESS establecida en FALSE para evitar salir del contenedor cuando el código de salida sea 0.

Paso 3: Permitir que finalice la actualización

Si la actualización de la base de datos se realiza correctamente, el contenedor saldrá con el código 0. Puedes utilizar el siguiente comando Docker para hacer un seguimiento del estado:

docker wait your-database-upgrade-container-name

Esta operación mostrará el código de salida del contenedor de servicio “dbupgrade”.

Paso 4: Reiniciar los contenedores de la aplicación principal y la aplicación web

Reinicia los contenedores de la aplicación principal y la aplicación web con la variable de entorno WA_API_VERSION establecida en la versión más reciente:

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

Para usuarios del cliente de la API de WhatsApp Business que actualizan a la versión 2.29.3 y posteriores

Si estás actualizando desde las versiones v2.29.1 o v2.29.2, o has experimentado problemas durante la actualización a esas versiones y has tenido que retroceder para ganar estabilidad, te recomendamos que actualices a la versión v2.29.3 y ejecutes el siguiente comando en el contenedor de Docker de la aplicación web:

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

A menos que lo hayas cambiado, el directorio de contenido multimedia predeterminado es /usr/local/wamedia.

Nota:

• Dado que es posible que este comando tarde un tiempo en completarse debido al tamaño del volumen de contenido multimedia que ya estaba presente, te recomendamos que lo inicies en cuanto hayas realizado la actualización durante el periodo de mantenimiento.
• Este comando solo modifica la propiedad de los volúmenes de contenido multimedia en segundo plano (no afecta a las operaciones multimedia ni genera tiempo de inactividad, ni tampoco influye en la latencia/rendimiento mientras se está ejecutando).
• Esta es una ruta de actualización única que tiene por objetivo corregir problemas de compatibilidad en las versiones v2.29.1 y v2.29.2.

Desinstalar el cliente de la API de WhatsApp Business

Si necesitas restablecer tu entorno de desarrollo eliminando todos los contenedores, utiliza los siguientes comandos con los cambios necesarios para tu entorno (es decir, nombres del host, nombres de usuario del host y rutas locales):

# ssh to each Webapp host, execute scripts to uninstall Webapp on the host
for host in your-webapp-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd waweb
done
# ssh to each Master host, execute scripts to uninstall Master on the host
for host in your-master1-hostname your-master2-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd master
done
# ssh to each Coreapp host, execute scripts to uninstall Coreapp on the host
for host in your-coreapp1-hostname your-coreapp2-hostname your-coreapp3-hostname; do
    cmd="EXTERNAL_HOSTNAME=$host WA_API_VERSION=2.23.4 docker-compose -f /local/path/prod-docker-compose.yml down"
    ssh username@$host $cmd wacore
done

Solución de problemas

Para obtener los registros de todos los contenedores de un host, ejecuta el comando siguiente:

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-multiconnect-compose.yml logs > debug_output.txt

Para obtener los registros de un servicio determinado, añade el nombre del servicio (p. ej., waweb, master1, wacore1) al comando docker-compose logs.

EXTERNAL_HOSTNAME=$host_to_collect_logs docker-compose -f /local/path/prod-multiconnect-compose.yml logs waweb > debug_output.txt

Encontrarás los registros en el archivo debug_output.txt del directorio actual.