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

9.4 KiB
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.)