RoadTripsGenerator/README.md at 02473fafbfd563d2f5109708cacfbe127b82f570

0 Fork 0

Files

T

FabriceandClaude Opus 5.5 02473fafbf Administration dans un conteneur Docker (Dockerfile, exemples compose et nginx) ; arrêt propre sur SIGTERM

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Mf2kATMtqVABHSYdxJMnim

2026-10-09 16:59:27 +00:00

20 KiB

Raw Blame History

RoadTripsGenerator (RTG) est un logiciel qui génère un site web statique de road-trips : une carte interactive par voyage et par jour, avec les photos, les vidéos, les traces GPS et le récit du voyage.

C'est sans prétention et il faudrait probablement des développements bien plus sérieux pour obtenir un logiciel « presse-bouton », mais si cela peut donner des idées…

Je me suis rendu compte que je passais des heures à monter des films de mes road-trips que finalement je ne regardais pas moi-même : trop longs mais pas assez d'infos, pas interactifs, etc. Je me suis donc demandé sous quelle forme présenter mes voyages pour pouvoir me les remémorer en famille et les partager. C'est comme cela que ce petit projet a vu le jour.

Le principe

Pour chaque voyage, je dispose de photos et de vidéos géolocalisées (photos iPhone, films GoPro), des traces GPS de chaque journée et d'un récit écrit en Markdown.

Les scripts lisent les positions GPS des photos et des vidéos, les placent sur une carte avec la trace du parcours découpée par jour, et construisent des pages web où l'on peut, en parallèle, lire le récit du voyage. Voir par exemple mon road-trip de l'été 2025.

Ils préparent aussi les médias pour le web :

vidéos : un 720p H.264 lisible partout, chargé par défaut, et un 1080p HEVC proposé à la demande (environ 40 % plus léger que du H.264 à qualité égale) ;
photos : une version allégée (1600 px, quelques centaines de Ko) affichée dans les diaporamas, le clic ouvrant l'original ;
aperçus : une image tirée de chaque vidéo, affichée avant la lecture.

Les originaux ne sont jamais modifiés. Le site produit est statique : une simple copie suffit pour le publier ou le transporter.

Installation

RTG fonctionne sous macOS et Linux ; Windows devrait fonctionner mais n'a pas encore été testé. Il lui faut :

Élément	Rôle	Version
Python	le logiciel lui-même	3.10 ou plus récent
pipx	installe RTG et ses modules Python dans un espace à part	—
exiftool	lit les dates et positions GPS des photos et des vidéos	toute version récente
ffmpeg (avec libx265 et libx264)	compresse les vidéos, tire les images d'aperçu	5 ou plus récent

Les modules Python (folium, pandas, gpxpy, Pillow, pillow-heif…) sont installés automatiquement avec RTG.

macOS

Installer Homebrew s'il n'est pas déjà là :

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Installer les outils, puis rendre pipx accessible :

brew install python pipx exiftool ffmpeg
pipx ensurepath

Ouvrir une nouvelle fenêtre de Terminal (ou taper source ~/.zshrc, zsh étant le shell par défaut de macOS) : pipx ensurepath ajoute ~/.local/bin au chemin des commandes, mais une fenêtre déjà ouverte ne le voit pas. Si rtg reste introuvable, c'est ce point.

Le ffmpeg de Homebrew contient libx265, libx264 et l'encodeur matériel VideoToolbox du Mac.

Linux (Debian, Ubuntu et dérivées)

sudo apt install python3 pipx ffmpeg libimage-exiftool-perl
pipx ensurepath

Puis fermer et rouvrir le terminal. Sur Fedora : sudo dnf install pipx perl-Image-ExifTool et ffmpeg depuis RPM Fusion.

Windows (non testé)

Dans PowerShell :

winget install Python.Python.3.12 Gyan.FFmpeg OliverBetz.ExifTool
py -m pip install --user pipx
py -m pipx ensurepath

Puis fermer et rouvrir PowerShell.

Installer RTG

Récupérer le dépôt (ou le copier, par exemple sur un disque externe) :

git clone https://git.ouaibe.fr/Korrigan/RoadTripsGenerator.git
pipx install --editable ./RoadTripsGenerator

