Comment mettre à jour Tiki Wiki vers la version 27 (new Build System)

Alors que Tiki 27 et son processus d’installation se stabilisent, ce guide est un travail en cours et sera utilisé pour mettre à jour la documentation officielle de Tiki.

Nouveau système de compilation (Build) de Tiki Wiki

Le système de compilation Tiki 27+ s’appuie sur des outils et des pratiques de développement modernes, alignant Tiki sur les standards actuels du web. Cela inclut l’intégration d’outils comme Composer pour les dépendances PHP et Node.js pour les dépendances JavaScript et CSS. Il modernise le flux de travail et facilite la mise en place de plusieurs composants requis par Tiki Wiki. Il garantit aussi la cohérence entre les environnements (développement, préproduction, production). Le processus d’installation automatisé réduit les risques de problèmes spécifiques à un environnement, pour des déploiements plus fiables.

Au moment de la rédaction, le système de compilation Tiki Wiki 27+ configure principalement :

• Composer
• Node.js et npm
• ...

Installation globale et prérequis pour exécuter le Build System Tiki 27+

Assurez-vous d’avoir installé les prérequis nécessaires (PHP, Composer, Node.js et npm). Suivez la documentation Tiki pour installer et configurer ces outils. Vous pouvez télécharger Node.js et npm depuis le site officiel Node.js website.

Cloner et actualiser votre code

Clonez le dépôt Tiki depuis le dépôt GitLab Tiki vers votre environnement de développement local. Vous disposerez ainsi de la dernière version du code.
Pour plus de détails sur l’installation, consultez notre tutoriel d’installation de Tiki Wiki. Parcourez nos tutoriels et articles destinés à nos services d'assistance sur Tiki Wiki et vérifiez si un article plus récent a été publié.

Exécuter setup.sh

Il est fortement recommandé d’exécuter ce script avec le même utilisateur que celui de votre répertoire web Tiki Wiki (par ex. www-data). N’utilisez « root » qu’en dernier recours en cas de problème.
Tiki Wiki fournit un script pour automatiser la configuration et appliquer les permissions correctes.

Lancez la commande suivante dans le répertoire de votre projet :

sh setup.sh

Si plusieurs versions de PHP sont installées, il est crucial de sélectionner la bonne version (voir les prérequis
Tiki Wiki) pour exécuter setup.sh.
Voici un exemple sur Debian 12 avec une configuration LAMP Virtualmin :

sh setup.sh -p /usr/bin/php8.2

Utilisez l’option "b" (build), puis "f" pour définir les permissions.
L’option "b" installera les paquets Composer et les dépendances PHP, et npm installera les dépendances JavaScript et CSS.
Vous verrez peut-être quelques avertissements (le système est encore en évolution), mais seules les erreurs requièrent votre attention.

Si tout se passe bien, utilisez l’option "f" pour appliquer les permissions et la propriété sur vos fichiers et répertoires Tiki.

Compiler votre thème et les fichiers publics générés

Avec le Build System Tiki 27+, la compilation des fichiers SCSS et CSS de votre thème diffère des versions précédentes. Tiki 27+ utilise un schéma de répertoires et de fichiers différent, et s’appuie sur des fichiers publics générés pour garantir l’apparence et le bon fonctionnement de votre instance Tiki. Cela implique le traitement de vos feuilles de style, scripts et autres ressources pour les préparer à la production.

Il y a des changements et un nouvel emplacement pour le fichier principal des thèmes personnalisés. Consultez la documentation des thèmes Tiki, mise à jour régulièrement, pour plus d’informations.

La dernière étape d’exécution de setup.sh lancera npm pour finaliser l’installation. Vous devrez exécuter npm run watch chaque fois que vous modifiez votre thème CSS, vos modèles (templates), fichiers personnalisés ou fichiers de langue, afin de garder vos fichiers publics à jour.

Dépannage

Reconstruction propre (from scratch)

En cas de problème — surtout si les journaux ne sont pas concluants — il est judicieux de réinstaller les paquets et dépendances à partir de zéro.

Supprimez manuellement les répertoires et caches, puis relancez l’installation :

