Linux Journey

ProjetLinux Journey (cours de linuxjourney.com) — serveur local
Date2026-09-19
MachineFedora 44, Python 3.14.7, git 2.55.0
Statut✅ EN COURS sur http://127.0.0.1:8080/
Clone~/dev/linuxjourney (upstream : itamarg365/linuxjourney @ 21d905a)
Venv~/dev/linuxjourney/.venv

1. Setup & contraintes

Je fais tourner le cours Linux Journey en local pour l’étudier sans internet. Deux sources candidates existaient :

  • labex-labs/linuxjourney — le repo de contenu officiel (leçons Markdown dans lessons/ + courses/), mais aucune application web dedans : contenu seul.
  • itamarg365/linuxjourney — un serveur FastAPI autonome qui sert le cours anglais archivé avec le look du site original (fork de LunaGNUisance/linuxjourney + styles de web.archive.org). Recette du README : pip install -r requirements.txt && cd src && uvicorn main:app.

J’ai choisi le serveur FastAPI. Contraintes : je travaille depuis le sandbox Obsidian — pas de sudo, pas d’installation de paquets système (/usr/bin/python3 n’a pas de module pip). Mais le sandbox peut écrire dans ~/dev, donc toute l’app vit dans un venv utilisateur, jamais dans les dossiers système.

2. Étapes chronologiques

Phase 1 — Clone

git clone --depth 1 https://github.com/itamarg365/linuxjourney ~/dev/linuxjourney

✅ Succès. Le repo contient images/, lessons/locales/en_english/ (22 dossiers de cours + assets), src/main.py, templates/lesson.html, requirements.txt.

Phase 2 — venv (le Python système n’a pas pip)

python3 -m venv ~/dev/linuxjourney/.venv

✅ Succès — pip 26.2.1 disponible dans le venv.

Phase 3 — Installation des dépendances épinglées

~/dev/linuxjourney/.venv/bin/pip install -r requirements.txt

✅ Succès sur Python 3.14 (étonnamment fluide pour un pin de 2022) : fastapi-0.88.0, starlette-0.22.0, pydantic-1.10.26, beautifulsoup4-4.11.1, uvicorn-0.53.0, markdown-server-0.1.4, plus les extras fastapi[all] (httpx, orjson, websockets…).

Phase 4 — Premier lancement (port 8000, selon le README)

cd ~/dev/linuxjourney/src
nohup ~/dev/linuxjourney/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 > ~/dev/linuxjourney/uvicorn.log 2>&1 &

⚠️ Le serveur annonçait Uvicorn running on http://127.0.0.1:8000 mais est mort à la fin de mon appel shell sandbox (curl → 000, aucun processus). Cause racine : le sandbox tue les processus enfants quand l’appel d’outil se termine — nohup ne suffit pas.

Phase 5 — Lancement détaché (setsid) → passage au port 8080

cd ~/dev/linuxjourney/src
setsid ~/dev/linuxjourney/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8080 </dev/null >> ~/dev/linuxjourney/uvicorn.log 2>&1 &

✅ A survécu. J’ai choisi 8080 au lieu de 8000 car :8000 est le port habituel du client freeCodeCamp (skill fcc-lab) — une collision en moins.

Phase 6 — Vérification (sortie réelle)

curl -s -o /dev/null -w "home: %{http_code}\n" http://127.0.0.1:8080/                        → 200
curl -s -o /dev/null -w "lesson: %{http_code}\n" http://127.0.0.1:8080/lesson/command-line/the-shell → 200
curl -s -o /dev/null -w "static css: %{http_code}\n" http://127.0.0.1:8080/static/assets/category/application-….css → 200
# le raccourci marche aussi : /lesson/the-shell → 307 → /lesson/command-line/the-shell

Les pages de leçon s’affichent avec le menu latéral (22 catégories), le contenu, les exercices et les quiz extraits du HTML archivé par BeautifulSoup.

Phase 7 — Lanceur pratique

~/dev/linuxjourney/start.sh (chmod +x) : ./start.sh en premier plan / ./start.sh --daemon en arrière-plan avec surcharge PORT :

PORT=8090 ./start.sh --daemon   # port personnalisé

