Relution Signet Customer Hub

Obsolète : Windows Server 2019

Ce guide décrit l’installation de Relution sur Windows Server 2019. Ces instructions utilisent MariaDB comme magasin de données et nginx comme proxy inverse.

Pour plus de sécurité et de performances, nous recommandons d’installer Relution, MariaDB et nginx sur des machines distinctes. L’installation sur une seule machine ou sur une ou plusieurs machines virtuelles est également possible.

Ce guide couvre l’installation et la configuration d’une instance simple de Relution.

Prérequis

Avant de commencer, s’assurer que :

  • Les machines peuvent se connecter à Internet
  • Des droits d’administration sont disponibles
  • Un certificat SSL valide est disponible pour le nom d’hôte externe

Les certificats auto-signés ne fonctionnent pas, car les appareils mobiles ne leur font pas confiance. Il est possible d’installer manuellement le certificat racine sur un appareil pour qu’il fasse confiance au certificat. Cette approche n’est pas recommandée.

Les certificats de Let’s Encrypt → ont été testés et fonctionnent. Les appareils plus anciens peuvent ne pas faire confiance à ces certificats, car Let’s Encrypt n’a été établi que récemment en tant qu’autorité de certification (AC).

Installation de MariaDB

Aller sur MariaDB → et télécharger une version LTS de MariaDB, au minimum 10.11, en 64 bits pour Windows. Relution ne démarre pas avec des versions plus anciennes.

Il est également possible d’utiliser la dernière version LTS à la place. Il s’agit de la version 10.11.5, et nous recommandons d’utiliser le package Windows Installer.

Veiller à utiliser un mot de passe root sécurisé.

Suivre les instructions à l’écran pour l’installation.

Configuration de MariaDB

Mettre à jour la configuration de MariaDB avec les options requises par Relution :

  • Aller dans %ProgramFiles%\MariaDB 10.11\data
  • Ouvrir my.ini dans un éditeur de texte en tant qu’administrateur (par exemple Notepad)
  • Trouver la section [mysqld]

Ajouter ces paramètres à la section [mysqld] :

collation-server=utf8mb4_general_ci
character-set-server=utf8mb4
max_allowed_packet=1G
innodb_file_per_table=1

La section [mysqld] peut déjà contenir un paramètre character-set-server. Supprimer ce paramètre et le remplacer par le paramètre ci-dessus.

À partir de MariaDB 11.5, la ligne character-set-collations=utf8mb4=utf8mb4_general_ci est également ajoutée à la section [mysqld]. Sans elle, MariaDB utilise la collation utf8mb4_uca1400_ai_ci pour les connexions, bien que la base de données et les tables soient en utf8mb4_general_ci. L’option existe à partir de MariaDB 11.2 ; la version 10.11 utilisée dans ce guide ne la reconnaît pas et ne démarre pas avec cette ligne.

Lors de la mise à jour d’une ancienne version de MariaDB, il se peut que les paramètres innodb_large_prefix et innodb_file_format soient encore présents dans le fichier my.ini. Ces paramètres ne sont plus nécessaires et leur présence peut empêcher le service MariaDB de démarrer correctement.

Redémarrer le service MariaDB en utilisant le gestionnaire de services (services.msc) ou l’invite de commande. Pour des raisons de compatibilité descendante, le service porte le nom de MySQL.

net stop MySQL
net start MySQL

Vérifier l’installation

Il devrait maintenant être possible de se connecter à cette instance de MariaDB, par exemple avec le raccourci MySQL Client (MariaDB 10.11 (x64)) que le programme d’installation devrait avoir créé dans le menu Démarrer. Une fois la connexion établie, un résultat similaire à celui-ci devrait s’afficher :

Enter password: ********
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 11
Server version: 10.11.5-MariaDB mariadb.org binary distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> exit
Bye

Alternativement, le client HeidiSQL, qui est une partie optionnelle de l’installateur, ou MySQL Workbench peuvent être utilisés pour se connecter à l’instance.

Créer une base de données

Ensuite, créer la base de données relution et un utilisateur de base de données associé. Cet utilisateur sera utilisé par le service Relution pour se connecter à la base de données.