rm -rf vendor_bundled/vendor
rm -rf node_modules
rm -f temp/cache/container.php
sh setup.sh -n build

# (Optionnel) supprimez aussi vendor_bundled/composer.lock pour forcer Composer à résoudre les paquets depuis zéro.

Note : La commande sh setup.sh -n build ne supprime pas d’elle-même les dépendances existantes ; les suppressions manuelles ci-dessus garantissent une reconstruction vraiment propre.

Votre CSS de thème ne se compile pas correctement

Le nouveau Build System Tiki étant encore en développement, il peut arriver que votre feuille de style de thème personnalisée ne se mette pas à jour correctement après npm run watch, que le site paraisse « cassé » ou que les changements de thème/modèles ne s’appliquent pas.

Étapes pour résoudre le problème

• Commencez par une reconstruction propre (voir la section ci-dessus).
• Confirmez que vos modifications figurent dans le fichier SCSS personnalisé :
  Path: _custom/shared/themes/yourtheme/css/yourtheme.scss
• Vérifiez ensuite qu’elles apparaissent dans le fichier CSS généré :
  Path: _custom/shared/themes/yourtheme/css/yourtheme.css

Astuce supplémentaire
Il peut être utile d’ouvrir un second terminal :

• Exécutez la commande npm run build dans le premier terminal.
• Forcer la recompilation du fichier SCSS
  Pour corriger cela, vous pouvez « toucher » le fichier SCSS (mise à jour du timestamp) afin de forcer le processus watch de npm à recompiler :

touch _custom/shared/themes/yourtheme/css/yourtheme.scss

root ou pas root

Chaque développeur a ses habitudes et les environnements varient, ce qui peut compliquer la mise en place. Nous recommandons de ne pas utiliser « root », mais dans certains cas vous pourriez y être contraint.
Sur des systèmes où vous ne pouvez pas modifier la configuration sudoers, ou si le coût du changement est trop élevé, vous devrez peut-être utiliser root pour installer les bonnes versions de npm et Node.js, ainsi que pour exécuter la commande npm run watch.

Versions requises de npm et Node.js

Node.js et npm (Node Package Manager) sont essentiels pour installer et exécuter Tiki Wiki 27 et versions suivantes, conformément aux pratiques modernes du développement web.
À la date de cet article, Tiki Wiki requiert les versions suivantes installées sur votre système :

• npm : versions 9.0.0 à 11
• Node.js : versions 18.0.0 à 22

Exemple de procédure pour installer npm et Node.js

Pour mettre à niveau ou changer de version, rendez-vous sur Node.js Downloads.
Utilisez le sélecteur déroulant pour choisir la version de Node.js adaptée à votre environnement.

Suivez les instructions fournies pour installer la version sélectionnée.
Une fois installé, vous devriez être prêt à finaliser votre installation de Tiki.

Correction de la commande generateiconlist

Lors de l’exécution du Build System (sh setup.sh), le processus peut être interrompu par une erreur lors de l’exécution de la commande PHP build:generateiconlist.
Vous pouvez aussi tenter d’exécuter directement : /Applications/MAMP/bin/php/php8.2.20/bin/php console.php build:generateiconlist et obtenir l’erreur :
Failed to open the bootstrap css vendor file, bootstrap icons won't be synched. Maybe npm is not available at this stage.

Pour résoudre ce problème, j’ai supprimé « package-lock.json » et le répertoire « node_modules ».
Ensuite, j’ai lancé « npm i » (j’ai aussi lancé « npm audit fix --force », optionnel).
Puis j’ai relancé la commande de build (b) dans sh setup, ou simplement « npm run build », et l’exécution s’est terminée comme prévu.

Correction « System limit for number of file watchers reached »

Linux utilise le paquet inotify pour surveiller les événements du système de fichiers. Avec des projets qui suivent de nombreux fichiers (comme Tiki Wiki), vous pouvez atteindre la limite de watchers et voir des avertissements. Augmenter cette limite résout ces problèmes.

Pour traiter ce point, suivez la discussion : Stackoverflow et appliquez la solution adaptée à votre cas et à votre environnement.