Portail

Le portail parent du module crèche permet aux parents de communiquer avec les structures. Il est divisé en deux modules indépendant activables par configuration. Les deux modules sont :

Préinscription qui concerne la partie permettant au parent de déclarer un nouvel enfant et ses besoins
Communication qui permet au parent de gérer son profil et l’activité de ses enfants

Toutes ces actions sont accessibles par un unique portail lié à une ou plusieurs sociétés SAINet. L’objectif de cette documentation, dédiée aux utilisateurs de type Super-administrateurs est d’exprimer les étapes pour déployer ce portail et configurer les éléments initiaux.

La partie configuration des fonctionnalités SAINet se trouve dans la documentation pré-inscription et la documentation portail de communication.

Pré-requis de déploiement

Dans SYS01, créer une nouvelle société. Par convention, les sociétés avec un seul portail global sur le serveur utilisent l’identifiant POR.

Dans les modules de la société, sélectionner la configuration de modules qui contient le module creche_portal. Cette configuration est généralement appellée également creche_portal par convention.

Une autre étape nécessaire est la déclaration de la société qui contiendra la configuration de toutes les fonctionnalités du portail. Il n’est pas nécessaire à ce point de configurer les fonctionnalités mais il est obligatoire d’en définir la base.

Le paramétrage des fonctionnalités disponibles dans le portail parents s’effectue dans la chaîne UNI de SAINet. Il est donc nécessaire de créer une nouvelle entrée POR (si la société du portail est POR) dans UNI91. Afin de pouvoir faire cette saisie, l’utilisateur courant doit avoir accès à la société POR dans SYS02.

Note:

Il est important que le domaine du portail (POR) soit déclaré au niveau des différentes tâches 01 (SAL01, CRM01, GTP01 et DEB01).

Création d’un compte utilisateur

Pour se connecter à SAINet, il est nécessaire de créer un compte de service sous la forme d’un utilisateur dans SYS02 dont les informations seront fournies à la configuration du portail parents. Ce compte doit pouvoir accéder à toutes les sociétés qui concernent les enfants et qui seront disponibles à travers le portail.

Afin d’éviter tout problème lié à l’expiration du mot de passe, il est conseillé de mettre une date de fin de validité suffisamment grande. Cette opération nécessite un accès direct à la base de données.

Création d’un groupe

Il est conseillé de créer un groupe PORTAIL en SYS03 afin d’y attacher l’utilisateur et de créer ensuite les droits nécessaires pour ce groupe via les tâches SYS04 et SYS07. L’utilisateur doit avoir les accès suivants:

Tâche	Accès	Remarques
`SYS00`	Accès en lecture et exécution.	Accès obligatoire pour la connexion des utilisateurs portail.
`UNI91`	Accès en lecture.	Accès obligatoire.
`SAL01`	Accès en lecture.	Accès obligatoire.
`CRM06`	Accès en lecture/écriture.	Accès obligatoire.
`CRM07`	Accès en lecture/écriture.	Accès obligatoire.
`CRM40`	Accès en lecture/écriture.	Accès obligatoire.
`GTP01`	Accès en lecture.	Accès obligatoire pour lire les configurations.
`GTP11`	Accès en lecture/écriture.	Accès obligatoire.
`GTP12`	Accès en lecture/écriture.	Accès obligatoire.
`UNI42`	Accès en lecture/écriture.	Accès obligatoire.
`DEB02`	Accès en lecture.	Uniquement si le portail permet aux parents d’accéder à leur factures.
`DEBED`	Accès en lecture.	Nécessaire si accès au `DEB02`.
`DEBOF`	Accès en lecture.	Nécessaire si accès au `DEB02`.
`DEB54`	Accès en lecture.	Nécessaire si accès au `DEB02`.
`DEB65`	Accès en lecture.	Nécessaire si accès au `DEB02`.

Docker

