Installation de Dokos sur plateformes RHEL (CentOS, AlmaLinux, RockyLinux) 8 et 9

Ce guide explique comment installer Dokos v2 ou v3 sur les plateformes Redhat (RHEL, AlmaLinux, CentOS, RockyLinux) EL8 ou EL9.

Bien qu'en dehors du scope du présent document, il convient de préparer le système hôte pour l'ERP Dokos comme suit:

• Le chemin /var contiendra les fichiers de l'ERP, une partition dédiée est souhaitable
• Configurer les éventuels guest tools s'il s'agit d'une machine virtuelle (VMWare, Qemu, HyperV...)
• Configurer un serveur NTP de préférence intra-réseau
• Configurer la sécurité, les accès, ainsi que la traçabilité (voir guide sécurité dédié ainsi que guide OpenSCAP)
• Configurer le tuning machine (voir guide dédié tuned-adm avec profil dédié NPF-APP et valeurs thread siblings)
• Installer les outils de diagnostics habituels (net-tools bind-utils nano sysstat iotop htop iftop atop nmon telnet lsof traceroute) disponibles essentiellement sur le depot EPEL
• Configurer la supervision (Prometheus ou SNMPd)

Installation des prérequis

Prérequis standards

Installer les paquets permettant la compilation des modules yarn

dnf install -y git tar bzip2 openssl-devel libffi-devel gcc

Pour la mise en production, il faudra en outre installer l'outil d'automatisation ansible:

# Pour RHEL 8 et clones
dnf -y install ansible
# Pour RHEL 9 et clones
dnf -y install ansible-core

Configuration spécifique du système

Modèle Inotify (mode développement uniquement)

Lors de l'exécution de Dokos en mode développement, le kernel hook inotify est utilisé par le framework JS pour surveiller les changements de fichiers. Par défaut, la limite de fichiers que RHEL 8 surveille est fixé à 8192 pour des raisons de performances, et les logs du framework peuvent contenir des erreurs de type

UnhandledPromiseRejectionWarning: Error: ENOSPC: System limit for number of file watchers reached, watch '/var/dokos/dokos-erp/apps/frappe/frappe/public/scss/common/quill.scss' 23:53:21 watch.1 | at FSWatcher.<computed> (internal/fs/watchers.js:243:19)

Pour un environnement de développement, il est possible de lever cette limite comme suit:

echo "fs.inotify.max_user_watches=$((1024*512))" | sudo tee -a /etc/sysctl.d/90-dokos.conf

Chaque fichier surveillé consomme 1Ko de mémoire, dans notre exemple, pour surveiller 512Ko fichiers, il faudra 512Mo de mémoire vive.

Dans un environnement de production, il faut penser à vider les caches de fichiers précédents de nodejs afin de réduire cette quantité de fichiers à surveiller.

Mémoire VM

Afin d'éviter que les enregistrements en tâche de fond échouent si la mémoire vive est faible:

echo "vm.overcommit_memory=1" | sudo tee -a /etc/sysctl.d/90-dokos.conf

TCP Backlog

Pour optimiser les performances de redis, il faudra modifier le paramètre suivant:

echo "net.core.somaxconn=65535" | sudo tee -a /etc/sysctl.d/90-dokos.conf

Chargement paramètres

Il faudra recharger les paramètres à la volée pour une application sans attendre le redémarrage.

sysctl --load /etc/sysctl.d/90-dokos.conf

Désactivation des Transparent Huge Pages (THP) via le mode opt-in par processus en utilisant la directive « madvise »

Il faudra changer les arguments kernel dans /etc/default/grub comme suit en ajoutant « transparent_hugepage=madvise ». Exemple:

GRUB_CMDLINE_LINUX="crashkernel=auto resume=UUID=598eec09-15a8-4cc9-b1ed-17d2b41b5594 transparent_hugepage=madvise"

Une fois enregistré, il faudra recréer une configuration de boot

find /boot -iname "grub.cfg" | xargs grub2-mkconfig -o

Préparation du service de base de données MySQL

Installation et préparation de la base de données MariaDB