Phase 8 — GitHub : fork & premières contributions (2026-09-19)

  • Authentification gh en tant que sambaseness (device flow, scopes repo, workflow — le second refresh a ajouté workflow, nécessaire car l’historique upstream contient des modifications de .github/workflows/sync-lessons.yml que les pushs OAuth refusent sans ce scope).
  • Le fork sambaseness/linuxjourney (repo de contenu officiel labex-labs/linuxjourney) existait déjà (2026-08-24) mais était périmé → synchronisé sur upstream 98f4eefe.
  • Push du serveur local vers mon compte en repo privé : sambaseness/linuxjourney-local (privé, car la clause de marque CC BY-SA interdit un clone public imitant le site officiel).
  • Constats de l’analyse du code (audit réalisé) :
    • Contenu officiel : 186 leçons × 9 langues (de/en/es/fr/ja/ko/pt/ru/zh), toutes avec frontmatter lesson_id, checks :::single-choice et Résumé final — zéro dérive structurelle entre langues (les IDs EN↔FR correspondent exactement). Les leçons françaises se finissent par ## Résumé — un grep de contrôle doit en tenir compte sous peine de faux négatifs.
    • App FastAPI locale : 500 latents (leçon sans <h3>Exercise</h3> → ValueError ; slug inconnu → KeyError), open() sans context managers, chemins dépendants du CWD, dépendance inutilisée markdown-server.
  • Corrections commitées (2 commits → master de linuxjourney-local) — vérifiées avant push :
    • 482be6f fix: robust lesson parsing, 404s instead of 500s, add /health
    • eb57f65 chore: drop unused markdown-server dependency
    • Vérification : balayage 185/185 leçons → 200 ; leçon/catégorie inconnue → 404 ; /health → {"status":"ok","lessons":185} ; tests unitaires de split_lesson (normal / sans-exercice / sans-quiz / exercice-seul → tous OK).

Phase 9 — Refonte UI/UX (2026-09-19)

