Installation sous macOS

Attention

Il y a moins de contributeurs·trices sur macOS que sur d’autres plateformes. Il se peut que l’installation et les tests unitaires fonctionnent correctement, partiellement ou pas du tout. Bref, en cas de problème n’hésitez pas à venir demander de l’aide sur le forum des Devs’ de Zeste de Savoir !

Les instructions ci-dessous ont été testées avec succès sur un MacBook Pro fin-2021, avec processeur M1 Pro, sous macOS 12 (Monterey) et 13 (Ventura).

Pour installer une version locale de ZdS sur macOS, veuillez suivre les instructions suivantes. Si une commande ne passe pas, essayez de savoir pourquoi avant de continuer.

macOS étant un système UNIX proche de Linux, l’installation fonctionne quasiment comme pour cet OS, à quelques détails près. La principale différence est que macOS étant basé sur BSD, il faut remplacer les outils BSD par ceux de GNU (les gnu-coreutils, utilisés sous Linux), et avec lesquels zds-site est conçu.

Note

Les instructions ci-dessous sont écrites pour macOS, mais il se peut que leur philosophie (utiliser les gnu-coreutils au lieu de ceux de BSD) permette d’installer zds-site sur un système *BSD.

Pré-requis

Avis aux utilisateurs·trices avancé·es

Ces instructions expliquent comment installer XCode, Homebrew, Python, pip, et les utilitaires GNU, sur macOS. Si vous avez déjà :

• une installation fonctionnelle de Homebrew et de Python 3.8+ ;

• configuré votre terminal pour utiliser les utilitaires GNU à la place de ceux de BSD (avec linuxify, par exemple) ;

alors vous pouvez passer à la section suivante concernant l’installation de zds-site.

XCode

Pour installer ou lancer zds-site sur macOS, vous devrez utiliser un terminal pour pouvoir y entrer des commandes servant à installer ou lancer le site et ses composants annexes. macOS intègre un terminal nativement, que vous pouvez utiliser.

Pour utiliser complètement le terminal sous macOS, vous devez installer quelques outils supplémentaires qui ne sont pas installés de base avec macOS. Depuis votre terminal, exécutez cette commande pour les installer.

xcode-select --install

Homebrew

Vous aurez ensuite besoin d’Homebrew, un système permettant de télécharger et d’installer des logiciels sous macOS depuis la ligne de commande, et de les mettre à jour. Nous nous en servirons pour installer Python (si nécessaire) et les dépendances de zds-site.

Les instructions d’installation d’Homebrew sont sur leur site web.

Python 3

zds-site dépend d’une version récente de Python 3. Sous macOS Ventura et plus récent (macOS 13+), Python 3 est installé avec XCode, qu’on a installé plus haut. Pour vérifier, exécutez la commande suivante :

python --version

Si vous obtenez une version inférieure à Python 3.9 (et notamment si vous voyez Python 2.7), il vous faudra installer une version récente de Python avec Homebrew. Sinon, vous pouvez utiliser la version intégrée avec macOS de Python, mais vous devrez installer pip.

Si votre version de Python est trop vieille

Il vous faut installer Python avec Homebrew. Exécutez dans un terminal :

brew install python

Puis revérifiez la version de Python avec python --version. Si elle n’a pas changé, tentez de redémarrer votre terminal.

Si vous gardez la version native de Python

Si vous avez décidé de garder la version native de Python, si elle est assez récente, vous allez quand même devoir installer pip, un logiciel compagnon de Python servant à installer des bibliothèques externes en Python — des extensions permettant d’augmenter ses possibilités facilement.

Pour vérifier que vous disposez de pip, exécutez l’une de ces commandes :

pip --version           # ou
pip3 --version          # ou
python -m pip --version

Vous devriez obtenir un numéro de version de pip et de Python, comme cela :

$ pip --version  # ou une des autres commandes
pip 22.3.1 from /opt/homebrew/lib/python3.10/site-packages/pip (python 3.10)

Si ces commandes retournent toutes une erreur, et non un numéro de version, vous devez installer pip. Les instructions d’installation sont sur le site web de pip.

Utilitaires GNU/Linux au lieu de BSD

zds-site est conçu pour fonctionner avec les utilitaires de Linux (les gnu-coreutils), différents des utilitaires natifs de *BSD (et donc de macOS, qui en est un lointain descendant).

Le plus simple est le projet linuxify, qui installe toutes les versions GNU de divers logiciels avec Homebrew. Par défaut, ces versions viennent préfixées, pour ne pas entrer en conflit avec les versions du système. En pratique, ce n’est pas un problème d’utiliser dans votre environnement local les versions de GNU, donc vous pouvez utiliser en permanence ces versions à la place de celles de BSD.

Dans le doute, remplacez en permanence par les versions de GNU : c’est sans impact négatif et ça permet à zds-site de fonctionner sans manipulation particulière.

Commencez par installer linuxify, tel que précisé sur leur site. Si vous avez une erreur disant command not found: git, exécutez dans votre terminal la commande brew install git.

Lorsqu’il vous demande Do you want to change your shell to the latest bash, répondez non (n).

Ensuite, si vous choisissez de remplacer en permanence les utilitaires BSD par ceux de GNU, exécutez la commande suivante pour automatiquement utiliser les utilitaires GNU quand vous utilisez votre terminal, puis redémarrez votre terminal.

echo ". ~/.linuxify" >> ~/.zshrc