Se connecter à la base de données en utilisant un client SQL. L’utilisation d’une application GUI comme HeidiSQL ou MySQL Workbench est recommandée pour cette tâche. Exécuter les instructions SQL suivantes :

CREATE DATABASE relution CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_general_ci';
CREATE USER 'relution'@'localhost' IDENTIFIED BY '$PASSWORD';
GRANT ALL PRIVILEGES ON relution.* TO 'relution'@'localhost' IDENTIFIED BY '$PASSWORD';
CREATE USER 'relution'@'%' IDENTIFIED BY '$PASSWORD';
GRANT ALL PRIVILEGES ON relution.* TO 'relution'@'%' IDENTIFIED BY '$PASSWORD';
FLUSH PRIVILEGES;

Remplacer $PASSWORD par un mot de passe aléatoire et sécurisé. Nous recommandons l’utilisation d’un gestionnaire de mots de passe pour créer un mot de passe aléatoire long (par exemple, 32 caractères ou plus). Ce mot de passe sera utilisé par le service Relution et n’a pas besoin d’être saisi manuellement par un administrateur. Un mot de passe fort peut donc être utilisé.

Cela crée une nouvelle base de données nommée relution et un nouvel utilisateur de base de données nommé relution, qui a tous les droits sur cette base de données. Cet utilisateur sera utilisé par le service Relution pour accéder à la base de données. Si un accès administratif à la base de données est nécessaire à des fins de maintenance, il est recommandé de créer un utilisateur de base de données distinct à cette fin.

Veiller à sauvegarder le mot de passe. Il sera nécessaire plus tard pour configurer la connexion à la base de données de Relution.

S’assurer qu’il est possible de se connecter à la base de données avec cet utilisateur. Ouvrir pour cela le raccourci Command Prompt (MariaDB 10.11 (x64)) dans le menu Démarrer et entrer la commande suivante :

mysql -u relution -p relution

Entrer le mot de passe lorsqu’il est demandé. L’invite MariaDB devrait s’afficher comme celle ci-dessus. Taper exit et appuyer sur Entrée pour terminer la session.

Configuration du pare-feu

Si Relution est installé sur une autre machine, le port 3306 doit être ouvert sur cette machine pour que Relution puisse communiquer avec MariaDB. Si Relution est installé sur la même machine, ces étapes peuvent être ignorées.

  • Ouvrir le Pare-feu Windows Defender avec fonctions avancées de sécurité
  • Sélectionner Règles de trafic entrant
  • Cliquer sur Nouvelle règle… sur le côté droit de la page
  • Sélectionner Programme
  • Cliquer sur Suivant
  • Sélectionner Chemin d’accès du programme
  • Utiliser Parcourir… pour sélectionner le fichier exe du service MariaDB (C:\Program Files\MariaDB 10.11\bin\mysqld.exe)
  • Cliquer sur Suivant
  • Sélectionner Autoriser la connexion
  • Cliquer sur Suivant
  • Activer Domaine et/ou Privé, en fonction de l’infrastructure
  • Cliquer sur Suivant
  • Donner un nom à la règle
  • Cliquer sur Terminer

Installer Java Runtime

Télécharger et installer une version supportée de Java. Si le programme d’installation demande si JAVA_HOME doit être configuré, sélectionner Oui.

Relution nécessite au minimum Java 21 (OpenJDK 21, un JRE suffit). La plupart des fournisseurs considèrent cette version comme une version de support à long terme (LTS). Informations à jour : Changelog technique →

Il existe plusieurs fournisseurs d’OpenJDK, dont Eclipse Temurin, Oracle, RedHat et d’autres. Pour Windows, nous recommandons Eclipse Temurin →.

Configurer l’environnement

Les étapes suivantes ne sont nécessaires que si le programme d’installation n’a pas défini JAVA_HOME. Le programme d’installation d’AdoptOpenJDK peut le faire automatiquement. Si cette option est activée, ces étapes peuvent être ignorées.

  • Cliquer sur Démarrer et chercher Variables d’environnement
  • Ouvrir Modifier les variables d’environnement système
  • Cliquer sur l’onglet Paramètres système avancés
  • Sélectionner Variables d’environnement…
  • Cliquer sur Nouvelle… sous Variables système
  • Entrer JAVA_HOME comme nom de la variable
  • Entrer le répertoire d’installation du JRE/JDK comme valeur de la variable
  • Cliquer sur OK