S'assurer que la version de MariaDB soit >= 10.3.x via la commande suivante:

dnf list mariadb-server

Lancer l'installation via la commandes suivantes:

# Pour RHEL 8 et clones
dnf -y install mariadb-server mariadb-devel
# Pour RHEL 9 et clones
dnf -y install mariadb-server

Configuration du serveur et du client

Ajouter les directives suivantes dans la section [mysql] du fichier /etc/my.cnf.d/mariadb-server.cnf

# NETPERFECT-BZ012: Optimisation des performances mono serveur
table_cache             = 1000
# NETPERFECT-BZ131: Permet l'import de fichiers SQL disposant de INSERT statements trop longs (ERROR 2006 (HY000) at line 696: MySQL server has gone away)
max_allowed_packet      = 128M
# NETPERFECT-BZ065: Augmenter la taille du fichier log INNODB pour permetttre de jouer de plus grandes requêtes (info: MySQL server has gone away.). Additional info: https://jira.kopano.io/browse/KC-1053
innodb_log_file_size    = 128M
# NETPERFECT-BZ213: Augmenter la durée maximale d'absence de requête pour éviter l'erreur (MySQL server has gone away)
wait_timeout            = 288000
# NETPERFECT-BZ003: Chaque table INNODB doit posséder son propre fichier afin de faciliter la récuperation de données en cas de crash
innodb-file-per-table   = 1

# NETPERFECT-BZ401: Do not set client handshake (dokos)
character-set-client-handshake = FALSE
# NETPERFECT-BZ232: Set default collation for most applications
character-set-server           = utf8mb4
# NETPERFECT-BZ232: Set default collation for most applications
collation-server               = utf8mb4_unicode_ci

Ajouter les directives suivantes dans la section [mysql] du fichier etc/my.cnf.d/mysql-clients.cnf

NETPERFECT-BZ232: Set default collation for most applications
default-character-set = utf8mb4

Une fois configuré, vous pourrez lancer le service MariaDB avec la commande suivante

systemctl enable --now mariadb

la configuration de sécurité se fera en lançant la commande

mariadb-secure-installation

La configuration est légèrement différente entre RHEL 8 et RHEL 9. Depuis RHEL 9, les connexions en tant qu'utilisateur root sont possibles sans mot de passe en utilisant un socket unix.

Sous RHEL 8, il faudra ajouter un fichier de mot de passe afin d'arriver à un résultat identique.

Créer le fichier /root/.my.cnf suivant

[client]
password="VotreMotDePasseSuperSécuriséMySQL"

Préparation de la base de données redis

Depuis le Framework Frappe v13 (dokos v2.x), le prérequis minimal est redis 6.x.

RHEL 8 est fourni avec redis 5.x par défaut et RHEL 9 est fourni avec redis 6.x par défaut.

# Pour RHEL 8 et clones
dnf module enable redis:6
dnf install redis -y
# Pour RHEL 9 et clones
dnf install redis -y

Préparation de l'environnement nodeJS

Depuis le Framework Frappe v13 (dokos v2.x), le prérequis minimal est nodejs 14.x.

Depuis le Framework Frappe v14 (dokos v3.x), le prérequis minimal est nodejs 16.x

RHEL 8 est fourni avec nodejs 14.x par défaut et RHEL 9 est fourni avec nodejs 16.x par défaut.

# Pour RHEL 8 et clones
dnf module enable nodejs:14
dnf install nodejs -y
# Pour RHEL 9 et clones
dnf install nodejs -y

Installation du manager de packages JS yarn

Solution d'installation en tant que paquet RPM

Cette solution à l'avantage de mettre à jour automatiquement yarn avec le système.

Depuis le framework Frappe v13, le prérequis minimal est yarn 1.12.

Installation du dépôt yarn

curl --silent --location https://dl.yarnpkg.com/rpm/yarn.repo | tee /etc/yum.repos.d/yarn.repo
rpm --import https://dl.yarnpkg.com/rpm/pubkey.gpg

Installation de yarn

dnf install -y yarn

Solujtion d'installation via npm