Afin de simplifier le déploiement, une image docker est disponible permettant en quelques lignes d’avoir un portail opérationnel facilement maintenable. Cette image s’appelle saierp/portal. La version de l’image dépend du serveur pointé. Par exemple, pour un serveur en version 4.10, l’image sera saierp/portal:4.10.

Afin de pouvoir déployer l’image, il est nécessaire d’avoir docker installé sur la machine.

Configuration et déploiement

Afin de déployer l’image, créer un fichier docker-compose.yml avec le contenu suivant :

version: "3.0"

services:
  sainet_portal:
    restart: always
    image: saierp/portal:4.11
    environment:
      - <variable>=<valeur>
      - ...
    volumes:
      - "./portal/app:/usr/src/app"
      - "./portal/update:/usr/src/update"
    ports:
      - "<port>:3001"

Le <port> correspond au port externe d’écoute de l’image docker. En interne, le port 3001 est utilisé. Il peut être changé dans les variables d’environnement ce qui n’est pas utile dans le cadre d’un déploiement docker.

Il est également nécessaire de configurer les deux volumes persistants sur /usr/src/app et /usr/src/update afin que les mises à jour automatiques puissent être appliquées.

La liste des variables principales se trouve ci-dessous:

Variable	Requis	Valeur	Définition
`SAINET_URL`	oui	`https://<host>/SNV4SRV-mobile-war/`	Le lien vers l’interface mobile d’un serveur SAINet.
`SAINET_USER`	oui	`string`	L’utilisateur du compte de service pour le lien avec SAINet.
`SAINET_PASS`	oui	`string`	Le mot de passe du compte de service.
`SAINET_DOMAIN`	oui	`string`	L’identifiant du domaine du portail qui sera utilisé pour la gestion.
`SAINET_MODULE`		`string`	Type de portail (REG ou CRE). Par défaut `CRE`.
`SAINET_APP_NAME`		`string`	Intitulé du portail. Par défaut ‘SAINet’.
`SAINET_NPM_AUTH_TOKEN`	oui	`string`	Token d’authentification pour que le portail puisse être compilé (également lors des mises à jour). Cette valeur est fournie par SAI ERP.
`SAINET_SUB_SITE_KEY`	*	`string`	La clé pour le captcha de google dans le cas où l’inscription est disponible.
`SAINET_SUB_SECRET_KEY`	*	`string`	La clé secrète pour vérifier le catpcha dans le cas où l’inscription est disponible.

Les variables SAINET_SUB_SITE_KEY et SAINET_SUB_SECRET_KEY peuvent être récupérées sur Google reCAPTCHA v2 (voir ici). Ces variables sont obligatoires lorsqu’un utilisateur peut s’enregistrer par lui-même.

Note:

Le portail s’attend à des requêtes HTTP. En cas de redirection HTTPS vers HTTP en amont (via Apache ou Traefik), il est nécessaire d’insérer le header X-Forwarded-Proto avec la valeur https sinon le mode NODE_ENV=production ne fonctionnera pas.

Les variables complémentaires suivantes sont également disponibles:

Variable	Type	Définition
`SAINET_ROOT_DIR`	`string`	Chemin d’installation du portail SAINet. Par défaut `/usr/src`.
`SAINET_AUTOUPDATE_COOLDOWN`	`integer`	Temps d’attente (en ms) avant de vérifier l’existence d’une mise à jour au (re)démarrage du service. Par défaut, 1h.
`SAINET_RELATIVE_PATH`	`string`	URL relative du portail lorsque ce dernier ne se trouve pas à la racine du site.
`SAINET_LOGOUT_URL`	`string`	URL de logout par un service externe. Utilisé en lien avec `SAINET_SESSION_TYPE=F5`.
`SAINET_SESSION_TYPE`	`string`	Type de session. Peut prendre la valeur `F5` dans le cas d’une authentification gérée par un service spécial.
`SAINET_DOWNLOAD_FOLDER`	`string`	Dossier de téléchargement des mises à jour.
`SAINET_DISPLAY_ENDPOINT`	`boolean`	Affichage de l’endpoint dans les logs lors du démarrage et quitte le processus.
`SAINET_PORT`	`integer`	Le port interne d’écoute du portail. Par défaut 3001.
`SAINET_AUTO_UPDATE`	`0` ou `1`	Permet d’activer ou désactiver la mise à jour automatique. Par défaut `1`.
`SAINET_LOG_LEVEL`	`1` à `6`	Logging pour node. Par défaut à 6 (DEBUG).
`SAINET_SERVER_LOG_LEVEL`	`1` à `6`	Logging pour les appels serveurs. Par défaut à 2 (WARNING).
`SAINET_CONFIG_LOG_LEVEL`	`1` à `6`	Logging pour la gestion de la configuration. Par défaut à 2 (WARNING).
`SAINET_REDIS_HOST`	`string`	Host du service Redis. Si pas spécifié, un cache local sera utilisé.
`SAINET_REDIS_PORT`	`integer`	Port du service Redis. Par défaut 6379.
`SAINET_REDIS_PASSWORD`	`string`	Mot de passe pour le service redis.
`NODE_ENV`	`development`,`production`	Définit le mode d’exécution du portail en terme d’optimisation. Par défaut `production` (nécessite un accès en HTTPS).
`NODE_TLS_REJECT_UNAUTHORIZED`	`0` ou `1`	Permet d’ignorer les erreurs de certificat lors de tests https en serveur local. Par défaut à 0 (<=3.0.2) et 1 (>=3.0.3).

Exemple

Voici un exemple de docker-compose.yml minimal dans le cadre d’un déploiement avec une partie pré-inscription. L’image Docker du portail est déployée sur Docker Hub.

Cette exemple montre une configuration du serveur SAINet avec son compte de service et la mise en place du captcha google pour la pré-inscription.

version: "3.0"

services:
  sainet_portal:
    restart: always
    image: saierp/portal:4.11
    environment:
      - SAINET_APP_NAME=MyPortal
      - SAINET_URL=https://my-sainet-server.ch/SNV4SRV-mobile-war
      - SAINET_USER=portal
      - SAINET_PASS=example
      - SAINET_DOMAIN=POR
      - SAINET_NPM_AUTH_TOKEN=123456789=
      - SAINET_REDIS_HOST=sainet_redis
      - SAINET_SUB_SITE_KEY=123456789abcd
      - SAINET_SUB_SECRET_KEY=987654321dcba
    volumes:
      - "./portal/app:/usr/src/app"
      - "./portal/update:/usr/src/update"
    ports:
      - "3001:3001"
      
  sainet_redis:
    restart: always
    image: redis:7-alpine
    command: redis-server --maxmemory 512m

HTTP/HTTPS et cookies sécurisés

Il est important de pouvoir accéder en https à l’URL de login (car des cookies sécurisés sont utilisées). Si cela n’est pas le cas, alors il est nécessaire de définir NODE_ENV=development afin de pouvoir se connecter. Dans le cas contraire, le header HTTP X-Forwarded-Proto doit être inséré dans la redirection avec la valeur “https” afin que l’utilisateur puisse être authentifié.

En utilisant Traefik pour réceptionner les requêtes https, il n’y a pas de configuration spéciale à effectuer car les headers nécessaires sont déjà inclus dans la requête transférée (x-forwarded-for, x-forwarded-host, x-forwarded-port, x-forwarded-proto, x-forwarded-server et x-real-ip).

Dans le cas d’une configuration Apache2 (dans une configuration VirtualHost), il est nécessaire d’activer le mode headers:

a2enmod headers

Il suffit ensuite d’ajouter la ligne ci-dessous dans le VirtualHost pour que le header soit ajouté lors de la redirection.

RequestHeader set "X-Forwarded-Proto" "https"

Certificat

Il est possible de mettre le portail derrière un service traefik afin de gérer le certificat SSL. La configuration ci-dessous est un exemple (basé sur cette documentation) qui sert un certificat statique.