Vérifier si JAVA_HOME est défini

Si une fenêtre d’invite de commande était ouverte auparavant, elle doit être fermée avant que les modifications ne prennent effet. Ouvrir une nouvelle invite de commande Windows et taper la commande suivante.

echo %JAVA_HOME%

La valeur saisie dans les variables d’environnement ci-dessus devrait apparaître. Si ce n’est pas le cas, vérifier les paramètres.

Installer Relution

Télécharger le paquetage Relution actuel → et l’extraire (clic droit sur le fichier, puis Extraire tout…).

Windows crée par défaut un nouveau répertoire pour les fichiers extraits, ainsi relution est situé dans le répertoire relution-package.

Déplacer le dossier relution de relution-package vers %ProgramFiles%. Pour cela, ouvrir une fenêtre de console en tant qu’administrateur et exécuter la commande suivante :

move "%USERPROFILE%\Downloads\relution-package\relution" "%ProgramFiles%\relution"

Adapter le répertoire source si nécessaire. Le répertoire cible %ProgramFiles%\relution ne doit pas exister auparavant.

Configuration de base de Relution

Ouvrir un éditeur de texte (par exemple Notepad) en tant qu’administrateur et y coller le contenu suivant :

relution:
  system:
    admin:
      password: %SYSTEM_ADMIN_PASSWORD%
      email: %SYSTEM_ADMIN_EMAIL%
  server:
    externalURL: %EXT_HOSTNAME_URL%
  database:
    type: mariadb
    url: jdbc:mariadb://<db-hostname>/relution?useServerPrepStmts=true
    username: relution
    password: %MYSQL_PASSWORD%

Veiller à modifier le fichier pour l’adapter à l’environnement concerné. Les paramètres suivants doivent être remplacés :

PlaceholderDescription
%EXT_HOSTNAME_URL%L’adresse externe du serveur Relution, par exemple https://mdm.example.com
%MYSQL_PASSWORD%Le mot de passe de l’utilisateur de la base de données Relution
%SYSTEM_ADMIN_PASSWORD%Le mot de passe initial de l’administrateur système. Modifier ce mot de passe après la première connexion, puis supprimer cette ligne.
%SYSTEM_ADMIN_EMAIL%L’adresse e-mail de l’administrateur système.

Envisager d’utiliser un générateur de mot de passe pour créer le premier mot de passe du compte administratif. Il est recommandé de changer le mot de passe après la première connexion.

Le nom d’utilisateur de l’administrateur système est admin. Le compte n’est créé au démarrage que tant qu’aucun administrateur n’existe encore dans l’organisation système. S’il en existe déjà un, le mot de passe indiqué dans application.yml reste sans effet.

Enregistrer le fichier en tant que application.yml dans le répertoire d’installation de Relution (par exemple "%ProgramFiles%\relution\application.yml").

Vérifier l’installation

Pour vérifier que l’installation est correcte jusqu’à ce point, démarrer Relution au premier plan. Ouvrir une fenêtre de console en tant qu’administrateur et exécuter les commandes suivantes :

cd "%ProgramFiles%\relution"
windows-bin\relution-foreground.bat

Si JAVA_HOME n’est pas défini, relution-foreground.bat se termine sans message.

Attendre que Relution soit lancé. Dès que la sortie du terminal a cessé de s’actualiser, il devrait être possible de se connecter à Relution à l’aide d’un navigateur :

http://localhost:8080

Si tout fonctionne, le portail Relution s’affiche et la connexion avec le nom d’utilisateur admin et le mot de passe indiqué dans le fichier application.yml est possible. Pour des raisons de sécurité, le mot de passe de l’administrateur devrait être changé après la connexion. Pour des raisons de sécurité, il est également conseillé de supprimer la ligne password sous relution.system.admin du fichier application.yml.

En cas d’erreurs, vérifier que toutes les étapes ci-dessus ont été effectuées. Utiliser Ctrl+C pour arrêter Relution et attendre que Relution s’arrête. Si Relution ne s’arrête pas, utiliser à nouveau Ctrl+C pour forcer le service à s’arrêter.

Si Relution s’arrête avec le message de log MariaDB versions lower than 10.11 are no longer supported by Relution, la version de MariaDB installée est trop ancienne.

