Installation

WorkersCore est l'application Symfony au cœur du fonctionnement du module Workers. Elle est disponible sous la forme d'une archive à installer sur un serveur, dédié ou non.

Prérequis

• php >= 8.1

WorkersCore est une application Symfony et nécessite donc l'interpréteur PHP.

• sqlite >= 3.34

WorkersCore utilise une base de données sqlite pour gérer sa file de messages.

• libpq-dev >= 13.10 et le driver pdo_pgsql

WorkersCore doit pouvoir communiquer avec une base de données PostgreSQL (pour la fonctionnalité DashboardETL).

Attention

Installez également les dépendances de chacune des fonctionnalités que vous souhaitez activer.

Télécharger et décompresser l'archive

Informations

• Cette étape doit être faite dans un projet AP4 initialisé.
• Si vous n'avez pas de projet AP4 initialisé, vous pouvez demander à votre intégrateur.

Installez le paquet @anakeen/workers à l'aide de la commande :

npx @anakeen/anakeen-platform install --flavour custom --cwd .

Décompressez l'archive qui nous intéresse node_modules/@anakeen/workers/zip/workers-core-x.x.x.zip dans le répertoire voulu. Par la suite, nous ferons référence à ce répertoire à l'aide de la variable WORKERS_HOME.

Configuration

Rendez-vous dans $WORKERS_HOME/workers.

Informations

Le point d'entrée de toutes les commandes de l'application est le script php bin/console. La liste des commandes est disponible ici.

Configurer les variables d'environnement

Il faut dans un premier temps définir la liste des fonctionnalités à activer dans $WORKERS_HOME/workers/.env.local :

FEATURES=FEATURE1,FEATURE2,...

où FEATURE1 et FEATURE2 sont des noms de fonctionnalités (par exemple ExtendedSmartField ou DashboardETL).

Chacune des fonctionnalités ayant des variables d'environnement dédiées, il est possible de lister à tout moment les variables manquantes avec la commande :

php bin/console status

Voici néanmoins la liste des variables pour chacune des fonctionnalités :

Variables communes

Variable	Description	Exemple	Obligatoire
FEATURES	Liste des fonctionnalités activées	ExtendedSmartField,DashboardETL
AP4_DOMAIN	URL du serveur AP4	http://127.0.0.1:8080

Variables ExtendedSmartField

Variable	Description	Exemple	Obligatoire
TOKEN_EXTENDEDSMARTFIELD	Jeton d'accès HTTP fourni par AP4	-

Variables DashboardETL

Variable	Description	Exemple	Obligatoire
TOKEN_DASHBOARDETL	Jeton d'accès HTTP fourni par AP4	-
DASHBOARD_PSQL_HOST	Nom d'hôte du serveur de base de données	127.0.0.1
DASHBOARD_PSQL_PORT	Port du serveur de base de données	5432
DASHBOARD_PSQL_DB	Nom de la base de données dédiée	dashboard
DASHBOARD_PSQL_USER	Nom d'utilisateur de la base de données	anakeen
DASHBOARD_PSQL_PASSWORD	Mot de passe de la base de données	password
DASHBOARD_DELAY_BETWEEN_SYNC	Délai (en secondes) entre deux synchronisations avec AP4	60 (par défaut)
DASHBOARD_MAX_DELAY_RETRY_UPDATE	Délai maximum (en secondes) entre deux mises à jour échouées d'un élément, ce délai augmente avec le nombre d'essais sans pour autant dépasser ce maximum $delay = 2 ** $retries	3600 (par défaut)

Générer les jetons d'accès

Les workers ont besoin d'un jeton HTTP pour communiquer de manière sécurisée avec AP4. Un token est nécessaire par fonctionnalité activée. Pour générer ces jetons, il suffit de lancer la commande suivante auprès d'AP4 :

./ank.php --script=generateWorkerToken --feature=FEATURE1,FEATURE2,...

FEATURE1,FEATURE2,... étant la liste des fonctionnalités pour lesquelles générer un token.

Vérification

La configuration peut être analysée à tout moment :

php bin/console status

Cette commande vérifie la définition des variables et effectue des tests spécifiques à chacune des fonctionnalités (tests de connexions à AP4, à la base de données, etc.).

Initialiser le contexte

Avant de déployer les workers, il est nécessaire d'initialiser le contexte à l'aide de la commande :

php bin/console context:init

Lancement des services

WorkersCore peut être lancé sous forme de service Supervisor ou sous forme de service systemd. Ces derniers vont superviser un ensemble de workers pour chacune des fonctionnalités activées.

Lancement par supervisor

Enregistrement pour lancement par supervisor

1. Générer un exemple de fichier de configuration :

   php bin/console conf:generate

2. Copier le fichier de configuration généré ank-workers.conf dans le répertoire de configuration de Supervisor :

   • Sur Debian/Ubuntu :

   # cp ank-workers.conf /etc/supervisor/conf.d/ank-workers.conf

   • Sur RedHat/CentOS :

   # cp ank-workers.conf /etc/supervisor.d/ank-workers.ini

3. Ajouter si nécessaire la directive user pour référencer l'utilisateur système sous lequel seront exécutés les services.

4. Ajuster si nécessaire le nombre de workers dédiés à chacune des tâches :

   [program:task1]
   ...
   numprocs=x

   où x est le nombre de workers qui seront déployés pour la tâche task1.

5. Activer les services :

   supervisorctl reread
   supervisorctl update

Démarrage/Arrêt des workers

• Démarrer tous les workers :

  supervisorctl start ank-workers:\*

• Arrêter tous les workers :

  supervisorctl stop ank-workers:\*

• Redémarrer tous les workers :

  supervisorctl restart ank-workers:\*

• Voir le statut des workers :

  supervisorctl status ank-workers:\*

Lancement par systemd

Enregistrement pour lancement par systemd

1. Générer un exemple de fichiers de configuration :

   php bin/console conf:generate --pcs=systemd

2. Copier les fichiers de configuration dans le répertoire de configuration de systemd :

   cp *.service /usr/lib/systemd/system/

3. Ajouter si nécessaire la directive User pour référencer l'utilisateur système sous lequel seront exécutés les services.

4. Ajuster si nécessaire le nombre de workers dédiés à chacune des tâches dans ank-workers.service :

   Requires=task@1.service task@2.service ... task@x.service

   où x est le nombre de workers qui seront déployés pour la tâche task.

5. Activer les services :

   systemctl enable ank-workers

Démarrage/Arrêt des services

• Démarrer tous les services :

  systemctl start ank-workers

• Arrêter tous les services :

  systemctl stop ank-workers

• Redémarrer tous les services :

  systemctl restart ank-workers

• Voir le statut des services :

  systemctl status ank-workers

Préconisations sur le nombre de workers

Fonctionnalité	Nom du worker	Nombre préconisé
ExtendedSmartField	esf-worker	5
DashboardETL	dashboard-sync	1
DashboardETL	dashboard-update	2

Recommandation

Le nombre de workers est évidemment à adapter en fonction de l'activité supposée de votre application.