Menu utilisateur du rail identique au mobile (Mon avatar, Paramètres, Admin, Déconnexion) ; titre du site masqué sur téléphone/tablette. Fragment réutilisable _image_upload.html pour le fond (Paramètres) et l'avatar, à la façon BibliothequAyr ; nouvelle route POST /api/fond/ (admin, Pillow, plafond 5 Mo) ; retrait du fond via BoiteDialog. Icônes SVG du site à la place des Bootstrap Icons jamais chargées ; les 9 favicons voyagent dans le projet. Aucune migration ; moteur, anti-régression et journal intacts.
201 lines
9.2 KiB
Markdown
Executable file
201 lines
9.2 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 <URL-du-dépôt> 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/<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 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.)
|