Alternativement, il est possible d'installer yarn via le gestionnaire de packages nodejs:

npm install -g yarn

Préparation de l'environnement Python

Depuis le Framework Frappe v13 (dokos v2.x), le prérequis minimal est python 3.8.x

Depuis le Framework Frappe v14 (dokos v3.x), le prérequis minimal est python 3.10.x

Configuration de python pour dokos v2.x

RHEL 8 est fourni avec python 3.8. RHEL 9 est fourni avec python 3.9.

Pour dokos v2.x, il sera donc possible d'utiliser l'interpréteur système

dnf install -y python-pip
python3 -m pip install --upgrade pip
python3 -m pip install --upgrade setuptools wheel virtualenv

Configuration de python pour dokos v3.x

Dokos v3.x utilise python 3.10+. Au 12/12/2022, aucune dépot officiel de python 3.10 n'existe pour RHEL. Il faudra donc compiler manuellement Python et l'installer dans un chemin alternatif /usr/local/bin/python3 pour ne pas interférer avec l'interpréteur python fourni par le système.

# Dépendances de compilation python
dnf install -y wget yum-utils make gcc openssl-devel bzip2-devel libffi-devel zlib-devel
# Dépendances de compilation de modules python nécessaires pour le framework Frappe
dnf install -y libpq-devel gcc-c++ libjpeg-turbo-devel libjpeg-turbo-utils
mkdir /opt/python310 && cd /opt/python310
# Attention: Vérifier sur python.org s'il existe une archive plus récente
curl -OL https://www.python.org/ftp/python/3.10.9/Python-3.10.9.tgz
tar xvf Python-3.10.9.tgz
cd Python-3.10.9
./configure --with-system-ffi --with-computed-gotos --enable-loadable-sqlite-extensions
make -j ${nproc}
make altinstall
alias python3=/usr/local/bin/python3

Installation de wkhtmltopdf

Il faut se rendre sur la page « https://github.com/wkhtmltopdf/packaging/releases pour télécharger la dernière version.

# Pour RHEL 8 et clones
cd /opt
curl -OL https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox-0.12.6.1-2.almalinux8.x86_64.rpm
dnf localinstall wkhtmltox-0.12.6.1-2.almalinux8.x86_64.rpm
dnf install nodejs -y
# Pour RHEL 9 et clones
cd /opt
curl -OL https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox-0.12.6.1-2.almalinux9.x86_64.rpm
dnf localinstall wkhtmltox-0.12.6.1-2.almalinux9.x86_64.rpm

La version de wkhtmlpdf doit avoir été compilée avec le support de la librairie qt.

Il est possible de vérifier que le patch QT soit appliqué avec la commande suivante

wkhtmltopdf -v 2>&1 | grep qt

wkhtmltopdf 0.12.6 (with patched qt)

Afin que les documents PDF générés par Dokos soient conformes à leur version HTML, il conviendra également d'installer les polices Truetype Microsoft avec la commande suivante:

dnf localinstall https://www.itzgeek.com/msttcore-fonts-2.0-3.noarch.rpm

Installation de l'ERP Dokos

L'ERP Dokos est un fork de erpnext, lui même basé sur le framework Frappe. Le framework Frappe s'administre avec l'outil bench (aussi nommé docli chez Dokos).

Création de l'utilisateur dédié

Afin d'améliorer la sécurité, dokos devrait être installé en tant qu'utilisateur non root.

Création d'un utilisateur dédié dont le dossier utilisateur sera stocké dans /var/dokos

user-add --home-dir /var/dokos -G wheel dokos
# Création d'un mot de passe pour l'utilisateur dokos
passwd dokos
su - dokos

Installation du Framework docli (Frappe Bench)

Afin que l'installation se déroule avec succès, il est conseillé de régler temporairement les variables linguistiques sur le standard C, afin que les scripts d'installations automatisés reçoivent des sorties standards des commandes telles que date sans se soucier de la langue.

# En tant qu'utilisateur dokos
export LC_ALL=C.UTF-8
cd /var/dokos && sudo python3 -m pip install dokos-cli

Cette opération installera une copie locale de docli qui est un alias de bench