Avec --editable, la commande rtg utilise directement le code du dossier : une mise à jour du dépôt (git pull) est prise en compte sans réinstaller. Le dossier doit alors rester accessible (disque branché).

Vérifier

rtg verifier

La commande contrôle Python, les modules, exiftool, ffmpeg et ses encodeurs, et donne pour chaque élément manquant la commande à taper sur votre système.

Organisation des dossiers

Le dépôt et le site sont deux dossiers voisins. Un voyage est un dossier qui contient au moins un des sous-dossiers photos, rushs ou routes. Les voyages rangés à la racine du site forment la rubrique « Voyages » de la page d'accueil. Ceux rangés un niveau plus bas, dans un dossier de regroupement (ici Balades), forment une rubrique du nom de ce dossier. L'accueil montre les 2 plus récents de chaque rubrique (ACCUEIL_NB=3 pour en montrer plus), avec un lien vers la liste complète.

CLEROADTRIPS
|-RoadTripsGenerator          ce dépôt
| |-Scripts
|   |-templates               mise en page (HTML, CSS, JavaScript)
|-Road-Trips                  le site
  |-Ete-2025
  | |-photos                  photos (JPEG)
  | |-rushs                   vidéos d'origine (peut être un lien vers un disque externe)
  | |-routes                  une trace GPX par jour, date dans le nom : 2025-08-02.gpx
  | |-voyage.md               le récit
  |-Balades
    |-Aisne-06-2026
      |-...

Dans le récit voyage.md, deux raccourcis évitent les liens écrits en dur (qui ne marcheraient pas à la fois en local et en ligne) :

[Carte du jour](jour:2025-08-02)
[Le col](media:photos/IMG_4831.jpeg)
[La descente](media:videos/GH011272.mp4)

L'interface

cd /Volumes/CLEROADTRIPS/Road-Trips
rtg interface