La page d’accueil et le template de leçon archivés codent en dur des assets de web.archive.org (CSS/JS Turbolinks, favicon morte) — fragiles et datés. Coquille refaite avec une UI moderne sans dépendance ; routes inchangées (/, /lesson/{cat}/{id}, redirection /lesson/{id}, /health, /static).

  • Nouveaux fichiers :
    • assets/css/style.css — design system : variables CSS, clair/sombre via prefers-color-scheme, responsive (sidebar → tiroir sous 900px, grille leçon/exercice → empilée sous 1150px), accessibilité focus-visible.
    • assets/js/app.js — suivi de progression (localStorage lj:v1:done), barres de progression par cours, compteur global « Done », réponse de quiz cachée sous un bouton « Reveal answer », raccourcis clavier (n suivant, p précédent, d marquer fait, Esc ferme le tiroir).
    • templates/base.html / home.html / lesson.html — accueil = hero + 22 cartes de cours ; leçon = fil d’Ariane, sélecteur de cours, sidebar complète du menu avec vrais titres, pagination précédent/suivant, cartes exercice/quiz.
  • src/main.py : les builders de métadonnées lisent les vrais titres depuis les H1 des .md parallèles (# The Shell → « The Shell »), construisent categories + find_lesson (index/total/prev/next) ; la route / rend le template ; montage /assets ajouté. Parsing intact.
  • Vérification : accueil 200 avec 22 .cat-card ; vrais titres dans la sidebar (« mv (Move) ») ; pagination correcte aux bords (« You’re at the start » / « Last lesson of the course ») et au milieu (history → cp → mv (Move)) ; cartes exercice/quiz rendues ; balayage 185/185 → 200 ; /assets/css/style.css + /assets/js/app.js → 200.
  • Commit 9cc827e poussé → sambaseness/linuxjourney-local compte désormais 3 commits (482be6f, eb57f65, 9cc827e).

3. Erreurs

  1. ❌ nohup … & n’a pas survécu à l’appel shell. Le sandbox Obsidian ramasse les processus enfants quand un appel d’outil se termine — nohup ignore seulement SIGHUP, il ne détache pas de la session. ✅ Correctif : setsid … </dev/null >> log 2>&1 & (nouvelle session, totalement détaché). Confirmé fonctionnel.
  2. ❌ pkill -f "uvicorn main:app" a tué mon propre shell. pkill -f matche la ligne de commande complète — et ma commande contenait le motif, donc le shell s’est suicidé (« (no output) », rien d’autre n’a tourné). ✅ Correctif : relancer en lançant un setsid propre ; ou utiliser l’astuce des crochets pkill -f '[u]vicorn main:app' pour que le motif littéral n’apparaisse plus dans la liste des processus.

4. Constatations de cause racine

  • Cycle de vie des processus sandbox : tout serveur durable doit être détaché par setsid (stdin et stdout détachés aussi) pour survivre à un appel d’outil. OpenClaw suit le même schéma (« gateway runs from the sandbox session and dies with it »).
  • Compatibilité Python 3.14 : la pile épinglée de 2022 s’installe et tourne sans problème sur 3.14 (pydantic 1.10 compilé en pur Python). Pas de bump de version nécessaire.
  • Le CWD d’exécution compte : src/main.py utilise des chemins relatifs (../lessons, ../templates), donc uvicorn doit être lancé depuis repo/src.

5. Tableau de statut

QuoiStatutNotes
Page d’accueil (/)✅ fonctionnetemplate refait : hero + 22 cartes de cours
Leçons (/lesson/{cat}/{id})✅ fonctionnentsidebar, contenu, exercices, quiz parsés par BeautifulSoup
Raccourci de redirection (/lesson/{id})✅ fonctionne307 → chemin complet
Assets statiques (CSS/JS/images)✅ fonctionnentmontés depuis lessons/
Leçon/catégorie inconnue✅ 404 (était 500)corrigé dans 482be6f
/health✅ fonctionne{"status":"ok","lessons":185}
Fork sambaseness/linuxjourney (contenu officiel)✅ synchronisé98f4eefe = tête upstream
sambaseness/linuxjourney-local (serveur)✅ en ligne sur GitHubprivé, 3 commits d’amélioration poussés
Persistance après redémarrage⚠️ pas encorepas d’unité systemd (nécessite un terminal hôte) — voir Travail futur

6. Tableau identifiants / config (source unique de vérité)

ÉlémentValeur
URLhttp://127.0.0.1:8080/
Port8080 (surcharge : PORT=… ./start.sh)
Dossier de clone/home/sambasene/dev/linuxjourney
venv~/dev/linuxjourney/.venv (python 3.14)
Log~/dev/linuxjourney/uvicorn.log
Démarrage~/dev/linuxjourney/start.sh (premier plan) / --daemon (arrière-plan)
Arrêtpkill -f '[u]vicorn main:app' (astuce des crochets, depuis un vrai terminal)
Upstreamgithub.com/itamarg365/linuxjourney @ 21d905a33b49c0494a866facecb8508f090dcfab
Licence du contenuCC BY-SA 4.0 (contenu Linux Journey) — usage local d’étude
Identifiantsaucun — pas d’auth, pas de DB

7. Blocs de config réutilisables

# start.sh
#!/usr/bin/env sh
set -e
DIR="$(cd "$(dirname "$0")" && pwd)"
PORT="${PORT:-8080}"
if [ "$1" = "--daemon" ]; then
  cd "$DIR/src"
  setsid "$DIR/.venv/bin/uvicorn" main:app --host 127.0.0.1 --port "$PORT" \
    </dev/null >> "$DIR/uvicorn.log" 2>&1 &
  echo "Linux Journey started in background → http://127.0.0.1:$PORT/ (log: $DIR/uvicorn.log)"
else
  cd "$DIR/src"
  exec "$DIR/.venv/bin/uvicorn" main:app --host 127.0.0.1 --port "$PORT"
fi

8. Dernier snapshot de vérification (2026-09-19)

Home  → 200
Lesson → 200 (titre : the-shell, menu latéral rendu)
Static CSS → 200
Log uvicorn : "INFO: Uvicorn running on http://127.0.0.1:8080"

9. Travail facultatif / futur

  • Service persistant : activer une unité systemd utilisateur (terminal hôte) : systemctl --user enable --now linuxjourney avec ExecStart=~/dev/linuxjourney/.venv/bin/uvicorn main:app --port 8080 WorkingDirectory=%h/dev/linuxjourney/src. → survit aux redémarrages.
  • Synchroniser le contenu officiel : labex-labs/linuxjourney (maintenu par LabEx) contient des leçons plus récentes/traduites ; à différer ou servir plus tard.
  • Idée « Linux Journey Rebuilt » (projet The Pseudo Line) : cette instance qui tourne est une base/référence parfaite pour un rebuild.

10. Leçons apprises

  1. Dans le sandbox Obsidian, les serveurs en arrière-plan doivent être détachés par setsid avec </dev/null + redirection de log ou ils meurent avec l’appel d’outil.
  2. Ne jamais pkill -f une chaîne littérale qui apparaît aussi dans sa propre ligne de commande — mettre des crochets ([u]vicorn). Précision : l’astuce des crochets ne protège que l’argument de pkill lui-même ; si le reste de la commande contient aussi le motif brut (ex. la ligne de lancement), le shell wrapper se fait quand même tuer. Tuer et lancer doivent vivre dans des appels d’outil séparés.
  3. « Repo de contenu officiel » ≠ « application exécutable » — pour Linux Journey le contenu et le serveur vivent dans deux repos différents.
  4. Les piles épinglées anciennes (fin 2022) s’installent encore proprement sur Python 3.14 dans un venv — essayer le pin avant de moderniser.
  5. Pousser un clone shallow vers un nouveau repo GitHub échoue (remote: did not receive expected object) — d’abord git fetch --unshallow.
  6. Les apps OAuth GitHub refusent les pushs touchant .github/workflows/* sans le scope workflow — nécessaire pour synchroniser le master du fork avec upstream.
  7. Des audits conscients de la langue : les résumés français sont ## Résumé, donc les grep de motifs anglais (## Summary) donnent des faux négatifs ; comparer les structures par langue, pas par titres anglais.
  8. La meilleure « première contribution » n’est pas toujours un PR de contenu : le cours officiel est en état quasi parfait (186×9, zéro dérive) ; les vrais bugs étaient dans l’app de service. Analyser avant d’écrire un PR — ne pas fabriquer de l’occupation.
  9. Pas de frontmatter, pas de métadonnées de leçon dans le HTML archivé — les vrais titres n’existent que dans les .md parallèles (H1 # The Shell). Pour les apps pilotées par des archives, dériver les métadonnées de navigation de la source la plus riche disponible (H1s, fichiers d’ordre), jamais des seuls noms de fichiers.