Configurer Relution en tant que service

Installer Relution en tant que service Windows à l’aide du script batch install_service.bat. Ouvrir une fenêtre de console en tant qu’administrateur et exécuter les commandes suivantes :

cd "%ProgramFiles%\relution"
windows-bin\install_service.bat auto "%JAVA_HOME%"

Le script définit la variable système RELUTION_HOME sur le répertoire d’installation et écrit le chemin Java transmis comme deuxième paramètre dans la variable système JAVA_HOME. Il configure ensuite le service Relution à l’aide du fichier nssm.exe fourni.

Le service devrait démarrer automatiquement après l’installation. Sinon, le gestionnaire de services ou la commande net start relution dans l’invite de commande permettent de démarrer le service.

Le répertoire windows-bin contient également start_service.bat, stop_service.bat et uninstall_service.bat. uninstall_service.bat supprime le service et réinitialise RELUTION_HOME.

La taille maximale du tas Java peut être définie avec la variable système RELUTION_MEMORY (par exemple 4G, transmise en tant que -Xmx). Sans cette variable, la valeur par défaut de l’environnement d’exécution Java s’applique. Les services Windows ne prennent généralement en compte les variables système nouvelles ou modifiées qu’après un redémarrage du serveur.

Configurer le pare-feu

Si nginx est installé sur une autre machine, le port 8080 doit être ouvert pour permettre à nginx de communiquer avec Relution. Si nginx est installé sur la même machine, ces étapes peuvent être ignorées.

Le port n’est pas ouvert par nssm.exe, mais par le processus java.exe lancé par relution-foreground.bat. C’est pourquoi une règle de port est créée :

  • Ouvrir le Pare-feu Windows Defender avec fonctions avancées de sécurité
  • Cliquer sur Règles de trafic entrant
  • Sélectionner Nouvelle règle… dans le menu d’action
  • Sélectionner Port
  • Cliquer sur Suivant
  • Sélectionner TCP et Ports locaux spécifiques, saisir 8080
  • Cliquer sur Suivant
  • Sélectionner Autoriser la connexion
  • Cliquer sur Suivant
  • Sélectionner Domaine et/ou Privé, en fonction de l’infrastructure
  • Cliquer sur Suivant
  • Donner un nom à la règle
  • Cliquer sur Terminer

Une règle de programme pour %JAVA_HOME%\bin\java.exe est également possible, c’est-à-dire pour l’installation Java transmise comme JAVA_HOME à install_service.bat. Une telle règle doit être adaptée après une mise à jour de Java ou un changement de chemin Java.

Installation de Nginx

Préparation

Un certificat SSL valide et une clé de certificat doivent être obtenus auprès du fournisseur SSL (autorité de certification, CA). Pour utiliser l’agrafage OCSP, un fichier de chaîne de certificats est également nécessaire.

Convertir un certificat en PEM →

Copier ces fichiers sur le serveur où nginx sera installé. Déplacer ces fichiers dans les répertoires appropriés et les sauvegarder si nécessaire.

La clé privée ne doit être lisible que par l’administrateur. Veiller à conserver ce fichier en lieu sûr. Toute personne ayant accès à cette clé peut signer des données au nom du titulaire du certificat et déchiffrer des informations privées qui lui sont destinées.

Pour Let’s Encrypt, ACME Client Implementations répertorie les clients disponibles pour Windows. Le Certbot officiel n’est disponible que pour les systèmes d’exploitation de type UNIX.

ACME Client Implementations →
Certbot →

Installer nginx

Télécharger la dernière version stable de nginx for Windows → dans le répertoire de téléchargement.

Faire un clic droit sur le fichier nginx-x.xx.zip et cliquer sur Extraire tout….

Déplacer le répertoire extrait nginx-x.xx vers %ProgramFiles% et le renommer en nginx.

move "%USERPROFILE%\Downloads\nginx-1.14.0\nginx-1.14.0" "%ProgramFiles%\nginx"

Personnaliser le répertoire source si nécessaire.

Par défaut, Windows crée un nouveau répertoire pour les fichiers extraits, de sorte que le répertoire nginx-x.xx proprement dit peut se trouver dans un autre répertoire nginx-x.xx. Veiller à déplacer le répertoire qui contient le fichier nginx.exe.