Le navigateur s'ouvre sur l'interface de RTG (adresse http://127.0.0.1:8765/…, visible de cet ordinateur seulement). Laisser la fenêtre de Terminal ouverte pendant l'utilisation ; Ctrl+C l'arrête.

Mes voyages : tous les voyages par rubrique, avec leurs dates et l'avancement des vidéos, des photos et des pages. Le bouton « Nouveau voyage » crée le dossier et son voyage.toml.
Un voyage, en cinq onglets :
- Journées : la carte des traces, jour par jour, et les kilomètres. Une trace sans heures et sans date dans son nom (un itinéraire préparé, par exemple) se rattache ici à un jour. RTG propose le jour où des photos ou des vidéos ont été prises le long de la trace. On peut aussi répartir les traces à la suite, un jour par trace.
- Carte et corrections : glisser une photo ou une vidéo mal placée, placer celles qui n'ont pas de position (cliquer son nom puis la carte), et masquer des zones de trace : autour de chez soi, ou sur une erreur du GPS. Une zone peut valoir pour tous les voyages (zone privée). Fond plan ou satellite. Les corrections sont notées dans voyage.toml ([positions], [corrections]) ou site.toml ([confidentialite]) et appliquées à la génération suivante ; les fichiers d'origine ne sont pas modifiés.
- Sources : où sont les traces, les vidéos et les photos d'origine, choisies dans une fenêtre de dossiers ou collées. Le nombre de fichiers trouvés s'affiche, et un disque débranché est signalé.
- Infos et récit : titre, moto et récit (voyage.md).
- Générer : tailles des rushs et de ce qui reste à encoder, espace libre, puis lancement de la génération ou de l'encodage seul. L'avancement de chaque vidéo s'affiche ; « Arrêter » interrompt proprement, sans perdre les vidéos déjà finies.
Réglages : les réglages de site.toml (qualité vidéo, taille des photos, fuseau, cartes My Maps) et la vérification des outils installés.
Voir le site : le site généré, servi tel quel, vidéos comprises.

Accès à l'interface

L'interface permet de modifier le site et de lire les fichiers de l'ordinateur : elle est protégée.

Sur l'ordinateur où elle tourne, l'adresse ouverte au lancement contient une clé d'accès tirée au hasard (…/?jeton=…), affichée aussi dans le Terminal. Sans elle, l'interface demande de se connecter. La clé change à chaque lancement ; le navigateur garde ensuite une session de 12 heures, perdue quand l'interface s'arrête. « Se déconnecter » la ferme tout de suite.
Mot de passe : rtg mot-de-passe le définit (10 caractères au moins). Seule une empreinte est enregistrée, hors du site : ~/.config/rtg/acces.toml (%APPDATA%\rtg\acces.toml sous Windows). rtg mot-de-passe --supprimer l'efface. Après 5 essais faux, l'adresse IP doit attendre une minute, puis deux, quatre… jusqu'à une heure.
Depuis une autre machine (le serveur qui héberge le site, par exemple) : rtg interface --distant, qui exige le mot de passe. Sans HTTPS, ce mot de passe circulerait en clair. Trois solutions :
- servir l'interface derrière le serveur web du site, en HTTPS, sur une adresse à part ;
- --certificat cert.pem --cle cle.pem ;
- le plus simple : un tunnel SSH. Sur le serveur, lancer rtg interface --sans-navigateur (sans --distant). Sur le Mac, ouvrir ssh -L 8765:127.0.0.1:8765 serveur, puis l'adresse avec la clé affichée sur le serveur.
Bouton « Connexion » sur l'accueil du site : voir ci-dessous.
Les fichiers de réglages (site.toml, voyage.toml) sont dans les dossiers du site. Si le serveur web publie ce dossier tel quel, ils sont lisibles par tous, avec les chemins de tes disques. Rien de secret n'y est écrit, mais on peut les refuser au serveur web (par exemple location ~ \.toml$ { deny all; } pour nginx, ou <FilesMatch "\.toml$"> Require all denied </FilesMatch> pour Apache).

Administration depuis le site

Pour administrer le site depuis son adresse publique (bouton « Connexion » en haut à droite de l'accueil, qui mène à https://roadtrips.ouaibe.fr/admin/), l'interface tourne sur la machine qui sert le site, derrière son serveur web en HTTPS. Les sources (rushs, traces, photos) doivent alors être accessibles depuis cette machine pour encoder et générer.

Sur cette machine, une fois : rtg mot-de-passe.
Lancer l'interface, en permanence de préférence (service, tmux…) :
```
rtg --racine /chemin/vers/Road-Trips interface --proxy --prefixe /admin --port 8765
```
Elle n'écoute que sur 127.0.0.1 : seul le serveur web peut la joindre. Le mot de passe est obligatoire.
Transmettre /admin/ à l'interface depuis le serveur web.
- Traefik qui envoie le site à un conteneur nginx (docker compose) : rien à changer dans Traefik. Ajouter le bloc de exemples/nginx-admin.conf dans le nginx.conf du conteneur, et extra_hosts: ["host.docker.internal:host-gateway"] au service dans docker-compose.yml, puis docker compose up -d.
- Traefik seul (fichier de configuration dynamique) : copier exemples/traefik-rtg-admin.yml dans le dossier de configuration dynamique de Traefik, en y mettant les mêmes entryPoints et certResolver que pour le site. Le fichier indique l'adresse à mettre selon que Traefik tourne dans Docker sur le Mac, directement sur le Mac, ou sur une autre machine (dans ce dernier cas, lancer RTG avec --ecoute 0.0.0.0 en plus).
- nginx, dans le bloc server du site en HTTPS :
```
location ^~ /admin/ {
    proxy_pass http://127.0.0.1:8765;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
}
location ~ \.toml$ { deny all; }
```
- Apache (modules proxy, proxy_http, headers) :
```
ProxyPass        /admin/ http://127.0.0.1:8765/admin/
ProxyPassReverse /admin/ http://127.0.0.1:8765/admin/
RequestHeader set X-Forwarded-Proto "https"
<FilesMatch "\.toml$">
    Require all denied
</FilesMatch>
```
Dans l'interface, Réglages → « Administration depuis le site » : adresse /admin/. Après « Refaire l'accueil », le bouton « Connexion » apparaît sur la page d'accueil.

L'administration dans Docker

Plutôt que de laisser rtg interface ouvert dans un Terminal, on peut le faire tourner dans un conteneur, à côté du nginx du site : il démarre avec Docker et redémarre tout seul. Le Dockerfile est à la racine de RoadTripsGenerator (Python, ffmpeg, exiftool).

Définir le mot de passe sur le Mac, une fois : rtg mot-de-passe. Le conteneur lit le même fichier.
Ajouter le service rtg au docker-compose.yml du site : voir exemples/docker-compose.yml. Le conteneur voit /Volumes aux mêmes chemins que le Mac : la clé, le disque des rushs… Les sources notées dans les voyage.toml restent donc valables.
Dans nginx.conf, faire pointer /admin/ vers ce conteneur : voir exemples/nginx-admin.conf. Le site reste en ligne même si le conteneur RTG est arrêté.
docker compose up -d --build.

Après une mise à jour de RTG : docker compose up -d --build rtg. Un disque branché après le démarrage du conteneur peut demander docker compose restart rtg. L'encodage utilise les processeurs attribués à Docker (réglages de Docker Desktop, « Resources ») ; l'encodeur matériel VideoToolbox du Mac n'est pas disponible dans le conteneur.

Le bouton n'est qu'un lien : la protection est celle de l'interface (mot de passe, blocage après plusieurs essais faux, cookie de session limité à /admin/, envoyé seulement en HTTPS).

Tout ce que fait l'interface s'écrit dans site.toml et les voyage.toml. On peut toujours utiliser les commandes ci-dessous ou modifier ces fichiers à la main. Une réécriture par l'interface conserve les valeurs mais pas les commentaires.

Utilisation : la commande `rtg`

Depuis le dossier du site (Road-Trips) :

rtg migrer                            # une fois : écrit site.toml et un voyage.toml par voyage
rtg etat                              # avancement de chaque voyage
rtg generer Balades/Vexin-10-2026     # un voyage, puis l'accueil
rtg generer --sans-compression        # tous les voyages, sans encoder de vidéo
rtg analyser Balades/Vexin-10-2026    # ce que RTG trouve dans les sources
rtg verifier                          # tout est-il installé ?
rtg interface                         # l'interface dans le navigateur
rtg mot-de-passe                      # mot de passe de l'interface (accès distant)
rtg interface --proxy --prefixe /admin   # derrière le serveur web du site (bouton Connexion)

Les sources d'un voyage peuvent rester où elles sont, nommées n'importe comment : on les indique dans son voyage.toml.

titre = "Balade dans le Vexin"
moto = "BMW R 1300 GS Adventure"

[sources]
traces = ["/Volumes/GPS/2026/vexin.gpx"]
videos = ["/Volumes/LaCie/Perso/Gopro/Gopro-2026/Vexin"]
photos = ["~/Pictures/Export/Vexin"]

RTG range alors lui-même les traces par journée (routes/AAAA-MM-JJ.gpx, d'après leurs horodatages, à défaut la date du nom de fichier, ou le jour choisi dans l'interface et noté dans [dates_traces]) et copie les photos dans photos/ (les HEIC de l'iPhone sont converties en JPEG). Une photo sans GPS reçoit la position de la trace à son heure, quand la trace est horodatée. Les réglages communs (qualité vidéo, taille des photos, fuseau horaire, cartes My Maps…) sont dans site.toml.

Les scripts de Scripts/ restent disponibles pendant la transition ; ils produisent le même site. Ils demandent en plus d'installer à la main les modules Python : pip3 install pandas folium gpxpy markdown2 numpy pillow.

Mode d'emploi (anciens scripts)

Tout le site, ou quelques voyages

Depuis le dossier du site :

cd Road-Trips
../RoadTripsGenerator/Scripts/genere_site.sh                        # tous les voyages
../RoadTripsGenerator/Scripts/genere_site.sh Balades/Vexin-10-2026  # un seul
SKIP_COMPRESS=1 ../RoadTripsGenerator/Scripts/genere_site.sh        # sans réencoder les vidéos

Pour chaque voyage, genere_site.sh enchaîne les étapes ci-dessous, puis régénère la page d'accueil et la carte globale. Un voyage d'une seule journée (une balade, souvent) n'a pas de carte générale intermédiaire : sa page est directement la carte du jour, avec photos et vidéos. Chaque étape ne refait que ce qui a changé : relancer le script est rapide, sauf quand de nouveaux rushs sont à encoder.

Étape par étape

Depuis le dossier d'un voyage (ici Road-Trips/Balades/Vexin-10-2026, d'où les ../../../) :

Commande	Rôle	Produit
`../../../RoadTripsGenerator/Scripts/extraction_infos.sh`	positions GPS des photos et vidéos	`export_photos.csv`, `export_videos.csv`
`../../../RoadTripsGenerator/Scripts/compress.sh`	vidéos web (long)	`videos/`
`../../../RoadTripsGenerator/Scripts/prepare_web.py`	photos allégées, aperçus	`photos_web/`, `apercus/`
`../../../RoadTripsGenerator/Scripts/genere_carte.py`	pages du voyage	`index.html`, `mini.html`, `html/`, `assets/`, `<voyage>.kml`

Puis, depuis le dossier du site, la page d'accueil :

../RoadTripsGenerator/Scripts/genere_index_general.py

Sans compression, il faut faire de videos un lien vers rushs : ln -s rushs videos.

Réglages utiles

compress.sh : ENCODER=vt (encodeur matériel du Mac, bien plus rapide, un peu moins bon à taille égale), JOBS=N, CRF_HEVC, CRF_H264, FORCE=1 pour tout réencoder. Une vidéo déjà encodée mais illisible (encodage interrompu) est refaite automatiquement.
prepare_web.py : WEB_PX=1600 (taille des photos), WEB_QUALITE=80, FORCE=1.
bench_crf.sh : mesure la qualité (VMAF ou SSIM) d'un extrait de rush à plusieurs CRF, pour choisir CRF_HEVC / CRF_H264 sur ses propres images.

Carte globale de l'accueil

Sous les rubriques, l'accueil affiche une grande carte (carte_globale.html, fond OpenStreetMap, sans Google) qui réunit le contenu récupéré de nos cartes Google My Maps et les voyages du site (rubrique « Voyages »), un calque et une couleur par voyage ; un clic sur une trace mène au voyage. Un fichier moto.txt (une ligne) dans un voyage ajoute la moto à son nom dans la légende, par exemple « Ete 2026 (BMW R 1300 GS Adventure) ».

On peut y ajouter des cartes Google My Maps : mettre leurs liens, un par ligne, dans mymaps.txt à la racine du site (les cartes doivent être partagées en « Tous les utilisateurs disposant du lien »). Le KML de chaque carte est récupéré une seule fois dans _mymaps/ ; ensuite la carte ne dépend plus de Google (MYMAPS_MAJ=1 pour le reprendre après avoir modifié la carte Google). On peut aussi déposer à la main des exports .kml ou .kmz dans _mymaps/. Chaque calque My Maps devient un calque de la carte, avec ses couleurs d'origine.

Chaque voyage produit aussi un <voyage>.kml (tout le voyage en une seule trace, avec sa distance et un lien vers sa page, sous les 5 Mo acceptés par My Maps), pour qui voudrait l'importer dans une carte My Maps. Régler l'adresse publique du site avec SITE_URL (par défaut https://roadtrip.ouaibe.fr/) pour des liens corrects.

Modifier l'apparence

Toute la mise en page est dans Scripts/templates/ :

carte.css, carte.js : style et comportement des pages de voyage (copiés dans assets/ de chaque voyage à la génération) ;
fragments.html : les morceaux de HTML (popups photo et vidéo, journal, boutons, barre des jours) ;
fragments_globale.html : les popups et la légende de la carte globale ;
base_accueil.html, accueil.html, liste.html : la page d'accueil (rubriques Voyages et Balades, les 2 plus récents de chacune) et les listes complètes voyages.html, balades.html.

Après une modification, SKIP_COMPRESS=1 ../RoadTripsGenerator/Scripts/genere_site.sh régénère tout en quelques dizaines de secondes.

Publier

Il suffit de copier le dossier du site. Les sous-dossiers rushs (originaux, très lourds) et les fichiers export_*.csv sont inutiles en ligne ; photos reste nécessaire pour l'ouverture des originaux.

Contribuer

Pour pouvoir faire des push :

git remote set-url origin https://<nom d'utilisateur>@git.ouaibe.fr/Korrigan/RoadTripsGenerator.git

Pour éviter de retaper le mot de passe pendant une heure pour les autres push :

git config --global credential.helper 'cache --timeout=3600'

20 KiB Raw Blame History