Création d'une nouvelle instance Dodock (Frappe framework)

# En tant qu'utilisateur dokos
cd /var/dokos && docli init --frappe-branch master dokos-erp

Le résultat devrait ressembler à ceci:

$ /usr/local/bin/virtualenv --quiet env -p python3
$ /var/dokos/dokos-erp/env/bin/python -m pip install --quiet --upgrade pip
Getting dodock
$ git clone https://gitlab.com/dokos/dodock.git --branch master --depth 1 --origin upstream
Clonage dans 'dodock'...
remote: Enumerating objects: 4828, done.
remote: Counting objects: 100% (4828/4828), done.
remote: Compressing objects: 100% (4556/4556), done.
remote: Total 4828 (delta 447), reused 2995 (delta 197), pack-reused 0
Réception d'objets: 100% (4828/4828), 21.74 Mio | 13.96 Mio/s, fait.
Résolution des deltas: 100% (447/447), fait.
Installing frappe
$ /var/dokos/dokos-erp/env/bin/python -m pip install --quiet --upgrade -e /var/dokos/dokos-erp/apps/frappe
$ yarn install
yarn install v1.22.18
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
warning " > @fullcalendar/vue@5.10.1" has incorrect peer dependency "vue@^2.6.12".
warning " > bootstrap@4.5.0" has unmet peer dependency "jquery@1.9.1 - 3".
warning " > bootstrap@4.5.0" has unmet peer dependency "popper.js@^1.16.0".
[4/4] Building fresh packages...
Done in 15.04s.
$ bench build
yarn run v1.22.18
$ FRAPPE_ENV=production node rollup/build.js
clean: postcss.plugin was deprecated. Migration guide:
https://evilmartians.com/chronicles/postcss-8-plugin-migration
Production mode
✔ Built js/moment-bundle.min.js
✔ Built js/libs.min.js

Building frappe assets...

✔ Built js/checkout.min.js
✔ Built js/dialog.min.js
✔ Built js/user_profile_controller.min.js
✔ Built js/frappe-vue.min.js
✔ Built js/bootstrap-4-web.min.js
✔ Built js/barcode_scanner.min.js
Browserslist: caniuse-lite is outdated. Please run:
npx browserslist@latest --update-db
Browserslist: caniuse-lite is outdated. Please run next command `yarn upgrade caniuse-lite browserslist`
✔ Built css/frappe-rtl.css
✔ Built js/frappe-recorder.min.js
✔ Built css/report.min.css
✔ Built js/web_form.min.js
✔ Built css/web_form.css
✔ Built css/frappe-chat-web.css
✔ Built js/report.min.js
✔ Built js/data_import_tools.min.js
✔ Built js/chat.js
✔ Built js/frappe-web.min.js
✔ Built js/desk.min.js
✔ Built js/events-portal.min.js
✔ Built js/list.min.js
✔ Built css/printview.css
✔ Built js/control.min.js
✔ Built css/website-calendar.min.css
✔ Built css/email.css
✔ Built css/login.css
✔ Built css/frappe-web-b4.css
✔ Built js/form.min.js
✔ Built css/desk.min.css
✨ Done in 111.635s
Done in 113.26s.
SUCCESS: Bench dokos-erp initialized

Installation des dépendances python du framework Frappe

Au lieu d'une installation en tant que site-packages, les dépendances du framework Frappe seront installés directement dans l'environnement virtuel python crée pour le framework.

# En tant qu'utilisateur dokos
python3 -m venv /var/dokos/dokos-erp/env
/var/dokos/dokos-erp/env/bin/python -m pip install --upgrade -e /var/dokos/dokos-erp/apps/frappe

Installation de l'application ERP dokos

UNe fois le framework configuré, il sera alors possible d'installer dokos comme suit

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && docli get-app --branch master https://gitlab.com/dokos/dokos

La sortie devrait ressembler à ceci:

Getting dokos
$ git clone https://gitlab.com/dokos/dokos --branch master --depth 1 --origin upstream
Cloning into 'dokos'...
warning: redirecting to https://gitlab.com/dokos/dokos.git/
remote: Enumerating objects: 5773, done.
remote: Counting objects: 100% (5773/5773), done.
remote: Compressing objects: 100% (4740/4740), done.
remote: Total 5773 (delta 1454), reused 3419 (delta 796), pack-reused 0
Receiving objects: 100% (5773/5773), 17.10 MiB | 17.00 MiB/s, done.
Resolving deltas: 100% (1454/1454), done.
Installing erpnext
$ /var/dokos/dokos-erp/env/bin/python -m pip install --quiet --upgrade -e /var/dokos/dokos-erp/apps/erpnext
$ yarn install
yarn install v1.22.18
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
Done in 1.53s.
$ bench build --app erpnext
yarn run v1.22.18
$ FRAPPE_ENV=production node rollup/build.js --app erpnext
clean: postcss.plugin was deprecated. Migration guide:
https://evilmartians.com/chronicles/postcss-8-plugin-migration
Production mode
✔ Built js/moment-bundle.min.js
✔ Built js/libs.min.js

Building erpnext assets...

✔ Built js/erpnext-web.min.js
✔ Built js/item-dashboard.min.js
✔ Built js/erpnext.min.js
✔ Built js/portal-payments.min.js
✔ Built js/point-of-sale.min.js
Browserslist: caniuse-lite is outdated. Please run:
npx browserslist@latest --update-db
Browserslist: caniuse-lite is outdated. Please run next command `yarn upgrade caniuse-lite browserslist`
✔ Built css/erpnext-web.css
✔ Built css/erpnext.css
✔ Built js/bank-reconciliation.min.js
✔ Built js/bank-transaction-importer.min.js
✔ Built js/portal-calendars.min.js
✔ Built js/resource-calendar.min.js
✨ Done in 38.242s
Done in 39.81s.

Note: L'erreur suivante peut apparaître

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts. frappe 2.13.0 requires PyJWT~=1.7.1, but you have pyjwt 2.3.0 which is incompatible.

Création d'un site

Par défaut, l'application dokos installée sur le framework n'est pas accessible publiquement.

Il convient de créer un site (nom de domaine) sur lequel le framework servira les applications qu'il héberge.

Le nom du site devra respecter la nomenclature DNS et pourra être un FQDN arbitraire (exemple: erp.masociete.local) ou un FQDN attaché à un nom de domaine existant (exemple: erp.monsite-societe.fr)

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && docli new-site <FQDN DE VORTE SITE>
docli --site <FQDN DE VOTRE SITE> set-config hostname http://<FQDN DE VOTRE SITE]

Dans le cas d'un FQDN arbitraire qui n'est pas résolu par un serveur DNS, il faudra ajouter les entrées suivantes au fichier /etc/hosts permettant au serveur local de résoudre le nom du site

127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4 <FQDN DE VOTRE SITE>
::1         localhost localhost.localdomain localhost6 localhost6.localdomain6 <FQDN DE VOTRE SITE>

La sortie de la commande de création de site devrait ressembler à ceci:

MySQL root password:

Installing frappe...
Updating DocTypes for frappe : [========================================] 100%
Updating country info : [========================================] 100%
Set Administrator password:
Re-enter Administrator password:
*** Scheduler is disabled ***
Current Site set to <FQDN DE VOTRE SITE>

Installation de l'application dokos sur le site crée

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && docli --site <FQDN DE VOTRE SITE> install-app dokos

La sortie devrait ressembler à ceci:

Installing erpnext...
Updating DocTypes for erpnext : [========================================] 100%
Updating customizations for Address
Updating customizations for Contact
Updating customizations for Payment Gateway

Fin d'installation

L'installation de l'ERP dokos est terminée et vous pouvez mettre fin à la session de l'utilisateur dokos.

# Redevenir utilisateur root
exit

A partir d'ici, vous pouvez tester dokos en mode développement ou alors configurer le serveur en mode production.

Optionnel: Démarrage du framework et l'ensemble des sites en mode développement

# En tant qu'utilisateur root
sudo -u dokos "cd /var/dokos/dokos-erp && docli start"