services:
  sainet_portal:
    ...
    
    labels:
      - "traefik.http.routers.sainet_portal.rule=PathPrefix(`/`)"
      - "traefik.http.routers.sainet_portal.entrypoints=websecure"
      - "traefik.http.services.sainet_portal.loadbalancer.server.port=3001"
      - "traefik.http.routers.sainet_portal.tls=true"

  sainet_traefik:
    restart: always
    image: traefik:v2.9
    depends_on:
      - sainet_portal
    command:
      - --providers.docker
      - --providers.file.directory=/certificates/config
      - --entrypoints.web.address=:80
      - --entrypoints.web.http.redirections.entrypoint.to=websecure
      - --entrypoints.web.http.redirections.entrypoint.scheme=https
      - --entrypoints.websecure.address=:443
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock"
      - "./certificates:/certificates"
    ports:
      - "443:443"

Service Redis

Redis permet de garder certaines données en cache, notamment au niveau des sessions utilisateurs. Par conséquent, il est utile que ces données soient persistentes afin que les utilisateurs ne se retrouvent pas déconnectés si le service de portail venait à redémarrer (typiquement lorsqu’un administrateur applique une mise à jour).

Niveau de logging

En cas de problème, la valeur des variables SAINET_LOG_LEVEL, SAINET_SERVER_LOG_LEVEL et SAINET_CONFIG_LOG_LEVEL peut prendre une valeur de 1 à 6 avec les définitions suivantes:

SEVERE
WARNING
FINE
FINER
FINEST
DEBUG

Windows / service

La procédure pour installer le portail en tant que service sur Windows:

Installer le serveur Apache en changeant le port pour 3001 dans la configuration.
Installer la version correspondante de NodeJS (npm et node doivent être disponibles dans la variable d’environnement PATH).
Installer sevenzip (7z doit être disponible dans la variable d’environnement PATH).
Télécharger l’artifact du portail.
Extraire les fichiers dans un sous-dossier app (par exemple D:/sainet/portal/app).
Copier les fichiers app/windows/env.bat et app/windows/service.bat au même niveau que le répertoire app (ils doivent être dehors du répertoire).
Mettre à jour les variables dans env.bat.
Créer un service en redémarrage automatique avec nssm (voir ici).

Mises à jour automatiques

Lorsque la mise à jour automatique est active (SAINET_AUTO_UPDATE=1), le portail va contrôler chaque nuit si une nouvelle version du portail est disponible à travers SAINet. Au besoin, la nouvelle version est téléchargée et le container se relance pour appliquer la mise à jour.

A noter également que lorsque le container est (re)démarré, le portail va directement vérifier la disponibilité d’une mise à jour et l’installer le cas échéant. Un timestamp local éviter que cela se fasse à chaque (re)démarrage si celui-ci intervient moins d’une heure avant la dernière mise à jour. Cela peut-être forcé en supprimant le fichier <update>/update.time et en redémarrant le container.

Administration

Une page d’administration est également disponible sur https://<url-portal>/admin-login. Il est nécessaire de fournir un utilisateur/mot de passe SAINet ayant le rôle SUPERADMIN afin de s’y connecter.

Commandes utiles

Afin de vérifier que la connexion du portail à SAINet se fait correctement, il est possible d’exécuter la commande suivante:

curl 'https://portal-bes.reg.sai-erp.net/clearcache?auth-login=<portal>&auth-pass=<password>&type=configuration'

Suivi de l’utililsation

Il est possible d’effectuer du suivi de l’utilisation du portail de manière anonyme via Google Analytics. Ce service permet d’obtenir des informations sur les pages du portail qui ont été visitées par les utilisateur.

Pour mettre en place ce suivi, il suffit de générer un nouveau Stream pour le portail dans Google Analystics et de récupérer la clé (Mesurement ID).

Dans le domaine du portail, créer un page Paramètres divers dans UNI91 et renseigner la clé.