Si vous choisissez de ne pas le faire, alors il vous faudra exécuter cette commande dans chaque terminal où vous exécuterez des commandes d’installation ou de mise à jour de zds-site (une fois par terminal, pas besoin de la ré-exécuter à chaque fois) :

. ~/.linuxify

Dépendances système

Le script d’installation n’installant pas encore les paquets automatiquement sur macOS, vous devez le faire à la main, via Homebrew. Exécutez la commande suivante pour tout installer.

brew install curl gettext cairo

Une fois les pré-requis terminés, vous pouvez vous lancer dans l‘installation de l’environnement de zds-site.

Installation de zds-site

Commencez par cloner le dépôt de zds-site, ou idéalement, votre fork sur lequel vous travaillerez avant d’envoyer des Pull-Requests.

git clone git@github.com:VOTRE-PSEUDO-GITHUB/zds-site.git
cd zds-site

zds-site peut s’installer de deux façons :

• une version minimale, qui ne contient que le site lui-même, mais pas le moteur de recherche ni le système d’export des PDF ;

• une version complète, qui contient tout, et qui est aussi plus lourde à installer.

Attention

La version complète ne peut être automatiquement installée pour le moment car l’installeur télécharge une version de Typesense (le moteur de recherche) spécifique à Linux.

Le système de génération et d’export des PDF devrait fonctionner normalement.

La version minimale a été testée avec succès.

Voir aussi

• Installation de Typesense ;

• installation de LaTeX.

Pour installer la version minimale, exécutez depuis la racine du dépôt que vous venez de cloner :

./scripts/install_zds.sh +base -packages

Si vous voulez la version complète :

./scripts/install_zds.sh +full -packages

Note

L’option -packages désactive l’installation automatique des dépendances système, qui n’est pour le moment supportée que sous Linux.

Note

Vous pouvez relire le script avant de l’exécuter pour savoir ce qu’il fait. Mais dans l’idée, ce script va :

• installer virtualenv (via pip), un logiciel Python permettant de créer des environnements virtuels cloisonnés en Python ;

• créer un environnement virtuel dans le sous-dossier zdsenv ;

• installer dans votre dossier utilisateur le logiciel nvm (Node Versions Manager), un outil permettant d’installer différentes versions de NodeJS ;

• installer la bonne version de NodeJS localement (uniquement pour zds-site) et intégrer le chargement de la cette bonne version à l’environnement virtuel ;

• installer les dépendances de zds-site dans l’environnement virtuel ;

• installer zmarkdown, le moteur de rendu Markdown utilisé par zds-site ;

• installer les dépendances du front-end avec npm puis compiler le font-end ;

• créer la base de données utilisée par zds-site (avec SQLite) et la remplir de données de test ;

• intégrer au dépôt local un pre-commit hook vérifiant que le code Python est correctement formaté à chaque commit (et le formatant le cas échéant).

Si vous installez la version complète, le script va, en plus :

• installer Typesense dans le dossier zds-site/.local/typesense ;

• installer TeXLive (permettant de compiler du LaTeX en PDF, utilisé pour les exports PDF) dans le dossier zds-site/.local/texlive ;

• cloner le dépôt contenant le modèle LaTeX utilisé par l’export PDF dans le dossier zds-site/latex-template.

Lancement de zds-site

Une fois dans votre environnement Python et toutes les dépendances installées, lançons ZdS.

Il faut d’abord lancer zmarkdown, le moteur de rendu Markdown utilisé par Zeste de Savoir. Ce moteur fonctionne sur un modèle client-serveur : zds-site envoie une requête HTTP (en local) pour obtenir le rendu d’un document Markdown en HTML, ePub, ou LaTeX. Il faut donc démarrer le serveur zmarkdown en arrière-plan.

Ensuite, on démarre zds-site.

# Depuis la racine du dépôt zds-site
make zmd-start
make run

Le démarrage de zds-site entraîne celui du backend Python dans un mode optimisé pour le développement. Notamment, le cache est totalement désactivé et des outils de débogage rendent disponible plein d’informations sur chaque page, les données techniques envoyées (paramètres de templates, …) et les requêtes SQL envoyées. Ces outils sont pratiques mais ils peuvent être lourds. Si vous avez une machine peu puissante et que vous voulez une version plus légère, mais sans tous ces outils de développement, vous pouvez démarrer une version plus légère de zds-site ainsi.

make run-fast

Ces deux façons de lancer zds-site lancent aussi la compilation automatique à la moindre modification des fichiers du front-end (SCSS, JS, etc.). Si vous voulez également désactiver cela, car vous ne travaillez pas sur le front-end et/ou que vous voulez une version plus légère du site, vous pouvez ne lancer que le back-end :

make run-back       # ou (cf. plus haut)
make run-back-fast

Pour lister toutes les options disponibles, exécutez simplement, sans argument :

make

Données de test

L’installeur a créé pour nous le jeu de données utile au développement. Si pour une raison ou pour une autre, vous voulez repartir de zéro en écrasant toutes les données de votre installation locale, vous pouvez le faire.

Avertissement

Cette commande supprime totalement votre base de données, ainsi que tous les contenus que vous avez pu créer, sur votre instance locale, puis recrée des données de test aléatoires à partir de zéro.

Il n’est pas possible d’annuler cette opération.

make new-db

Mettre à jour votre instance locale

Pour rapidement mettre votre instance locale à jour, par exemple pour tester une Pull-Request ou si vous vous êtes mis à jour depuis le dépôt principal, lancez :

make update

Cette commande va mettre à jour le back-end et le front-end, puis migrer la base de données (si nécessaire) et recompiler le front-end.