Remarque: Si les logs sont remplis d'erreurs de type ENOSPC, il faudra vérifier la configuration du nombre de noeuds inotify (voir ci-dessus) et vérifier l'espace disque disponible.

Dokos sera servi sur le port 8000. Il faudra donc configurer le parefeu.

# En tant qu'utilisateur root
firewall-cmd --add-port=8000/tcp

Cette commande ouvrira le port 8000 jusqu'au redémarrage du serveur. Si aucune mise en production aura lieu sur ce serveur, il sera possible de configurer de rendre cette configuration permanente

# En tant qu'utilisateur root
firewall-cmd --runtime-to-permanent

L'environnement dokos sera disponible à l'adresse http://[IP-DU-SERVEUR]:8000

Mise en production

Configuration de l'environnement de production

Ajout des dépendances nécessaires à la mise en production

Le dépot EPEL est repuis pour fail2ban et supervisor.

# En tant qu'utilisateur root
dnf install -y epel-release
dnf install -y fail2ban nginx supervisor

Droits d'accès

# En tant qu'utilisateur root
chmod 750 /var/dokos
usermod -aG dokos nginx

Configuration SELinux

Le système de production crée un lien symbolique du fchier nginx de configuration local vers le dossier de configuration nginx.

Il est nécessaire de changer le contexte de sécurité SELinux pour autoriser le chargement de ce fichier par nginx hors du dossier /etc/nginx.

# En tant qu'utilisateur root
semanage fcontext -a -t httpd_config_t /var/dokos/dokos-erp/config/nginx.conf
restorecon -Rv /var/dokos/dokos-erp/config/nginx.conf

Il faudra également autoriser nginx à se connecter à internet:

# En tant qu'utilisateur root
setsebool -P httpd_can_network_connect 1

Enfin, il faudra rendre le dossier sites lisible pour nginx:

# En tant qu'utilisateur root
site=[NOM SITE DOKOS]
http_ro_content=(/var/dokos/dokos-erp/sites/assets /var/dokos/dokos-erp/apps/frappe/frappe/public /var/dokos/dokos-erp/apps/erpnext/erpnext/public /var/dokos/dokos-erp/apps/erpnext/node_modules /var/dokos/dokos-erp/apps/frappe/node_modules /var/dokos/dokos-erp/sites/$site/public)
http_rw_content=(/var/dokos/dokos-erp/sites/$site/public/files /var/dokos/dokos-erp/sites/$site/private/files)
for path in ${http_ro_content[@]}; do semanage fcontext -a -t httpd_sys_content_t "${path}(/.*)?"; restorecon -Rv "${path}"; done
for path in ${http_rw_content[@]}; do semanage fcontext -a -t httpd_sys_rw_content_t "${path}(/.*)?"; restorecon -Rv "{$path}"; done

Setup automatisé production Dokos

Choix de la gestion des services

Afin de vérifier la bonne exécution de l'ensemble des services, il faudra choisir entre utiliser des services systemd ou utiliser supervisord. Dans ce guide, nous utiliserons supervisord.

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && docli setup supervisor

Setup de production

Note: les patchs https://gitlab.com/dokos/docli/-/merge_requests/2 https://gitlab.com/dokos/docli/-/merge_requests/3 et https://gitlab.com/dokos/docli/-/merge_requests/4 doivent être intégrés.

L'action suivante configurera supervisord et nginx:

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && sudo env "PATH=$PATH" docli setup production dokos

Vérification

Afin de vérifier que l'ensemble des processus nécessaires au fonctionnement de dokos sont actifs, il faudra exécuter les commandes suivantes:

supervisorctl status
systemctl status nginx

Setup services supplémentaires

Firewall

Pour un serveur de production, il faudra ouvrir les ports HTTP et HTTPS de manière permanente:

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && sudo env "PATH=$PATH" docli setup firewall

Fail2ban

Fail2ban permettra de bannir une IP tentant une authentification par brute force

# En tant qu'utilisateur dokos
cd /var/dokos/dokos-erp && sudo env "PATH=$PATH" docli setup fail2ban