Configurer nginx pour Relution

Copier le certificat SSL et la clé privée dans %ProgramFiles%\nginx\server.pem et %ProgramFiles%\nginx\server.key.

Ouvrir le fichier %ProgramFiles%\nginx\conf\nginx.conf dans un éditeur de texte en tant qu’administrateur et remplacer son contenu par l’exemple de configuration suivant :

worker_processes  1;
daemon off;
error_log  logs/error.log;
pid        logs/nginx.pid;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    # increase request size for app upload
    client_max_body_size 512M;
    large_client_header_buffers 8 32k;
    sendfile        on;
    keepalive_timeout  65;

    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    proxy_http_version 1.1;
    proxy_read_timeout 300;
    proxy_set_header Host $host:$server_port;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;

    proxy_busy_buffers_size   512k;
    proxy_buffers   4 512k;
    proxy_buffer_size   256k;

    proxy_cache_path cache levels=1:2 keys_zone=cache:16m max_size=16g inactive=60m use_temp_path=off;

    server {
        listen 80 default_server;
        server_tokens off;
        # Redirect to HTTPS
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_tokens off;

        # Use slashes instead of backslashes in paths
        ssl_certificate      "C:/Program Files/nginx/server.pem";
        ssl_certificate_key  "C:/Program Files/nginx/server.key";

        location ~ /api/v1/system/files/.*/content {
            proxy_cache cache;
            proxy_cache_key $host$uri;            # must NOT include query params!
            proxy_cache_revalidate on;
            proxy_cache_lock on;
            proxy_cache_lock_age 60s;
            proxy_cache_lock_timeout 60s;

            proxy_pass http://127.0.0.1:8080;
        }

        location ~ /api/management/v1/system/files/.*/content {
            proxy_cache cache;
            proxy_cache_key $host$uri;            # must NOT include query params!
            proxy_cache_revalidate on;
            proxy_cache_lock on;
            proxy_cache_lock_age 60s;
            proxy_cache_lock_timeout 60s;

            proxy_pass http://127.0.0.1:8080;
        }

        location ~ /Microsoft-Server-ActiveSync {
            proxy_read_timeout 2100;
            proxy_pass http://127.0.0.1:8080;
        }

        location / {
            proxy_pass http://127.0.0.1:8080;
        }
    }
}

Adapter la configuration à l’environnement si nécessaire. Si Relution a été installé sur un autre serveur, l’adresse IP doit être adaptée dans toutes les lignes proxy_pass http://127.0.0.1:8080;.

Vérifier la configuration nginx avec la commande suivante :

"%ProgramFiles%\nginx\nginx.exe" -t

Les messages syntax is ok et test is successful devraient s’afficher. En cas d’erreurs, vérifier que la configuration nginx ne contient pas de fautes de frappe, etc., comme indiqué dans le message d’erreur.

Installer nginx en tant que service Windows

nginx est configuré en tant que service Windows à l’aide du fichier nssm.exe inclus dans le paquetage Relution. Ouvrir pour cela une fenêtre de console en tant qu’administrateur et exécuter les commandes suivantes :

"%ProgramFiles%\relution\windows-bin\nssm.exe" install nginx "%ProgramFiles%\nginx\nginx.exe"
sc start nginx

Le script windows-bin\install_service.bat ne convient pas à cet usage, car il installe uniquement le service Relution.

Pare-feu

Ouvrir les ports 80 et 443 dans le pare-feu pour permettre l’accès via HTTP et HTTPS.

  • Ouvrir le Pare-feu Windows Defender avec fonctions avancées de sécurité
  • Naviguer jusqu’à Règles de trafic entrant
  • Dans la section Actions, cliquer sur Nouvelle règle…
  • Sélectionner Programme
  • Cliquer sur Suivant
  • Sélectionner Chemin d’accès du programme
  • Utiliser Parcourir… pour sélectionner le fichier exécutable de nginx (C:\Program Files\nginx\nginx.exe)
  • Cliquer sur Suivant
  • Sélectionner Autoriser la connexion
  • Cliquer sur Suivant
  • Sélectionner Public
  • Cliquer sur Suivant
  • Entrer un nom pour la règle et cliquer sur Terminer