VocabulAyr/README.md
VocabulAyr dab648013e VocabulAyr 0.04
Retouches de cohérence documentaire : URL réelle du dépôt à l'étape de clonage ;
lien permanent de la release à la place de « l'archive du coordonnateur » ;
destination de sauvegarde du README alignée sur le script (/mnt/share/sauvegardes/vocabulayr/data/<date>/) ;
compteur de tests exact (32) ; coquille « Arch Linux » dans l'extrait Caddy.
Aucune migration ; moteur, anti-régression et journal intacts.
2026-11-08 16:54:28 +00:00

206 lines
9.4 KiB
Markdown
Executable file

# 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 https://git.servayr.duckdns.org/Ayr/VocabulAyr.git 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/data/<date>/` (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 de la
release, en gardant `data/` et `.env`) :
https://git.servayr.duckdns.org/Ayr/VocabulAyr/releases/download/0.04/vocabulayr-0.04.tar.gz
Son sha256 est publié dans la note de la release : contrôlez-le
avant de décompresser.
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` (32 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.)