# VocabulAyr — Le Fil des Mots Jeu d'étymologie française pour toute la famille, auto-hébergé : un chemin de 105 mots et expressions, cinq pistes par mot (sens, origines, registre, emplois, voisins), des mini-jeux, une fiche d'étymologie par mot, des grades d'écriture (du Griffonneur au Calligraphe d'or) et un thème clair/sombre. Le chemin n'ouvre qu'un mot à la fois : sa fiche assemblée à 100 % ouvre le suivant, et toutes les fiches acquises restent relire dans l'**Historique**. Adresse de la maison : **https://vocabulaire.servayr.duckdns.org** (port local 8020, même série que bibliothequayr=8000 et culinayr=8010). Techniquement : le projet sépare les **rouages du savoir**. Le savoir — les mots, leurs pistes, leurs mini-jeux — vit **en base de données** (table `jeu_mot` du dossier `data/`, avec un catalogue embarqué dans `jeu/catalogue/mots-complet.json` pour les installations neuves). Les rouages — le moteur du jeu — sont le fichier `jeu/static/jeu/index.html` (polices incrustées, zéro dépendance extérieure) que Django 6 habille : il y injecte les mots (`window.MOTS`), l'état du compte (`window.ETAT`) et le menu du site. Le moteur ne contient plus aucun mot. ## Ce que le site ajoute au fichier - **Des comptes de joueurs.** Ayr ouvre les comptes dans l'admin (`/admin/` → Utilisateurs) ; chaque membre se connecte ensuite sur n'importe quel appareil (tablette, téléphone, PC) et retrouve sa progression. - **La progression ET le savoir en base de données** (SQLite, dossier `data/`). Le jeu sauvegarde la progression au fil du jeu ; les mots sont importés depuis le catalogue au premier démarrage. **La sauvegarde nocturne couvre donc tout le site** : progressions, comptes, mots, mini-jeux. - **Un site fermé.** Sans connexion, une seule page : la connexion. - **Une page Paramètres** (menu du site, réservée à l'administrateur, même esprit que BibliothequAyr) : le **titre du site** — affiché dans le menu, sur les téléphones et sur la page de connexion — et **l'image de fond de la connexion**, avec aperçu immédiat et bouton pour la retirer. L'icône d'onglet (favicon) se dépose à part, dans `jeu/static/jeu/favicons/` du serveur. - **Une page Historique** : les fiches de tous les mots en poche, en lecture seule, avec leur badge (Fiche parfaite / improvisée). - **« Recommencer à zéro »**, en bas du jeu : chaque joueur remet sa propre progression à vide (double confirmation). ## La première connexion (une seule fois) Le site commence vide : la page de connexion devient alors l'écran de **première installation** — on y crée le compte de l'administrateur (« Ayr »). À partir de là, cet écran redevient la page de connexion classique et l'admin s'ouvre avec ce compte. ## Déployer sa propre instance ### Le conseil principal Si vous n'êtes pas à l'aise avec Docker et Linux : **faites-vous accompagner par une IA**. Donnez-lui ce README, le Dockerfile et le docker-compose.yml du dépôt, décrivez votre machine (distribution, Docker installé ?), et faites chaque étape avec elle, une à la fois. ### Les pièces du puzzle (pour comprendre avant de taper) - **Le code** : ce dépôt git. Il contient tout sauf vos données et vos secrets. - **L'image Docker** : construite par `docker compose up --build`. Le code y est figé ; vos données, jamais. - **Le dossier data/** : la base SQLite (comptes, progressions) et les médias (image de fond de la connexion). **C'est ici que vit maintenant la progression de toute la famille** — les sauvegardes sont indispensables (voir étape 7). - **Le fichier .env** : deux lignes de secrets. `DEBUG=0` (mode production). `SECRET_KEY` : la clé avec laquelle le site signe ses sessions et ses cookies — **ce n'est pas une clé d'API**. Elle se génère une fois, se garde précieusement, ne se partage jamais. Une variable optionnelle, `JOURNAL_ETAT=1`, active le journal de diagnostic (chaque sauvegarde de progression et d'avatar notée dans `docker logs vocabulayr`) : à retirer une fois le problème résolu, en production normale rien ne s'écrit. - **docker-compose.yml** : fourni — le conteneur, son port (8020, en local seulement) et les dossiers montés. Il voyage avec le code. - **VERSION** : le numéro de la version installée, incrémenté de 0.01 à chaque livraison. `cat VERSION` le rappelle, et l'image Docker porte la même étiquette (`docker images | grep vocabulayr`). - **install/** : les deux fichiers du timer de sauvegarde systemd, prêts à copier dans `/etc/systemd/system/` (étape 7). ### Les étapes 1. **Récupérer le code** git clone vocabulayr && cd vocabulayr 2. **Créer le .env** echo "DEBUG=0" > .env echo "SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(64))')" >> .env chmod 600 .env 3. **Préparer les dossiers de données** mkdir -p data staticfiles sudo chown -R 1001:1005 data staticfiles (1001:1005 = l'utilisateur interne du conteneur, mêmes numéros que bibliothequayr et culinayr.) 4. **Lancer** docker compose up -d --build Au premier démarrage : migration, fichiers statiques collectés, gunicorn à l'écoute sur le port **8020 de la machine, en local uniquement**. Ensuite : nom de domaine + reverse proxy HTTPS devant (Caddy, nginx…) qui transmet au 8020 — un extrait de Caddyfile prêt à adapter est dans `docs/caddy-extrait.txt`. 5. **Ouvrir https://vocabulaire.servayr.duckdns.org** → l'écran de première installation crée le compte administrateur. 6. **Ouvrir les comptes de la famille** : `/admin/` (compte Ayr) → Utilisateurs → Ajouter. Un identifiant, un mot de passe, c'est tout — le jeu crée la progression de chacun à la première partie. 7. **Sauvegarde nocturne** (indispensable : la base porte désormais tout — progressions, comptes, mots, mini-jeux) scripts/sauvegarde-vocabulayr.sh # premier essai, à la main Le script fait : copie cohérente de la base (« à chaud », mécanisme officiel SQLite), contrôle d'intégrité, empreintes sha256, copie des médias, garde 7 jeux. Destination : `/mnt/share/sauvegardes/vocabulayr//` (le même disque protégé que BibliothequAyr). Puis le timer systemd — tous les jours à 4h00, décalé de BibliothequAyr qui tourne à 3h30 : sudo cp install/vocabulayr-sauvegarde.* /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now vocabulayr-sauvegarde.timer systemctl list-timers --no-pager | grep vocabulayr ## Ajouter des mots / mettre le jeu à jour Les mots vivent **en base** : on ne touche plus jamais au fichier du moteur pour du contenu. ### Ajouter ou modifier un mot 1. Préparez un fichier `mot.json` au format catalogue (même forme que les entrées de `jeu/catalogue/mots-complet.json` : identifiant, titre, fiche `card`, les cinq `pistes` avec leurs mini-jeux, les perles de résolution) ; 2. Dans le dossier du site, sur le serveur : docker exec -it vocabulayr python manage.py ajouter_mot mot.json Ajouté à la suite du chemin, ou inséré avec `--ordre 7`. L'identifiant existe déjà ? Le mot est mis à jour, la place conservée. La structure est vérifiée avant écriture ; rien ne rentre si elle cloche, et la base entière est recontrôlée après. ### Mettre le code à jour 1. Remplacez le code par la nouvelle version (l'archive du coordonnateur, en gardant `data/` et `.env`) ; 2. `docker compose up -d --build`. ~10 secondes d'interruption. Au démarrage, une base vide reçoit automatiquement le catalogue (`importer_mots --si-vide`) : une base existante n'est jamais touchée. La progression de chacun est conservée : elle ne dépend que des identifiants de mots, jamais de la version du code. ## Développer / faire évoluer - Dossier séparé pour le dev (ex. vocabulayr-dev), même dépôt, DEBUG=1 dans son .env, port **8021** (jamais le 8020). Avant le premier `compose.dev.yml up` : `docker volume create vocabulayr-pip`. - Commandes de gestion du savoir : python manage.py importer_mots # (ré)importe le catalogue python manage.py ajouter_mot mot.json # ajoute/met à jour un mot python manage.py verifier_mots # filet de sécurité structurel python manage.py exporter_mots --fichier sauv.json # sortie catalogue - Tests du projet : `python manage.py test` (26 tests : site fermé, première installation, progression, catalogue, registre ternaire, commandes d'ajout/export). - Pistes d'évolution : statistiques de famille, mode « rejouer » dans l'Historique, éditeur de mots dans l'admin. ## Restaurer après un sinistre (le mode d'emploi du moi-de-dans-5-ans) 1. Réinstallez Docker, clonez ce dépôt (étapes 1 et 2 ci-dessus — un .env neuf avec une NOUVELLE SECRET_KEY convient) ; 2. Récupérez `data/` depuis votre disque de sauvegarde (db.sqlite3 + media/), placez-le dans `data/` — il porte les comptes, les progressions **et les 105 mots avec leurs mini-jeux** ; 3. `docker compose up -d --build` ; 4. Le site revient tel quel : comptes, progressions, mots, image de fond. (Sans `data/`, le site repart du catalogue : les mots y sont, seuls comptes et progressions sont perdus.)